@k8ordo/i18n

Troubleshooting

Common symptoms, their causes and their fixes. To look up an error, search this page for its wording.

On this page

no text for "en"

Cause

A message has no text for that locale. It happens to a message written before Register carried the locale type, forced through with as, or written in JavaScript.

Fix

The error names the missing locale and the ones the message has. Add the missing text. With the locale type in Register, this is a type error at the declaration.

A missing locale that is not a type error

Cause

Register does not carry the locale type. Until it does, RegisteredLocale is string, and any combination of locales passes.

Fix

Write Register with declare module '@k8ordo/i18n' in the module that defines the locale set, and check that the module is part of the TypeScript project. In an @k8ordo/framework app Register is generated; for when, see @k8ordo/framework’s Routing.

Text that does not change with the language

Cause

The message is called at module scope and kept as a string. A message reads the locale at the moment it is called, so the string stays in the locale current when the module loaded.

Fix

Keep the Message itself, and call it in the component that renders it.

A date that differs between the server and the browser

Cause

A new Intl.DateTimeFormat without a timeZone formats in the runtime’s own time zone. When the server and the browser are in different time zones, the date shifts and hydration disagrees.

Fix

Format it with locales.dateTimeFormat. It uses the locale’s timeZone, so the server and the browser agree. Anything that should follow the visitor’s own zone belongs in a part that renders only in the browser.

Pages rendered in the default locale

Cause

On the server, neither run nor paramsSchema has set a locale. Messages on the server do not read the URL, so even /en/… renders in the default locale.

Fix

Wrap the code that calls messages in locales.run, or validate the locale with paramsSchema before it. In @k8ordo/framework, export paramsSchema from the [locale] layout. See @k8ordo/framework’s Routing.

no AsyncLocalStorage to scope a locale to

Cause

The server runtime has no process.getBuiltinModule, so AsyncLocalStorage cannot be reached. Without it, the locale cannot be scoped to an async context, so run and paramsSchema fail with this error instead of going on in the default locale.

Fix

Run on a runtime with process.getBuiltinModule('node:async_hooks'). Node 24 has it.

in the browser the URL is the locale

Cause

locales.run was called in a browser. A test environment that defines document, such as jsdom or happy-dom, counts as one.

Fix

In a browser, change the locale by navigating to that locale’s URL. In a test, change the pathname with history.replaceState. See Testing.

@k8ordo/ui components left in English

Cause

The module that defines the locale set is not loaded in the browser.

Fix

Import locales from a Client Component. See the @k8ordo/ui guide to i18n.

@k8ordo/ui: no built-in text for "fr"

Cause

No dictionary other than ja and en is registered with @k8ordo/ui.

Fix

Call registerMessages('fr', fr) from @k8ordo/ui/i18n in the module that defines the locale set. See the @k8ordo/ui guide to i18n.

A switcher URL with two locales

Cause

A pathname that still has its locale segment was passed to localize. localize does not check whether one is already there.

Fix

Take the segment off with delocalize first, and pass its pathname to localize.

A 404 page left in the default language

Cause

HTML rendered once, such as the 404.html a static host serves, is returned for every URL. Text a Server Component rendered stays in the locale it was rendered in.

Fix

Render text that should follow the visitor’s locale in the browser, after hydration. @k8ordo/framework hydrates 404.html as written and then renders it again at the visitor’s URL, so a Client Component’s messages come out in the visitor’s locale. See @k8ordo/framework’s Deployment.

A message that cannot be passed to a Client Component

Cause

A message is a function, and React cannot send a function to a Client Component as a prop.

Fix

Pass the string you get by calling it, or import the message in the Client Component and call it there.

Form errors in the wrong language

Cause

zod was given a string instead of the message, or formFields is called at module scope.

Fix

For the fix, see the @k8ordo/form guide to Errors.

k8ordo

React libraries that use Baseline features without holding back.