Internationalization
Fondu has no translations of its own: a page's URL says its language, with an optional segment, and a library has the messages. This page uses Paraglide JS: messages compiled to typed functions, the same in the browser and on the server, no provider. i18next works too. The demo has a page in three languages.
URLs
The base language has no prefix, the others have one:
| File | URLs |
|---|---|
routes/[[locale]]/index.tsx | /, /de, /fr |
routes/[[locale]]/about.tsx | /about, /de/about, /fr/about |
routes/admin/index.tsx | /admin: the base language only |
params lists the prefixes, so /xx/about is a 404 and a route such as [slug].tsx keeps the other URLs:
// app/routes/[[locale]]/_middleware.ts
import { baseLocale, locales } from '#/paraglide/runtime.js'
export const params = { locale: locales.filter((locale) => locale !== baseLocale) }/en/about is a 404 too: the base language's URL has no prefix.
Paraglide
npx @inlang/paraglide-js@latest init --outdir ./app/paraglide sets it up: the messages in messages/, the project
in project.inlang/, the Vite plugin, and allowJs in tsconfig.json (the messages compile to JavaScript). The
plugin's options:
// vite.config.ts
paraglideVitePlugin({
project: './project.inlang',
outdir: './app/paraglide',
strategy: ['url', 'baseLocale'], // the URL decides the language
trailingSlash: 'never', // /de, as Fondu's URLs; 'always' with createApp({ trailingSlash: 'append' })
}),Its middleware sets the language of each request, for the messages and getLocale() on the server:
// app/routes/_middleware.ts
import { defineMiddleware } from 'fondu'
import { paraglideMiddleware } from '#/paraglide/server.js'
export default defineMiddleware((c, next) => {
// the path as the routes read it (percent-decoded): Paraglide sees the same language. No body: Paraglide reads
// the URL and the headers only, and an upload isn't held twice
const url = new URL(c.req.url)
url.pathname = c.req.path
return paraglideMiddleware(new Request(url, { headers: c.req.raw.headers }), async () => {
await next()
return c.res
})
})In routes/_middleware.ts, it runs for every request, so the 404 page is in the URL's language too. It keeps the
language in AsyncLocalStorage: Node and Bun have it, and Cloudflare Workers with Node.js compatibility, on from
compatibility date 2026-08-04 (before: "compatibility_flags": ["nodejs_compat"] in wrangler.jsonc).
Messages
Each language has a file, messages/de.json for German: { "greeting": "Hallo, {name}!" }. m.greeting({ name })
is the same function in a page and on the server: the URL's language in the browser, the request's on the server.
import { m } from '#/paraglide/messages.js'
export default function Welcome({ name }: { name: string }) {
return <h1>{m.greeting({ name })}</h1>
}// an action
flash(c, { message: m.saved() })
// a validation message: a function, called as the body is checked (a message called as the module loads would be
// in the base language)
const name = z.string().check(z.minLength(1, { error: () => m.name_required() }))Where no request says the language (a scheduled task, an email sent later, a callback URL without the prefix), pass
it: m.welcome({ name }, { locale }).
Links
href() in the current language, typed as href():
// app/lib/i18n.ts
import { href } from 'fondu/client'
import { localizeHref } from '#/paraglide/runtime.js'
/** `localizedHref('/about')` is `/de/about` on a German page */
export const localizedHref: typeof href = (path, ...params) => localizeHref(href(path, ...params))For links, form actions and redirects: <a href={localizedHref('/about')}>,
<form action={localizedHref('/contacts?create')}>, c.redirect(localizedHref('/contacts'), 303). An action's URL
has the language, so its flash and its errors are in it; back(c) returns to the page's own URL.
Switching
The other language is another document, as <html lang> says it: remember it with Paraglide's cookie, then load
its URL with loadDocument() (a plain navigation would keep the document's lang):
import { href, loadDocument } from 'fondu/client'
const pick = (locale: Locale) => {
setLocale(locale, { reload: false })
loadDocument(localizeHref(href('/about'), { locale })) // /about becomes /de/about
}The document says the language:
// app/document.tsx
<html lang={getLocale()}>Search engines
Each page lists its URL in every language, itself included, as full URLs: what Google reads.
// app/routes/[[locale]]/about.tsx, in the loader
const url = (locale: Locale) => new URL(localizeHref('/about', { locale }), c.req.url).href
const alternates = { ...Object.fromEntries(locales.map((l) => [l, url(l)])), 'x-default': url(baseLocale) }// app/routes/[[locale]]/about.tsx, in the page
{Object.entries(alternates).map(([lang, href]) => (
<link key={lang} rel="alternate" hrefLang={lang} href={href} />
))}Static pages: export const prerender = () => params.locale.map((locale) => ({ locale })) next
to params writes each page in each language; the base language's comes with them.
The home page in the visitor's language
The URL decides, so a visitor opening / reads the base language and picks theirs. To open the home page in the
language picked, or else the browser's:
// app/routes/_middleware.ts, before Paraglide's middleware; strategy: ['url', 'cookie', 'baseLocale'] in
// vite.config.ts, so setLocale() keeps the choice in a cookie (the URL still decides the language)
if (c.req.path === '/' && c.req.method === 'GET') {
const locale = toLocale(getCookie(c, cookieName)) ?? extractLocaleFromHeader(c.req.raw)
if (locale && locale !== baseLocale) {
c.header('Vary', 'Accept-Language, Cookie')
return c.redirect(localizeHref('/' + new URL(c.req.url).search, { locale }), 302)
}
}The home page only, so a shared link opens as it was sent; a page load or a navigation, so a link to / inside the app
goes there too; and the language from the cookie or the header is one of the app's (toLocale,
extractLocaleFromHeader) before it is used. Add the Vary header to the home page's own response too, for caches,
and don't prerender it: a static file is served before any middleware. getCookie is hono/cookie's; the rest is
#/paraglide/runtime.js.
Type checking
The compiled messages aren't committed (Paraglide ignores them), so a type check without a dev server or a build first compiles them:
{
"scripts": {
"typecheck": "paraglide-js compile --project ./project.inlang --outdir ./app/paraglide && tsc --noEmit"
}
}i18next
With i18next and react-i18next, messages are looked up by key at runtime, through a provider, with no AsyncLocalStorage:
- The language:
c.req.param('locale') ?? 'en'inroutes/[[locale]]/_middleware.ts, with the sameparams. - On the server: an instance per request,
i18next.cloneInstance({ lng }), itstinc.set()for actions. - The messages: shared with the pages:
share(c, { locale, messages: () => resources[locale] }). - In the browser:
app/routes/_layout.tsxmakes an instance of the shared messages, once per language, and wraps the page in<I18nextProvider>:i18next.createInstance(), theninit({ lng, resources, initAsync: false, interpolation: { escapeValue: false } })(React escapes the values already).