# Adding a Locale

> Add a language with one config line and message files, offer a language picker, and verify it before shipping.

*Canonical: https://makerkit.dev/docs/void-cloudflare/internationalization/adding-a-locale*

---

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](./overview).

## 1. Add It to the Config

```ts
// 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:

```tsx
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](./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:

   ```bash
   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 →](./url-prefixes)
