# Internationalization

> How the kit resolves a locale, where messages live, which files are yours, and how to translate your first string.

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

---

Every request gets one supported locale. Components and server code read messages through [use-intl](https://use-intl.dev/), re-exported by `@kit/i18n`. Kit strings and your strings live in separate folders, so kit updates don't collide with your copy. The kit ships English only; adding a locale is a config line plus message files.

## How It Works

1. **`middleware/05.locale.ts`** resolves the locale with `resolveLocale()`, puts it in shared data (`useShared().locale`, `c.get('shared').locale`) and sets `<html lang>`.
2. **`pages/layout.tsx`** wraps the tree in `I18nProvider` with the config, the locale and `getLocaleMessages(locale)`.
3. **Components** call `useTranslations('<namespace>')` or render `<Trans i18nKey="<namespace>.<key>" />`.
4. **Server code** (`head`, actions, handlers) calls `getServerTranslator({ c, namespace })`. Code without a request (queues, crons, emails) calls `getLocaleTranslator({ locale, namespace })` with a locale you stored.

The locale flows one way: middleware resolves it once and both SSR and the client read it from shared data. The client never re-detects, so hydration always matches the server HTML.

## Locale Resolution

| Order | Source | Notes |
|---|---|---|
| 1 | URL prefix (`/it/pricing`) | Non-default locales only. See [URL Prefixes](./url-prefixes). |
| 2 | `locale` cookie | Ignored unless it's a configured locale. |
| 3 | `Accept-Language` header | Highest `q` first; full tag before base language (`pt-BR`, then `pt`), any case. Returns the configured spelling. |
| 4 | `defaultLocale` | From `apps/web/config/i18n.config.ts`. |

Only values in `locales` ever reach `<html lang>` or shared data; a forged cookie or header falls through to the next source.

## Where Messages Live

Messages are JSON files named `<locale>/<namespace>.json`. The file name is the namespace.

```
packages/i18n/src/messages/en/common.json   kit namespaces (404 page, theme, spinner, copy-to-clipboard…)
packages/i18n/src/messages/en/organizations.json, invitations.json   kit organization UI
packages/i18n/src/messages/en/content.json   kit docs and content pager labels
apps/web/messages/en/app.json               your namespaces (any file name)
apps/web/messages/en/marketing.json
apps/web/messages/en/roles.json             role names (+ roles.server.json for emails)
```

Both folders are loaded with an eager `import.meta.glob`, so a new file is picked up with no code. A key is addressed as `<namespace>.<key.path>`: `common.notFound.title`, `app.routes.dashboard`.

**Messages are bundled.** The same map is used by the server and shipped to the browser with the JS. Every configured locale is bundled. Messages are public: never put a secret, internal URL or unreleased name in a message file. The one exception is a `<namespace>.server.json` file (email copy, admin copy), which stays on the server ([Managing Translations](./managing-translations)).

## Files You Own vs Files the Kit Owns

| Yours (edit freely) | The kit's (avoid editing; updates land here) |
|---|---|
| `apps/web/config/i18n.config.ts` (locales, default) | `packages/i18n/src/**` (library and kit messages) |
| `apps/web/messages/**` (your namespaces) | `apps/web/config/i18n.messages.ts`, `apps/web/lib/i18n.client.ts`, `apps/web/lib/i18n.server.ts` |
| `apps/web/pages/layout.tsx` (mounts `I18nProvider`) | `apps/web/middleware/05.locale.ts` |
| | `packages/ui/src/makerkit/trans.tsx` |

Changing kit wording means editing a kit message file. That's a known merge point: see [Managing Translations](./managing-translations#overriding-kit-wording).

## Package Exports

| Import | Use in | Exports |
|---|---|---|
| `@kit/i18n` | anywhere | `I18nConfig`, `LOCALE_COOKIE`, `resolveLocale`, `createMessages`, `localizeHref`, `getLocaleFromPath`, `stripLocale`, `isApiPath` |
| `@kit/i18n/kit-messages` | the app's messages config | `kitMessages` (Vite-only: `import.meta.glob`; kept off the root so code loaded outside Vite, like `db/seed.ts`, can import `@kit/i18n`) |
| `@kit/i18n/react` | components | `I18nProvider`, `useTranslations`, `useFormatter`, `useLocale`, `LocalizedLink`, `useLocalizeHref`, `useI18nConfig` |
| `@kit/i18n/server` | server code | `getTranslator` (prefer the app's `getServerTranslator` / `getLocaleTranslator`) |
| `@kit/ui/trans` | components | `Trans` |

Import hooks from `@kit/i18n/react`, never from `use-intl` directly.

## Quick Start

Add a key to your namespace:

```json
// apps/web/messages/en/app.json
{
  "billing": {
    "title": "Billing",
    "seats": "{count, plural, one {# seat} other {# seats}}"
  }
}
```

Use it:

```tsx
import { useTranslations } from '@kit/i18n/react';

export function BillingHeader({ seats }: { seats: number }) {
  const t = useTranslations('app.billing');

  return (
    <h1>
      {t('title')} · {t('seats', { count: seats })}
    </h1>
  );
}
```

## Common Pitfalls

- **Hardcoded user-visible strings.** Every label, title, error and `alt` goes through a message key, including in server code.
- **A namespace named like a kit namespace** (`apps/web/messages/en/common.json`) makes every page fail to load. Pick another name.
- **Kit components outside `I18nProvider`.** The spinner, theme toggles and copy-to-clipboard call `useTranslations` and throw without a provider. The root layout provides one; content rendered outside it (a separate React root, a test render) needs its own `I18nProvider`.
- **Cached pages and detection.** ISR serves cookieless visitors the cached HTML, rendered in whatever locale the first request resolved. Use [URL prefixes](./url-prefixes) for cached localized pages; a `Vary: Accept-Language` header disables Void ISR for that page.
- **`apps/web/public/500.html`** is static English by design: it's served when the Worker can't render.

## Topics

1. [Using Translations](./using-translations)
2. [Managing Translations](./managing-translations)
3. [Adding a Locale](./adding-a-locale)
4. [URL Prefixes](./url-prefixes)

App configuration lives in the [Configuration documentation](../configuration/overview).

---

**Next:** [Using Translations →](./using-translations)
