i18n-mcp

An MCP (Model Context Protocol) server that gives coding agents tools to manage Rails-style localization files (YAML or JSON). Point it at a Rails app's config/locales directory and the agent can read, search, write and audit translations without hand-editing files.

Supported layouts

Both common Rails layouts are detected automatically, and can be mixed:

config/locales/
  en/                  # per-locale directories (nesting allowed)
    common.yml         # rooted at the locale code: `en: ...`
    admin/users.yml
  th/common.yml
  legacy.yml           # flat files whose top-level keys are locale codes

Files may be .yml, .yaml or .json. Writes go through the YAML AST, so existing comments and key order survive edits. Duplicate keys are tolerated with last-wins semantics, matching Rails (Psych). Files that cannot be parsed are reported in locales output under problems instead of aborting the server.

Related MCP server: i18n-mcp

Install and build

Run directly from npm without installing:

npx -y mcp-i18n --locales-dir /path/to/rails-app/config/locales

Or build from source:

npm install
npm run build

Usage with an MCP client

Add the server to your MCP client configuration (Kimi Code, Claude Desktop, etc.). Via npx (no local checkout needed):

{
  "mcpServers": {
    "i18n": {
      "command": "npx",
      "args": [
        "-y", "mcp-i18n",
        "--locales-dir", "/path/to/rails-app/config/locales"
      ]
    }
  }
}

Or from a local build:

{
  "mcpServers": {
    "i18n": {
      "command": "node",
      "args": [
        "/path/to/i18n-mcp/dist/src/index.js",
        "--locales-dir", "/path/to/rails-app/config/locales"
      ]
    }
  }
}

Options:

• --locales-dir <path> — locales directory. Falls back to the I18N_LOCALES_DIR environment variable, then <cwd>/config/locales.

• --default-file <name> — file name (relative to the locale directory) for brand-new keys. Default: common.yml (or common.json for JSON-only locales).

Tools

Examples

// get_key
{ "key": "roles_scope.super_admin" }

// set_key
{ "key": "features.reports.title", "values": { "en": "Reports", "th": "Reports (th)" } }

// missing, scoped to one subtree
{ "prefix": "dashboards", "limit": 50 }

All responses are JSON. Errors (unknown locale, missing key, write failures) are returned as tool errors with a human-readable message.

Development

npm test            # vitest unit/handler tests
npm run coverage    # tests + v8 coverage report (enforced thresholds: 85% lines/statements, 80% branches/functions)
npm run lint        # eslint (zero errors required)
npm run typecheck   # tsc --noEmit, strict (zero errors required)
npm run build       # compile to dist/
npm run smoke       # end-to-end test over real stdio transport