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.ts
import 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.json
apps/web/messages/it/marketing.json
packages/i18n/src/messages/it/common.json

With 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 defaultLocale value, 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

  1. pnpm dev, then check the console: no i18n: warnings about the locale.

  2. *_translations_stats (MCP) shows coverage for the new locale in both folders.

  3. Run the production Worker with pnpm preview (it builds first), and set URL to the address it prints.

  4. 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[^>]*>'
  5. 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 defaultLocale on 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 →