@k8ordo/i18n

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

text
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.

Warning

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"].
  • message does not take the locale set as an argument. As a method such as locales.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

  • paramsSchema refuses a locale outside the list. In the browser, once the set is defined, messages and getLocale() use the default locale when the first segment of the URL is outside the list.
  • A locale run set is read only inside fn and whatever it starts. It is never used for another request being handled at the same time.
  • On a server runtime without AsyncLocalStorage, paramsSchema and run throw. 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 Register carries the locale type. A gap that gets past the types throws a TypeError where the message is read, and never returns undefined.
  • dateTimeFormat writes a date in the locale’s timeZone, 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 paramsSchema nor run has set a locale returns the default locale’s text. It does not read the request’s URL or headers.
  • paramsSchema sets 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.
k8ordo

React libraries that use Baseline features without holding back.