I18n Codelens MCP server

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 CLAUDEPROJECTDIR for stdio servers, so the server always finds the right project. Its tool-search feature defers MCP tools; i18nupserttranslations and i18ngettranslations 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.

Manual configuration

Project scope is .mcp.json in the repository root:

{
  "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.

Manual configuration

Global is ~/.gemini/config/mcpconfig.json (Windows: %USERPROFILE%\.gemini\config\mcpconfig.json), per project .agents/mcpconfig.json. In the IDE: … → MCP Servers → Manage MCP Servers → View raw config**.

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

Antigravity also accepts disabled: true and disabledTools: ["i18nformatresources"] per server.

Gemini CLI

Shortened. The full README is on GitHub.