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.