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

StringFolderNamespace
Your features, pages, nav labels, your emailsapps/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 emailspackages/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" />.
// 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.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).

  • 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:

{
"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:

Toolapp_ edits apps/web/messages · kit_ edits packages/i18n/src/messages
*_translations_listKeys per locale and namespace, flattened with dots
*_translations_updateSet one value; missing groups are created
*_translations_statsCoverage per locale against the base locale (en)
*_translations_add_namespaceNew empty namespace file in every locale
*_translations_add_localeNew locale folder with an empty file per namespace
*_translations_remove_namespaceDelete a namespace from every locale
*_translations_remove_localeDelete 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).

Dev Warnings

In development the console reports:

WarningMeaning
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>.jsonA 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 usedA 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 →