i18n-mcp

Vibe coded project — built fast, works well, but may have rough edges. Missing a feature or hit a bug? Open an issue — contributions welcome.

MCP server for managing i18n JSON translation files. Gives Claude structured read/write access to your translation files — add keys, check coverage, find duplicates — without ever leaving your editor.

Works with monorepos. Supports both flat (en.json) and i18next folder (en/translation.json) structures, auto-detected per namespace.

Quick Start

Run this once in your project root:

npx @robinheat/i18n-mcp install

This installs the Claude Code skills and adds the MCP server to your project's .mcp.json. Then:

1. Restart Claude Code

2. Run /i18n-setup — auto-detects your translation files, infers tone and brand terms, writes .i18n-mcp.json

Related MCP server: mcp-locator

Configuration

.i18n-mcp.json lives in your project root:

{
  "primaryLocale": "en",
  "style": {
    "tone": "informal",
    "glossary": {
      "Wärmepumpe": "heat pump"
    },
    "doNotTranslate": ["Robin", "COP"]
  },
  "namespaces": [
    {
      "name": "common",
      "description": "Shared UI strings",
      "path": "packages/ui/locales"
    },
    {
      "name": "web",
      "description": "Web app strings",
      "path": "apps/web/locales"
    }
  ]
}

File Structure Support

Both layouts are auto-detected per namespace:

Flat:

locales/
  en.json
  de.json
  fr.json

i18next folder style:

locales/
  en/
    translation.json
  de/
    translation.json

Tools

All tools are available to Claude once the MCP server is running.

get_translation

Returns translations for a single key across all locales. Faster than get_translations for targeted spot-checks.

get_translation("common", "button.save")
// → { "en": "Save", "de": "Speichern" }

get_namespace_keys

Returns a sorted list of all dot-notation keys in a namespace without values. Use to plan batch translation work without loading full locale content.

get_namespace_keys("common")
// → ["button.cancel", "button.save", "title"]

get_translations

Returns all keys for a namespace as { "key.path": { "en": "...", "de": "..." } }.

get_translations("common")
get_translations("common", "button.*")      // glob filter on keys
get_translations("common", "save")          // substring filter on values

Results are capped at 100 KB (override with I18N_MCP_MAX_RESULT_BYTES). A namespace with thousands of keys across many locales runs to megabytes, which stalls the MCP client, so oversized results are truncated and a second content block reports how many entries were dropped. Filter with a query, or list keys with get_namespace_keys and fetch them individually with get_translation.

The query is matched as a glob against keys and as a substring against values. Brace expansion, extglob, and leading-! negation are disabled, so natural-language queries like {{count}} tickets or !important behave predictably. The same cap applies to get_namespace_keys and find_untranslated_values; check_translation_integrity lists at most 100 keys per locale per category.

add_translation

Adds or updates a single key. Only the provided locales are written.

add_translation("common", "button.save", {
  en: "Save",
  de: "Speichern",
  fr: "Enregistrer"
})

add_multiple_translations

Batch version — one disk write per locale file regardless of entry count.

add_multiple_translations("common", [
  { key: "button.save",   translations: { en: "Save",   de: "Speichern" } },
  { key: "button.cancel", translations: { en: "Cancel", de: "Abbrechen" } }
])

// Only write "de" even if other locales are provided:
add_multiple_translations("common", [...], ["de"])

delete_translation

Removes a key from all locale files in a namespace.

delete_translation("common", "button.save")

find_untranslated_values

Finds keys where the translated value is identical to the primary locale — placeholder translations that were never actually translated. Terms in doNotTranslate are excluded.

find_untranslated_values("web")           // all non-primary locales
find_untranslated_values("web", "de")     // one locale

Returns { locale: { key: primaryValue } } for each stale entry found.

check_translation_quality

Checks specific keys for quality issues across all non-primary locales. Returns issues per locale per key: untranslated (value identical to primary), empty (missing or blank), short (< 30% of primary value length for strings longer than 15 chars). Terms in doNotTranslate are excluded from the untranslated check.

check_translation_quality("web", ["header.title", "onboarding.description"])

copy_from_primary

Copies the primary locale value verbatim to specified locales for specified keys. Use for brand names, units, prices, and other terms that should not be translated. Returns an error if any key is missing from the primary locale.

copy_from_primary("common", ["brand.name", "unit.percent"], ["de", "fr"])

check_translation_integrity

Compares all locales against primaryLocale. Returns missing keys, extra keys, and empty values per locale.

check_translation_integrity()           // check all namespaces
check_translation_integrity("common")   // check one namespace

Array Values

JSON arrays are not supported as leaf values. Use indexed dot-keys instead — this is what i18next expects when you call t('key', { returnObjects: true }) anyway.

In your translation file:

{
  "steps": {
    "0": "Connect your device",
    "1": "Open the app",
    "2": "Follow the setup guide"
  }
}

Adding via tools:

add_multiple_translations("common", [
  { key: "steps.0", translations: { en: "Connect your device", de: "Gerät verbinden" } },
  { key: "steps.1", translations: { en: "Open the app",        de: "App öffnen" } },
  { key: "steps.2", translations: { en: "Follow the setup guide", de: "Setup-Anleitung folgen" } }
])

Reading via tools:

get_translations("common", "steps.*")

Integrity checks and missing-key detection work the same as for any other key.

Usage Skills

For day-to-day work (small edits, targeted key additions):

/i18n-usage

Guides Claude to check integrity first, search before adding, always add all locales at once, and verify coverage when done.

For large translation jobs (20+ keys or 3+ locales):

/i18n-translate

Orchestrates parallel agents — one per locale — so large jobs run faster without self-review loops or sequential batching.

Manual Installation (without npm)

Add the server to .mcp.json in your project root:

{
  "mcpServers": {
    "i18n-mcp": {
      "command": "npx",
      "args": ["-y", "@robinheat/i18n-mcp@latest"]
    }
  }
}

Then create .i18n-mcp.json in your project root manually.

Development

npm test          # run tests (85 tests)
npm run build     # compile to dist/
npm run dev       # run server directly with tsx (needs .i18n-mcp.json in cwd)

License

MIT