the-i18n-mcp

MCP server for managing i18n translation files — gives your AI agent full control over your app's translations without dumping entire locale files into context.

12 purpose-built tools that let the agent work surgically — touching only the keys it needs. Auto-detects Nuxt, Laravel, or any project with JSON/PHP locale files.

Part of the-i18n-kit monorepo. For CLI usage, see the-i18n-cli.

Quick Start

No install needed — your MCP host runs the server via npx.

Add to .vscode/mcp.json:

{
  "servers": {
    "the-i18n-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["the-i18n-mcp@latest"]
    }
  }
}

Add to .zed/settings.json:

{
  "context_servers": {
    "the-i18n-mcp": {
      "command": "npx",
      "args": ["the-i18n-mcp@latest"]
    }
  }
}

Add to claude_desktop_config.json:

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

Then just ask your agent:

"Add a 'save changes' button translation in all locales"

"Find and fix all missing translations in the admin layer"

"Add Swedish as a new language and translate everything"

Related MCP server: i18n Agent

What You Get

• Auto-translate entire locales — translate_missing batches keys to an LLM via MCP sampling, writes results back, and shows a progress bar

• Refresh one existing key — translate_key updates a source locale and translates target locales, optionally overwriting stale existing values

• Add a new language in one shot — the add-language prompt walks your agent through config updates, file scaffolding, and bulk translation

• Safe, atomic writes — temp file + rename cycle, indentation preserved, keys sorted alphabetically, {placeholders} validated

• Smart caching — config detection and file reads are mtime-cached, writes invalidate automatically

• Monorepo & layer-aware — discovers all Nuxt apps and layers under a project root

• Dead key cleanup — find orphan keys not referenced in source code and bulk-remove them

Supported Frameworks

Tools

Prompts

Examples

write_translations — Hand-crafted translations

Add a key to two locales (upsert mode never fails if key exists):

{
  "layer": "root",
  "mode": "upsert",
  "translations": {
    "auth.login.title": {
      "en-US": "Welcome back",
      "de-DE": "Willkommen zurück"
    }
  }
}

Strict add (fails if key already exists):

{
  "layer": "root",
  "mode": "add",
  "translations": {
    "common.actions.save": {
      "en-US": "Save",
      "de-DE": "Speichern",
      "fr-FR": "Enregistrer"
    }
  }
}

translate_key — Single-key LLM translation

Source value provided inline, writes to source locale + translates to others:

{
  "layer": "root",
  "key": "bookingCreator.options.removeSubResource",
  "sourceLocale": "en-US",
  "sourceValue": "Remove sub-resource",
  "targetLocales": ["de-DE", "fr-FR", "es-ES"],
  "overwrite": true
}

Source value read from existing locale file, only fill missing targets:

{
  "layer": "root",
  "key": "auth.errors.sessionExpired",
  "sourceLocale": "en-US",
  "targetLocales": "all",
  "overwrite": false
}

Project Config

Drop a .i18n-mcp.json at your project root:

{
  "$schema": "node_modules/the-i18n-mcp/schema.json",
  "context": "B2B SaaS booking platform",
  "glossary": {
    "Booking": "Core concept. Dutch: 'Boeking'.",
    "Resource": "A bookable entity (room, desk, person)"
  },
  "translationPrompt": "Professional but approachable tone. Keep translations concise.",
  "localeNotes": {
    "de": "Informal German (du)",
    "de-formal": "Formal German (Sie)"
  }
}

See the full config reference for all options including layerRules, examples, orphanScan, samplingPreferences.

Model Selection for Translations

translate_missing uses MCP sampling — the host picks which LLM fulfills the request. The server hints toward fast, cheap models since translation is high-volume.

Default preferences:

Override via samplingPreferences in .i18n-mcp.json.

Tip: In VS Code, restrict model access per-server via MCP: List Servers → Configure Model Access to force a specific fast model for translation batches.

Migrating from v2

npx the-i18n-mcp and npx nuxt-i18n-mcp still work — both bin names point to the same server. No configuration changes needed.

The MCP server API (tools, prompts, resources) is unchanged. The main difference is the internal restructure into a monorepo with the core logic in the-i18n-cli.

License

MIT