# Using Translations

> Translate strings in components, head, actions, handlers and background jobs; format dates and numbers; handle missing keys.

*Canonical: https://makerkit.dev/docs/void-cloudflare/internationalization/using-translations*

---

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](./overview).

## In Components

```tsx
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:

```json
// apps/web/messages/en/app.json
{ "apiExample": "API example: <link>/api/hello</link>" }
```

```tsx
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.

```tsx
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:

```tsx
<Trans i18nKey={item.label} defaults={item.label} />
```

## In `head`, Actions and Handlers

`getServerTranslator` reads the locale the middleware resolved for this request:

```ts
// 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:

```ts
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

```tsx
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 →](./managing-translations)
