Using Translations
Translate strings in components, head, actions, handlers and background jobs; format dates and numbers; handle missing keys.
Components use useTranslations or Trans. Server code uses a translator from apps/web/lib/i18n.server.ts. All of them read the same messages and render a missing key the same way.
This page is part of the Internationalization documentation.
In Components
import { useTranslations } from '@kit/i18n/react';export function NotFound() { const t = useTranslations('common'); return <h1>{t('notFound.heading')}</h1>;}- The argument is a namespace, optionally with a path:
useTranslations('common.theme')thent('light'). - Without an argument, pass full keys:
t('common.notFound.title'). - Values use ICU syntax:
"Hello {name}"→t('hello', { name }); plurals and selects work the same way.
Rich Text
Tags in a message are mapped to React through t.rich, never to raw HTML:
// apps/web/messages/en/app.json{ "apiExample": "API example: <link>/api/hello</link>" }const t = useTranslations('app');<p> {t.rich('apiExample', { link: (chunks) => <a href="/api/hello">{chunks}</a>, })}</p>;Never render a message with dangerouslySetInnerHTML: messages pass through translators and tools, and tag functions keep them inert.
The Trans Component
Trans from @kit/ui/trans renders one key in JSX. Use it where a key is data (a nav label, a config value) rather than written in the component.
import { Trans } from '@kit/ui/trans';<Trans i18nKey="common.theme.light" /><Trans i18nKey="hello" ns="common" values={{ name: 'Ada' }} /><Trans i18nKey="app.apiExample" components={{ link: <a href="/api/hello" /> }}/>| Prop | Purpose |
|---|---|
i18nKey | namespace.key.path. The first segment is the namespace unless ns is set. |
ns | Namespace, when i18nKey doesn't start with one. |
values | Interpolated values. |
components | Tag → function (chunks) => node, or an element that wraps the chunks. |
defaults | Rendered when the key is missing (no dev warning). |
Keys use dots only. A colon key (auth:terms, from i18next-style kits) is treated as a missing key.
Navigation Labels
Labels in apps/web/config/navigation.config.tsx are message keys (app.routes.dashboard) from apps/web/messages/en/app.json. Render them with defaults so a plain-text label still works:
<Trans i18nKey={item.label} defaults={item.label} />In head, Actions and Handlers
getServerTranslator reads the locale the middleware resolved for this request:
// apps/web/pages/[...slug].server.tsimport { defineHead } from 'void';import { getServerTranslator } from '#/lib/i18n.server.ts';export const head = defineHead((c) => { const t = getServerTranslator({ c, namespace: 'common' }); return { title: t('notFound.title') };});Use the same call in a page action or a defineHandler route for error messages and toasts returned to the client.
Without a Request: Queues, Crons, Emails
There's no request, so there's no detected locale. Store the user's locale when you have a request (c.get('shared').locale), and pass it later:
import { getLocaleTranslator } from '#/lib/i18n.server.ts';const t = getLocaleTranslator({ locale: job.locale, namespace: 'app' });const subject = t('emails.invite.subject', { org: job.orgName });An unconfigured locale falls back to defaultLocale messages for every key.
The Current Locale
| Where | How |
|---|---|
| Component | useLocale() from @kit/i18n/react |
| Loader, action, handler | c.get('shared').locale |
Dates and Numbers
import { useFormatter } from '@kit/i18n/react';const format = useFormatter();format.dateTime(createdAt, { dateStyle: 'medium' });format.number(amount, { style: 'currency', currency: 'EUR' });format.relativeTime(createdAt);I18nProvider formats in UTC unless given a timeZone; the root layout doesn't pass one. For a user's time zone, pass timeZone to I18nProvider in pages/layout.tsx, or pass timeZone per call.
Missing Keys
A missing key never crashes. It renders as its path (common.notFound.title) and, in development only, logs i18n: <use-intl message> to the console. A key missing in a non-default locale falls back to the defaultLocale value first, so the path only shows when the default lacks it too.
Common Pitfalls
- Concatenating translated fragments (
t('hello') + name). Put the variable in the message:"Hello {name}". - Calling a translator at module top level. The locale is per request; call it inside the component,
head, action or handler. - Translating server errors on the client. Return the translated message from the action, or return a key and translate it in the component; don't send raw English from the server.
- A kit component in a separate React root (a portal mounted with
createRoot, a test render) throws: it needs its ownI18nProvider. - Dates rendered in UTC when a user expects local time. Pass
timeZone.
Next: Managing Translations →