How it works
When and where @k8ordo/i18n reads the locale, and what it does and does not guarantee.
On this page
Where the locale is read
server locales.run('en', fn) → AsyncLocalStorage
paramsSchema accepts 'en' → AsyncLocalStorage
home() → reads the storage → 'Home'
browser location.pathname '/en/ui' → first segment 'en'
home() → reads the URL → 'Home'A message is handed the locale neither as an argument nor by a provider; it reads it when called. Where it reads from differs between the server and the browser, and which side it is on is decided once, when the module loads, by whether document is defined.
Server
On the server, the locale passed to run and the locale paramsSchema accepted are kept in AsyncLocalStorage, so concurrent renders never mix their locales. AsyncLocalStorage is reached through process.getBuiltinModule, with no import of node:async_hooks. So the same build loads in a browser unchanged.
The RSC environment and the SSR environment, where Client Components become HTML, are separate module graphs in one process. The storage lives on globalThis so that both read the same locale.
run sets the locale for fn and whatever it starts, and nothing else. paramsSchema sets it for the rest of the async context that called its validation. Whatever runs the schema decides which render runs in that context. For the order @k8ordo/framework runs schemas in, see @k8ordo/framework’s Parameters.
Browser
In the browser, a message reads the first segment of location.pathname below Vite’s base every time it is called.
Until the module defining the set has run in the browser, there is no telling whether a segment is a locale. Meanwhile a segment the message has no text for counts as no locale, and the first text written is returned. That is what keeps a 404 page on /fr/… from throwing.
Set registration
Besides returning the set, defineLocales registers the default locale and is on globalThis. message takes no set, so this is where it reads the default locale and is, the membership check, from.
The last definition wins, so that when a dev server evaluates i18n.ts again after a locale is added, the next message called reads the new set.
Pitfall
Define another set inside a test or a helper, and every message after it reads that set. For the fix, see Testing.
Messages and the bundle
src/components/save-button.tsx'use client';
import { save } from '../messages/form';
export function SaveButton() {
return <button type="submit">{save()}</button>;
The only message in the browser bundle
}message returns a function holding the text it was given, and nothing more. At the declaration it registers nothing and checks nothing, so a bundler drops a message nothing calls as dead code.
The browser bundle carries only the messages that 'use client' modules and their imports reference by name, each with its text in every locale. Text only a Server Component renders stays out, whichever module declares it.
Three more decisions keep unused messages removable.
- Messages are individual exports, not entries in one dictionary object. A dictionary is kept or dropped whole.
- A missing locale is not checked at the declaration. A declaration that could throw counts as a side effect to the bundler, which then keeps unused messages too. A gap the types did not catch fails where the message is read, with
TypeError: message: no text for "en" in ["ja"]. messagedoes not take the locale set as an argument. As a method such aslocales.message(…), it would be a function another call (defineLocales) returned. The bundler does not look inside such a function, so unused messages would stay.
Guarantees
paramsSchemarefuses a locale outside the list. In the browser, once the set is defined, messages andgetLocale()use the default locale when the first segment of the URL is outside the list.- A locale
runset is read only insidefnand whatever it starts. It is never used for another request being handled at the same time. - On a server runtime without
AsyncLocalStorage,paramsSchemaandrunthrow. They never go on to render in the default locale. - Messages and
getLocale()are not hooks. They can be called in a Server Component or a Client Component, in an event handler, or inside another message’s function. - Declaring a message has no side effect, so a bundler can drop a message nothing calls.
- A message missing a locale is a type error once
Registercarries the locale type. A gap that gets past the types throws aTypeErrorwhere the message is read, and never returnsundefined. dateTimeFormatwrites a date in the locale’stimeZone, on the server and in every browser.
Not guaranteed
- Messages and
getLocale()do not subscribe to the URL. In the browser, they read it at the moment they are called. - A string a message returned does not change when the locale does. Called at the top level of a module, it stays in the locale of the moment the module loaded.
- On the server, a message called where neither
paramsSchemanorrunhas set a locale returns the default locale’s text. It does not read the request’s URL or headers. paramsSchemasets the locale for the rest of the async context that called its validation. Keeping each request in a context of its own is up to whatever calls the schema.- A message a Client Component uses ships to the browser with its text in every locale. The bundle is not split per locale.
- A date not written through
dateTimeFormat, and a time relative to now, can differ between the server and the browser.