Using i18n

Render a string

app.get("/board", (c) => c.html(c.var.t.t("api/board.title")))

c.var.t is on every request whether or not you composed the capability — core seeds it with each composed capability’s English. Composing i18n replaces it with a translator that negotiated the reader’s locale.

Add a language

Two steps — and serving a second language walks them with the rest of the setup around them:

i18n({
  supportedLocales: ["en", "es"],
  messages: {
    es: { "api/board.title": "Tablero" },
  },
})

Ship the least specific tag that is true — es, not es-ES. Every option here is in the reference, and the browser half negotiates on its own chain. The catalog locale falls back and the formatting locale does not, so a regional reader already gets regional dates from a plain es catalog.

The default locale must be one of the supported ones; the config refuses otherwise.

Override one kit sentence

The same messages field. One entry, one key — overriding one sentence is the whole procedure:

messages: {
  en: { "auth/sign_in.title": "Welcome back to Board." },
}

Every key you did not mention keeps flowing from the package, because the merge is per key. Passing a whole locale object instead is the fork this design exists to avoid.

Declare your own keys

Under your own app capability’s name — api in a Worker scaffolded as apps/api — contributed through its messages like any other capability’s. api/board.title is yours. A key under auth/ is refused with the domain named.

Plurals

t.plural("api/board.entries", count)

It looks up <key>.<category> and falls back to <key>.other. Write the categories the language actually has — English needs one and other; other languages need more, and the fallback covers a category you have not written yet.

Formatting

formatNumber, formatCurrency, formatDate, formatList and formatRelativeTime all run against formattingLocale, which is the reader’s full tag rather than the catalog’s.

So es-AR gets Argentine formatting from an es catalog, with nobody writing an es-AR anything.

Render an error a client can translate

t.maybe(payload.code, payload.params) ?? payload.message;

maybe, not t — t is total and never misses, so it can never fall through to the English the server sent. See the translator interface.

Set lang and dir on the document

Read c.var.locale rather than t — it carries the tags themselves and the direction:

const { formattingLocale, direction } = c.var.locale ?? {};

null means nothing was negotiated, which is a different fact from the default was chosen, and it is what a project with no i18n composed looks like.

Localize your own copy before you enqueue an email

The kit translates the half it wrote. A template whose words arrive as payload is only as localized as your payload.

An operational notice enqueued at locale es takes its severity label from the Spanish catalog and your summary straight from your payload — delivering a Spanish label in front of an English sentence. That is correct behavior, and it is a surprise unless somebody says it out loud.

So look your summary up first, under your own domain, and hand the rendered string to the enqueue along with the same locale. A catalog cannot translate a sentence it has never seen.

In the browser

useNegotiatedLocale walks the browser chain and useTranslator gives you the same object. Pass persist so a signed-in reader’s choice reaches their account rather than only this device.

Pass the hook’s source straight to TranslatorProvider, null included, and mount the provider from the first render. source is null until the locale’s catalog has loaded, and stays null in a project with no i18n composed. A provider holding null reads exactly as no provider, so each screen shows its own English meanwhile. A provider that wraps the app only once the catalog lands changes the tree above every screen, so React remounts them all and each loses its state, a router’s current route included. The pithy-locale.tsx that pithy ui add scaffolds, for React and for React Native, already does this.

Screens are fetched one locale at a time as their own chunk, so adding a language does not grow the bundle every reader downloads.

On a phone

A React Native app runs the same chain from what a phone holds. Pass nativeLocaleEnvironment from @pithy-sh/i18n/src/native/environment as useNegotiatedLocale’s environment, which the pithy-locale.tsx that pithy ui add react-native scaffolds does on a device. The device’s preferred languages come from expo-localization, in the order the reader set them, and are followed when they change while the app runs. A choice is kept in AsyncStorage under the same storageKey; a language is not a secret, so it is not kept in the secure store. There is no query string and no server-rendered lang, so those links answer nothing. Nothing is negotiated until the stored choice has been read, so a remembered language is not preceded by a flash of another.

Direction goes through I18nManager, and React Native applies it only at the next launch. So a choice that lays out the other way from the one the app started in sets reloadRequired on the hook’s answer, and the scaffolded app says to restart rather than flip half a layout. A browser never sets it. The web build of the same app negotiates as a browser does.

ESC