i18n-mcp

An MCP server for inspecting, validating, translating, and safely updating JSON i18n locale files in frontend projects. Detect locale layouts, bootstrap .i18n-mcp.json, find missing and stale translations, plan agent translation batches, validate placeholders and ICU shape, scan application source for dead keys, preview patches, and write only after explicit approval.

i18n-mcp supports both local stdio and MCP Streamable HTTP transports. It runs with the same filesystem permissions as the user or container process that starts it. Write tools are dry-run by default and require apply: true before changing files.

Security & Trust - This tool reads project files and can write locale JSON, config, and state files when explicitly asked. The default path is preview-first: config writes, state rebuilds, translation applies, key prune, and key rename all return patch previews unless apply: true is provided. The HTTP server binds to loopback by default and refuses non-loopback binds unless authentication is enabled. The built-in static bearer-token verifier is intended only for local development; place production deployments behind a properly authenticated and authorized gateway. In provider mode, translation items and requested style-guide or glossary context are sent to the configured provider; agent mode makes no server-side provider request.

Why i18n-mcp

• Safe locale writes - every write workflow is dry-run first, returns changed-file metadata and unified diffs, and writes only with apply: true.
• Framework-aware i18n bootstrap - detects project hints, JSON locale layouts, locales, namespaces, and a proposed .i18n-mcp.json config.
• Value-aware stale detection - tracks source hashes in .i18n-mcp/state.json instead of storing metadata inside locale files.
• Translation planning, not blind rewriting - builds deterministic batches for missing and stale keys, then validates proposed translations before apply.
• Validation built for UI strings - checks placeholders, HTML-like tags, ICU arguments, markdown-sensitive patterns, and empty targets.
• Dead-key review workflow - scans TS/TSX/JS/JSX/MJS/CJS usage, reports confidence, respects dynamic hints, and refuses unsafe prune by default.
• CI-ready audits - emits Markdown or JSON reports and exits according to configurable failure policy.
• Flexible MCP transport - use stdio for local coding agents or Streamable HTTP for network-capable MCP clients.

Quick Start

One-line install (macOS / Linux shell):

curl -fsSL https://raw.githubusercontent.com/Ret2Hell/i18n-mcp/main/install.sh | bash

Open OpenCode, Codex, or Claude Code from your frontend project directory and start working. The installer configures supported agents automatically.

Run either transport manually if needed:

# Local stdio
i18n-mcp serve stdio --project /path/to/frontend-app

# Streamable HTTP at http://127.0.0.1:7339/mcp
i18n-mcp serve http --project /path/to/frontend-app

Ask your agent to detect the i18n project. The first MCP tool call is:

{
  "name": "i18n.project.detect",
  "arguments": {}
}

Coding Agent Support

The one-line installer configures these agents by default:

| Agent | Config written | Server project root | | --- | --- | --- | | OpenCode | ~/.config/opencode/opencode.json | . from the OpenCode workspace | | Codex CLI | ~/.codex/config.toml | . from the Codex workspace | | Claude Code | ~/.claude/.mcp.json and ~/.claude.json | . from the Claude workspace |

After install, restart or open your coding agent from the frontend project directory. The MCP server is registered as i18n-mcp and starts as:

i18n-mcp serve stdio --project .

Use --skip-config if you want to install only the binary and configure agents yourself.

Docker

Pull the image:

docker pull ret2hell/i18n-mcp:latest

Run the stdio server:

docker run --rm -i ret2hell/i18n-mcp:latest serve stdio

For real project access, mount the project directory:

docker run --rm -i -v "$PWD:/workspace" -w /workspace ret2hell/i18n-mcp:latest serve stdio --project /workspace

Run Streamable HTTP on port 7339:

export I18N_MCP_DEV_TOKEN='replace-with-a-random-secret'
docker run --rm -p 127.0.0.1:7339:7339 \
  -e I18N_MCP_DEV_TOKEN \
  -v "$PWD:/workspace" -w /workspace \
  ret2hell/i18n-mcp:latest serve http \
  --project /workspace --addr 0.0.0.0:7339 --auth-required \
  --auth-resource http://127.0.0.1:7339/mcp \
  --dev-static-token-env I18N_MCP_DEV_TOKEN

This is a development-only bearer-token setup. Authentication is required because the process binds to a non-loopback address inside the container. Configure the client to send Authorization: Bearer <token>.

Installation

One-Line Installer

curl -fsSL https://raw.githubusercontent.com/Ret2Hell/i18n-mcp/main/install.sh | bash

Go Run Without Installing

Run directly from the module:

go run github.com/Ret2Hell/i18n-mcp/cmd/i18n-mcp@latest --help
go run github.com/Ret2Hell/i18n-mcp/cmd/i18n-mcp@latest serve stdio --project /path/to/frontend-app

Go Install

go install github.com/Ret2Hell/i18n-mcp/cmd/i18n-mcp@latest

Then run:

i18n-mcp --help
i18n-mcp serve stdio --project /path/to/frontend-app

Build From Source

git clone https://github.com/Ret2Hell/i18n-mcp.git
cd i18n-mcp
go mod download
go test ./...
go build -o bin/i18n-mcp ./cmd/i18n-mcp

Keeping Up to Date

Re-run the installer to replace the binary with the latest release:

curl -fsSL https://raw.githubusercontent.com/Ret2Hell/i18n-mcp/main/install.sh | bash

Uninstall

Remove the installed binary and any project state you no longer want:

rm -f "$(command -v i18n-mcp)"
rm -rf /path/to/frontend-app/.i18n-mcp

Do not remove .i18n-mcp.json unless you also want to remove project configuration.

MCP Client Configuration

The installer configures OpenCode, Codex CLI, and Claude Code automatically using stdio. For other MCP clients, choose either stdio or Streamable HTTP.

{
  "mcpServers": {
    "i18n-mcp": {
      "command": "/absolute/path/to/i18n-mcp",
      "args": ["serve", "stdio", "--project", "/absolute/path/to/frontend-app"]
    }
  }
}

Use absolute paths so the client does not depend on its current working directory.

Streamable HTTP

Start the HTTP server (the default endpoint is http://127.0.0.1:7339/mcp):

i18n-mcp serve http --project /absolute/path/to/frontend-app

Configure a Streamable HTTP-capable client with that URL. The exact configuration keys vary by client; a typical configuration looks like:

{
  "mcpServers": {
    "i18n-mcp": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:7339/mcp"
    }
  }
}

The server also exposes GET /healthz. Use --addr and --path to change the listen address and MCP endpoint. Loopback HTTP is unauthenticated by default. See HTTP Deployment before binding to another interface.

Docker-based stdio

For Docker-based clients using stdio, use docker as the command and pass the run arguments explicitly. Ensure the project is mounted into the container.

{
  "mcpServers": {
    "i18n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/absolute/path/to/frontend-app:/workspace",
        "-w",
        "/workspace",
        "ret2hell/i18n-mcp:latest",
        "serve",
        "stdio",
        "--project",
        "/workspace"
      ]
    }
  }
}

First Project Workflow

1. Call i18n.project.detect.
2. Review the returned proposedConfig.
3. Call i18n.config.write with the proposed config and no apply flag to preview .i18n-mcp.json.
4. Review the patch preview.
5. Call i18n.config.write again with apply: true to write the config.
6. Call i18n.config.validate.
7. Call i18n.state.rebuild without apply to preview state bootstrap.
8. Call i18n.state.rebuild with apply: true after review.
9. Call i18n.keys.diff to inspect missing, stale, invalid, extra, and unknown keys.

Features

Project Detection & Config

• Detect framework hints, i18n libraries, JSON locale file layouts, locales, and namespaces.
• Generate a proposed .i18n-mcp.json config for review.
• Validate config through MCP or CLI schema generation.
• Preview config writes before applying them.

Locale Inventory & Diff

• List locale files, namespaces, key counts, flattened keys, and duplicate namespace warnings.
• Compare source and target locales.
• Report current, missing, stale, invalid, unknown, and extra keys.

Translation Workflow

• Build deterministic translation batches for missing and stale keys.
• Include configured style guide and glossary content in plans when requested.
• Generate proposals through an optional direct OpenAI-compatible provider.
• Validate proposed translations against current source values.
• Reject source drift by default.
• Preview locale JSON and state patches before writing.

Dead-Key Workflow

• Scan source usage in .ts, .tsx, .js, .jsx, .mjs, and .cjs files.
• Detect literal calls, JSX i18nKey, and namespace-bound translation calls.
• Classify keys as used, probably_unused, maybe_dynamic, ignored, or kept.
• Respect ignoredKeyPatterns, keptKeyPatterns, and dynamicKeyHints.
• Prune exact keys only; unsafe statuses are refused unless explicitly overridden.

CI & Reports

• Run non-interactive audits with Markdown or JSON output.
• Configure failure policy for missing, stale, invalid, and dead-key statuses.
• Generate reports through MCP and read the latest report resource.

MCP Tools

| Tool | Description | | --- | --- | | i18n.health | Return server version, project root, and health status. | | i18n.project.detect | Detect project hints, locale layouts, and proposed config. | | i18n.config.get | Return resolved config with defaults and origin. | | i18n.config.validate | Validate resolved config. | | i18n.config.write | Preview or write .i18n-mcp.json; dry-run by default. | | i18n.locales.list | List locale files, namespaces, key counts, and warnings. | | i18n.keys.diff | Compare source and target locale keys. | | i18n.keys.usage_scan | Scan source files for translation key usage evidence. | | i18n.keys.dead_report | Classify likely dead keys. | | i18n.keys.prune | Preview or remove exact locale keys; dry-run by default. | | i18n.keys.rename | Preview or rename exact locale keys and state; dry-run by default. | | i18n.translation.plan | Build a translation batch for missing and stale keys. | | i18n.translation.generate | Generate and validate proposals through the configured direct provider without writing files. | | i18n.translation.validate | Validate proposed translations. | | i18n.translation.apply | Preview or apply translations and update state; dry-run by def