MCP server for managing JSON translation files. Query, set, add, delete, rename, move, list, and search i18n keys across locales — designed for AI agents like Claude Code and Cursor. Supports flat and namespaced (i18next-style) directory layouts.

@trivle/i18n-tools-mcp

MCP server for querying and managing JSON translation files. Designed for AI agents (Claude Code, Cursor, etc.) to read and write i18n, i18next, react-i18next, and next-i18next translations directly through the Model Context Protocol.

Supports flat ({locale}.json) and namespaced ({locale}/{namespace}.json) directory layouts with dot-notation keys.

Install

Ask your AI agent:

Install the @trivle/i18n-tools-mcp MCP server. The translations directory is at ./messages and the base locale is nl.

Or add it manually to your MCP client config (e.g. .cursor/settings.json):

{
  "mcpServers": {
    "i18n-tools": {
      "command": "npx",
      "args": ["@trivle/i18n-tools-mcp", "./messages", "nl"]
    }
  }
}

Arguments:

1. Required: Path to the directory containing your translation files
2. Optional: Base locale code (default: nl) — used in tool descriptions to guide AI agents
3. Optional: JSON indentation spaces (default: 4)

Directory structures

Both flat and namespaced layouts are auto-detected.

Flat — one JSON file per locale:

messages/
  en.json
  nl.json

Namespaced — subdirectory per locale, one JSON file per namespace (i18next-style):

messages/
  en/
    common.json
    auth.json
  nl/
    common.json
    auth.json

In namespace mode, prefix keys with the namespace: common:Users.name. Read operations (query, list, search, missing) work across all namespaces when no prefix is given. Write operations (set, add) require a namespace prefix.

Tools

query

Look up a translation key across all locale files. Returns the value for each locale that has the key.

set

Set a translation value for a si