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') then t('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" /> }}
/>
PropPurpose
i18nKeynamespace.key.path. The first segment is the namespace unless ns is set.
nsNamespace, when i18nKey doesn't start with one.
valuesInterpolated values.
componentsTag → function (chunks) => node, or an element that wraps the chunks.
defaultsRendered 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.

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.ts
import { 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

WhereHow
ComponentuseLocale() from @kit/i18n/react
Loader, action, handlerc.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 own I18nProvider.
  • Dates rendered in UTC when a user expects local time. Pass timeZone.

Next: Managing Translations →