Adding a Locale
Add a language with one config line and message files, offer a language picker, and verify it before shipping.
A locale is a config entry plus message files. There's no env variable for it: message files must be in the build.
This page is part of the Internationalization documentation.
1. Add It to the Config
// apps/web/config/i18n.config.tsimport type { I18nConfig } from '@kit/i18n';export const i18nConfig = { locales: ['en', 'it'], defaultLocale: 'en',} satisfies I18nConfig;Use the tag you want in <html lang> and in URLs: it, pt-BR. Accept-Language matches the full tag first, then the base language, ignoring case.
2. Add Message Files
Copy each namespace you translate into a folder named after the locale:
apps/web/messages/it/app.jsonapps/web/messages/it/marketing.jsonpackages/i18n/src/messages/it/common.jsonWith MCP: app_translations_add_locale and kit_translations_add_locale create empty files for every namespace, then *_translations_update fills them.
- Fallback is per key. Any key the locale lacks renders the
defaultLocalevalue, so you can ship a partial translation. - Both folders are optional per locale. With only
apps/web/messages/it/, your pages are Italian and the kit shell (404 page, theme menu) stays English. - A configured locale with no files in either folder logs a dev warning and renders the default locale.
3. Offer a Language Picker
@kit/ui/language-selector exports LanguagePreferenceCard (a settings card) and LanguageSelector (a select). Both read the locales from I18nProvider and render nothing with one locale, so they're safe to mount before you add a locale. The marketing footer already shows LanguageSelector (apps/web/components/marketing-preferences.tsx). The app has none: add one to a settings page of yours:
import { LanguagePreferenceCard } from '@kit/ui/language-selector';<LanguagePreferenceCard />;Choosing a language sets the locale cookie (1 year, path /, SameSite=Lax) and loads the current page in that language: /pricing → /it/pricing, /it/pricing → /pricing for the default locale, query and hash kept; /api URLs are never prefixed. Languages are listed by their native names (Italiano, Deutsch); up to three show as buttons, more as a select.
4. URL Prefixes
With a second locale, any page also answers at /it/…, while bare URLs follow the visitor's cookie. Nothing to configure; link public pages with LocalizedLink so their URLs stay localized: see URL Prefixes.
5. Verify
pnpm dev, then check the console: noi18n:warnings about the locale.*_translations_stats(MCP) shows coverage for the new locale in both folders.Run the production Worker with
pnpm preview(it builds first), and setURLto the address it prints.Request a page with the cookie and with the header, and check
<html lang>and the text:curl -s -H 'Cookie: locale=it' "$URL/" | grep -o '<html[^>]*>'curl -s -H 'Accept-Language: it-IT,it;q=0.9' "$URL/" | grep -o '<html[^>]*>'Open a prefixed URL (
/it/) and a 404 (/it/missing) in the browser.
Removing a Locale
Remove it from locales, then delete its folders (*_translations_remove_locale). A user whose cookie holds the removed locale falls through to Accept-Language, then the default.
Common Pitfalls
- Message files without the config line. The folder is ignored (dev warning:
"fr" is not in i18nConfig.locales). - Changing
defaultLocaleon a live site. Every unprefixed URL changes language, and prefixed links to the new default start redirecting. Treat it as a URL migration. - Bundle size. Every configured locale is bundled into the server and the browser today. Many large locales need per-locale lazy loading in
apps/web/config/i18n.messages.ts(a kit file). - Right-to-left languages.
<html dir>isn't set and layouts aren't mirrored; RTL needs its own work.
Next: URL Prefixes →