Internationalization

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

Every request gets one supported locale. Components and server code read messages through use-intl, 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

OrderSourceNotes
1URL prefix (/it/pricing)Non-default locales only. See URL Prefixes.
2locale cookieIgnored unless it's a configured locale.
3Accept-Language headerHighest q first; full tag before base language (pt-BR, then pt), any case. Returns the configured spelling.
4defaultLocaleFrom 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).

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.

Package Exports

ImportUse inExports
@kit/i18nanywhereI18nConfig, LOCALE_COOKIE, resolveLocale, createMessages, localizeHref, getLocaleFromPath, stripLocale, isApiPath
@kit/i18n/kit-messagesthe app's messages configkitMessages (Vite-only: import.meta.glob; kept off the root so code loaded outside Vite, like db/seed.ts, can import @kit/i18n)
@kit/i18n/reactcomponentsI18nProvider, useTranslations, useFormatter, useLocale, LocalizedLink, useLocalizeHref, useI18nConfig
@kit/i18n/serverserver codegetTranslator (prefer the app's getServerTranslator / getLocaleTranslator)
@kit/ui/transcomponentsTrans

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

Quick Start

Add a key to your namespace:

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

Use it:

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 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
  2. Managing Translations
  3. Adding a Locale
  4. URL Prefixes

App configuration lives in the Configuration documentation.


Next: Using Translations →