i18n-codelens-mcp

Model Context Protocol (MCP) server for i18n translation files. It lets AI agents (Claude Code, Cursor, Antigravity, GitHub Copilot, Codex, Gemini CLI and any other MCP client) inspect, audit and safely edit locale JSON files without ever loading a whole locale file into the model context.

• Compact by design. Ten tools, single-line JSON results, no echoed input, limit/includeValues everywhere. A typical read costs 50-200 tokens.
• Safe by construction. No write path can reduce a locale file's key set; mixed flat/nested files are edited in place, never converted; upserts report conflicts instead of overwriting.
• Current MCP. Built on the TypeScript SDK v2: protocol revision 2026-07-28 and the 2025 revisions, server instructions, prompts (slash commands), cache hints and elicitation-based confirmation for destructive tools.
• Any layout. locales/en.json, locales/en-US.json, messages.en.json and i18next-style locales/en/common.json (namespace files, keys as common:nav.home).

This package is also the MCP backend of the i18n CodeLens VS Code extension.

Requirements

• Node.js 20 or newer
• Locale resources as JSON files
• An MCP client that supports stdio servers

Install

npx -y i18n-codelens-mcp
# or
npm install -g i18n-codelens-mcp

Client setup

Every command below registers the same thing: a stdio server named i18n-codelens running npx -y i18n-codelens-mcp. Pick your client, run one line, done.

The server needs to know which project to work on. Most clients start it in the project directory, and Claude Code passes the project root explicitly, so nothing else is needed. When your client starts the server from somewhere else, add the project path with the client's env flag, for example -e WORKSPACE_ROOT=/absolute/path/to/project.

Windows PowerShell: PowerShell can swallow a bare -- before it reaches the CLI, which then reports unknown option '-y'. If that happens, quote the separator as '--', or run the command from cmd, Git Bash or WSL.

Claude Code

# for the whole team: writes .mcp.json in the repo
claude mcp add --scope project i18n-codelens -- npx -y i18n-codelens-mcp

# just for you, in every project
claude mcp add --scope user i18n-codelens -- npx -y i18n-codelens-mcp

Claude Code sets CLAUDE_PROJECT_DIR for stdio servers, so the server always finds the right project. Its tool-search feature defers MCP tools; i18n_upsert_translations and i18n_get_translations are marked anthropic/alwaysLoad so the two everyday tools need no lookup. The prompts show up as /i18n-codelens:audit, /i18n-codelens:add-key and /i18n-codelens:translate-missing.

{
  "mcpServers": {
    "i18n-codelens": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"]
    }
  }
}

Google Antigravity

agy mcp add i18n-codelens -- npx -y i18n-codelens-mcp

agy mcp list, agy mcp disable i18n-codelens and agy mcp remove i18n-codelens manage it afterwards. Inside the IDE, /mcp opens the MCP manager.

{
  "mcpServers": {
    "i18n-codelens": {
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"],
      "cwd": "/absolute/path/to/project",
      "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" }
    }
  }
}

Gemini CLI

gemini mcp add -s user i18n-codelens npx -y i18n-codelens-mcp

Use -s project to write the project's settings instead. Gemini takes the command and its arguments positionally, so no -- is needed.

OpenAI Codex CLI

codex mcp add i18n-codelens -- npx -y i18n-codelens-mcp

[mcp_servers.i18n-codelens]
command = "npx"
args = ["-y", "i18n-codelens-mcp"]

VS Code and Copilot Chat

code --add-mcp "{\"name\":\"i18n-codelens\",\"command\":\"npx\",\"args\":[\"-y\",\"i18n-codelens-mcp\"]}"

That writes the user profile. MCP: Add Server in the Command Palette does the same through a guided flow and can target the workspace.

{
  "servers": {
    "i18n-codelens": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"],
      "env": { "WORKSPACE_ROOT": "${workspaceFolder}" }
    }
  }
}

OpenCode

opencode mcp add i18n-codelens -- npx -y i18n-codelens-mcp

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "i18n-codelens": {
      "type": "local",
      "command": ["npx", "-y", "i18n-codelens-mcp"],
      "enabled": true
    }
  }
}

GitHub Copilot CLI

Copilot CLI adds servers from inside a session rather than from the shell. Start copilot, then:

/mcp add

Fill in the form: Server Name i18n-codelens, Server Type STDIO, Command npx -y i18n-codelens-mcp. /mcp, /mcp show i18n-codelens and /mcp delete i18n-codelens manage it afterwards.

{
  "mcpServers": {
    "i18n-codelens": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"],
      "env": {},
      "tools": ["*"]
    }
  }
}

Cursor, Windsurf, Claude Desktop, Kiro, Cline and Roo Code

These clients have no command to add a server, so the configuration file is the way in. The shape is the same everywhere; only the path differs.

{
  "mcpServers": {
    "i18n-codelens": {
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"],
      "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" }
    }
  }
}

{
  "mcpServers": {
    "i18n-codelens": {
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"],
      "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" }
    }
  }
}

{
  "mcpServers": {
    "i18n-codelens": {
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"],
      "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" },
      "disabled": false,
      "autoApprove": ["i18n_project_info", "i18n_get_translations", "i18n_search_keys", "i18n_file_keys", "i18n_key_references", "i18n_audit"]
    }
  }
}

{
  "context_servers": {
    "i18n-codelens": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"],
      "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" }
    }
  }
}

{
  "mcpServers": {
    "i18n-codelens": {
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"],
      "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Sharing with a team

Commit a project-level configuration so every teammate and every agent picks up the same server without touching global settings.

Workspace root

Resolution order:

1. Per-tool workspaceDir argument (must be inside the configured root, see below)
2. CLI --workspaceRoot <path> / --workspace-root <path>
3. WORKSPACE_ROOT
4. CLAUDE_PROJECT_DIR (set by Claude Code)
5. Current working directory
6. Server package directory

The workspaceDir tool argument can only select a sub-directory of the configured root. A model cannot point the server at another directory on disk unless the server is started with I18N_ALLOW_ANY_WORKSPACE=1.