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
middleware/05.locale.tsresolves the locale withresolveLocale(), puts it in shared data (useShared().locale,c.get('shared').locale) and sets<html lang>.pages/layout.tsxwraps the tree inI18nProviderwith the config, the locale andgetLocaleMessages(locale).- Components call
useTranslations('<namespace>')or render<Trans i18nKey="<namespace>.<key>" />. - Server code (
head, actions, handlers) callsgetServerTranslator({ c, namespace }). Code without a request (queues, crons, emails) callsgetLocaleTranslator({ 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. |
| 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 UIpackages/i18n/src/messages/en/content.json kit docs and content pager labelsapps/web/messages/en/app.json your namespaces (any file name)apps/web/messages/en/marketing.jsonapps/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
| 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:
// 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
altgoes 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 calluseTranslationsand throw without a provider. The root layout provides one; content rendered outside it (a separate React root, a test render) needs its ownI18nProvider. - 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-Languageheader disables Void ISR for that page. apps/web/public/500.htmlis static English by design: it's served when the Worker can't render.
Topics
App configuration lives in the Configuration documentation.
Next: Using Translations →