Managing Translations
Add strings and namespaces, change kit wording, and manage message files with the MCP tools.
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.
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
- Pick the namespace (the file) and a key. Nest by feature or screen:
billing.plan.title, notbillingPlanTitle. - Add it to the
defaultLocalefile, and to each other locale's file if it has one. - Use it:
useTranslations('app')thent('billing.plan.title'), or<Trans i18nKey="app.billing.plan.title" />.
// 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.
Adding a Namespace
Create a JSON file. No registration, no code:
apps/web/messages/en/billing.jsonThen 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 fileUse 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.jsonsuffix (see 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'semailsisauth.emails.*. A key in both files fails when messages load. - Server translators only.
getLocaleTranslatorandgetServerTranslator(apps/web/lib/i18n.server.ts) see them;useTranslationsin components doesn't. - MCP tools list and edit the file as the namespace
<namespace>.server(e.g.kit_translations_updatewith namespaceauth.server, keyemails.verification.subject).
Overriding Kit Wording
Edit the kit file, for example packages/i18n/src/messages/en/common.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. Usekit_translations_*only to change kit wording or add a locale to kit strings. *_translations_add_namespacerefuses 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).
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_statsshows 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 →