# Managing Translations

> Add strings and namespaces, change kit wording, and manage message files with the MCP tools.

*Canonical: https://makerkit.dev/docs/void-cloudflare/internationalization/managing-translations*

---

Your strings go in `apps/web/messages/<locale>/<namespace>.json`. Kit strings live in `packages/i18n/src/messages/<locale>/<namespace>.json`. Both are plain JSON, loaded with no code.

This page is part of the [Internationalization documentation](./overview).

## Which Folder

| String | Folder | Namespace |
|---|---|---|
| Your features, pages, nav labels, your emails | `apps/web/messages/` | `app`, `home`, or a new one per feature (`billing`, `projects`) |
| Kit components (404 page, theme, spinner, copy-to-clipboard, OAuth logos) | `packages/i18n/src/messages/` | `common` |
| Kit auth forms and auth emails | `packages/i18n/src/messages/` | `auth` |

Add new strings to your folder. Edit the kit folder only to change kit wording.

## Adding a String

1. Pick the namespace (the file) and a key. Nest by feature or screen: `billing.plan.title`, not `billingPlanTitle`.
2. Add it to the `defaultLocale` file, and to each other locale's file if it has one.
3. Use it: `useTranslations('app')` then `t('billing.plan.title')`, or `<Trans i18nKey="app.billing.plan.title" />`.

```json
// apps/web/messages/en/app.json
{
  "routes": { "dashboard": "Dashboard" },
  "billing": {
    "plan": { "title": "Your plan" }
  }
}
```

Message syntax is ICU: `{name}` for values, `{count, plural, one {# item} other {# items}}` for plurals, `<link>…</link>` for [rich text](./using-translations#rich-text).

## Adding a Namespace

Create a JSON file. No registration, no code:

```
apps/web/messages/en/billing.json
```

Then `useTranslations('billing')`. The dev server picks it up after a reload.

- **The name must differ from every kit namespace.** A clash fails when messages load, on the first dev request or at preview start, and every page errors:

  ```
  i18n: namespace "common" is defined by both packages/i18n/src/messages/en/common.json (kit) and apps/web/messages/en/common.json (app); rename the app's file
  ```

- Use a plain name: letters, digits, `-` or `_`. A dot in the file name (`billing.plans.json`) becomes part of the namespace and breaks key lookup. The one exception is the `.server.json` suffix (see [Server-Only Strings](#server-only-strings)).
- Files must sit directly in the locale folder; subfolders (`en/billing/plans.json`) aren't loaded.

## Server-Only Strings

Every message file the root layout loads is sent to the browser. Strings only the server needs (email copy, notification text) go in a `<namespace>.server.json` next to it: `apps/web/messages/<locale>/emails.server.json`, or `auth.server.json` beside the kit's `auth.json`.

- **Same namespace.** The server file adds keys to `<namespace>`: `auth.server.json`'s `emails` is `auth.emails.*`. A key in both files fails when messages load.
- **Server translators only.** `getLocaleTranslator` and `getServerTranslator` (`apps/web/lib/i18n.server.ts`) see them; `useTranslations` in components doesn't.
- **MCP tools** list and edit the file as the namespace `<namespace>.server` (e.g. `kit_translations_update` with namespace `auth.server`, key `emails.verification.subject`).

## Overriding Kit Wording

Edit the kit file, for example `packages/i18n/src/messages/en/common.json`:

```json
{
  "notFound": {
    "heading": "We couldn't find that page."
  }
}
```

You can't override a kit namespace from your folder: a same-named file is the error above, by design, so kit strings never get replaced silently. A kit message file is a merge point: when you pull a kit update that touched it, keep your wording and add the kit's new keys.

## MCP Tools

The kit's `makerkit` MCP server (`.mcp.json`) exposes the same seven tools for each folder:

| Tool | `app_` edits `apps/web/messages` · `kit_` edits `packages/i18n/src/messages` |
|---|---|
| `*_translations_list` | Keys per locale and namespace, flattened with dots |
| `*_translations_update` | Set one value; missing groups are created |
| `*_translations_stats` | Coverage per locale against the base locale (`en`) |
| `*_translations_add_namespace` | New empty namespace file in every locale |
| `*_translations_add_locale` | New locale folder with an empty file per namespace |
| `*_translations_remove_namespace` | Delete a namespace from every locale |
| `*_translations_remove_locale` | Delete a locale folder (never the base locale) |

- Use `app_translations_*` for new strings. Use `kit_translations_*` only to change kit wording or add a locale to kit strings.
- `*_translations_add_namespace` refuses a name the other folder already has, so the duplicate-namespace error can't be created through MCP.
- The tools don't edit `apps/web/config/i18n.config.ts`; a new locale still needs its config line ([Adding a Locale](./adding-a-locale)).

## Dev Warnings

In development the console reports:

| Warning | Meaning |
|---|---|
| `i18n: <use-intl message>` | A key is missing (rendered as its path), or a message failed to format. |
| `i18n: locale "it" is configured but has no message files; add messages/it/<namespace>.json` | A configured locale has no files in either folder. It renders the default locale. |
| `i18n: messages/fr/ exists but "fr" is not in i18nConfig.locales, so it is never used` | A locale folder exists without a config line. |

Production logs none of these and never crashes on a missing key.

## Common Pitfalls

- **Adding a key only to a non-default locale.** Fallback runs from the default locale; a key missing there renders as its path everywhere.
- **Renaming a key without updating every locale.** The old key lingers in other locales and the new one falls back to the default. `*_translations_stats` shows the gap.
- **Secrets or unreleased names in messages.** Every message is bundled and shipped to the browser.
- **One giant namespace.** Split by feature; it keeps files small and merges clean.

---

**Next:** [Adding a Locale →](./adding-a-locale)
