i18n-codelens-mcp

i18n-codelens-mcp

用于 i18n 翻译文件的模型上下文协议（MCP）服务。它让 AI Agent（Claude Code、Cursor、Antigravity、GitHub Copilot、Codex、Gemini CLI 及任何其他 MCP 客户端）能够检查、审计并安全地编辑区域设置 JSON 文件，而无需将整个区域设置文件加载到模型上下文中。

• 设计紧凑。 十个工具，结果为单行 JSON，不回显输入，到处都支持 limit/includeValues。一次典型读取仅需 50–200 个 token。
• 从设计上确保安全。 任何写入操作都无法减少区域设置文件的键集合；混合扁平/嵌套文件会在原处编辑，绝不转换；新增或更新操作会报告冲突，而不是覆盖内容。
• 采用当前 MCP 标准。 基于 TypeScript SDK v2 构建：协议修订版 2026-07-28 和 2025 年各修订版、服务说明、提示词（斜杠命令）、缓存提示，以及通过 elicitation 确认破坏性工具操作。
• 适用于任何布局。 locales/en.json、locales/en-US.json、messages.en.json 和 i18next 风格的 locales/en/common.json（命名空间文件，键为 common:nav.home）。

此软件包也是 i18n CodeLens VS Code extension 的 MCP 后端。

要求

• Node.js 20 或更高版本
• 以 JSON 文件形式存储的区域设置资源
• 支持 stdio 服务的 MCP 客户端

安装

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

客户端设置

以下每条命令都会注册同一个服务：名为 i18n-codelens、通过 npx -y i18n-codelens-mcp 运行的 stdio 服务。选择你的客户端，运行一行命令即可。

服务需要知道要处理哪个项目。大多数客户端会在项目目录中启动服务，而 Claude Code 会显式传入项目根目录，因此无需进行其他设置。如果客户端从其他位置启动服务，请使用客户端的 env 标志添加项目路径，例如 -e WORKSPACE_ROOT=/absolute/path/to/project。

Windows PowerShell： PowerShell 可能会吞掉尚未传递给 CLI 的独立 --，导致 CLI 报错 unknown option '-y'。如果遇到这种情况，请将分隔符写成 '--'，或在 cmd、Git Bash 或 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 会为 stdio 服务设置 CLAUDE_PROJECT_DIR，因此服务总能找到正确的项目。其工具搜索功能会延迟加载 MCP 工具；i18n_upsert_translations 和 i18n_get_translations 标记为 anthropic/alwaysLoad，因此这两个日常工具无需查找即可使用。提示词会显示为 /i18n-codelens:audit、/i18n-codelens:add-key 和 /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 和 agy mcp remove i18n-codelens 管理。在 IDE 中，输入 /mcp 可打开 MCP 管理器。

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

使用 -s project 将设置写入项目配置。Gemini 会按位置传递命令及其参数，因此无需使用 --。

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 和 Copilot Chat

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

这会写入用户配置文件。在命令面板中选择 MCP: Add Server，也可以通过引导流程完成相同操作，并且可以指定工作区。

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

Copilot CLI 在会话内添加服务，而不是通过 shell 添加。启动 copilot，然后：

/mcp add

填写表单：服务名称 i18n-codelens、服务类型 STDIO、命令 npx -y i18n-codelens-mcp。之后可通过 /mcp、/mcp show i18n-codelens 和 /mcp delete i18n-codelens 管理它。

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

Cursor、Windsurf、Claude Desktop、Kiro、Cline 和 Roo Code

这些客户端没有添加服务的命令，因此需要通过配置文件进行配置。各处的配置格式相同，只有路径不同。

{
  "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": []
    }
  }
}

与团队共享

提交项目级配置，这样每位团队成员和每个 Agent 都能使用同一个服务，无需修改全局设置。

工作区根目录

解析顺序：

1. 按工具指定的 workspaceDir 参数（必须位于已配置的根目录内，见下文）
2. CLI --workspaceRoot <path> / --workspace-root <path>
3. WORKSPACE_ROOT
4. CLAUDE_PROJECT_DIR（由 Claude Code 设置）
5. 当前工作目录
6. 服务包目录

workspaceDir 工具参数只能选择已配置根目录的子目录。除非启动服务时设置 I18N_ALLOW_ANY_WORKSPACE=1，否则模型无法将服务指向磁盘上的其他目录。

配置

工具

所有结果都是紧凑的单行 JSON。空白部分会被省略，路径相对于工作区且使用正斜杠，并且每个列表都遵循 limit（默认值为 50）。错误会以 isError 文本返回，并在消息中说明修复方法（例如可用 Locale 列表）。

具有破坏性工具的操作确认

i18n_delete_keys、i18n_rename_key 和 i18n_format_resources 默认会预览。当模型省略 dryRun 且客户端支持 MCP elicitation（Claude Code 支持）时，服务会显示一个说明变更内容的问题对话框，并在用户接受后应用变更。设置 dryRun:false 可不经对话框直接应用变更，设置 dryRun:true 则仅预览。i18n_upsert_translations 无需确认：它无法删除键，并且除非设置 overwrite:true，否则会拒绝覆盖不同的值。

提示词

服务会发布三个提示词，客户端会将它们作为命令提供：audit（完整审计和修复建议）、add-key <key> [text]（为每个 Locale 添加一个带有对应文案的键）和 translate-missing [locale]（分批填补缺失的翻译）。

指令

连接时，服务会发送使用说明（小于 2 KB），Claude Code 等客户端会将其添加到系统提示词中：绝不直接编辑 Locale 文件、调用一次 i18n_project_info、在一次调用中为所有 Locale 执行 upsert，等等。项目特定规则（键命名、语气、占位符风格）仍应放在你自己的 CLAUDE.md / AGENTS.md 中。

命名空间布局

如果语言文件按语言分别存放在目录中（locales/en/common.json、locales/tr/auth.json），则目录表示语言，文件表示命名空间。键使用 namespace:key 格式寻址（common:nav.home）；i18n_project_info 会报告 keyFormat: "namespace:key" 和命名空间。如果你的 i18n 库使用其他分隔符，请设置 I18N_NS_SEPARATOR；对于未带分隔符的键，请设置 I18N_DEFAULT_NS。

名称不是语言标签的文件（config.json）会被跳过并显示警告；如果一个 glob 匹配到同一语言两次（src/locales/en.json 和 public/locales/en.json），则使用第一个匹配项，并且 i18n_project_info 会提醒你缩小 I18N_GLOB 的匹配范围。

结构与键安全

语言文件根据叶节点的存储方式分为 扁平（"nav.home": "Home"）、嵌套（对象）或 混合。在 I18N_STRUCTURE=auto 下，扁平文件会以扁平形式写入，嵌套文件会以嵌套形式写入，而 混合文件绝不会被转换：每个键都会保留原位，新键则按文件中占主导的风格写入。写入时会保留文件的缩进、换行符和末尾换行，因此单键更改只会产生单行差异。

有两道保护机制，可从结构上杜绝键丢失：

• 遇到值与命名空间冲突时（dashboard.announcement 同时是字符串和父级），unflattenObject 会抛出错误，而不是覆盖其中一方。
• 每次写入都会将新文档与磁盘上的文件进行比较；如果有键将会消失，则拒绝写入。删除和重命名操作会声明要移除的键；任何其他缺失的键都会导致写入中止，并列出这些键。

src/__tests__/tools-write.test.ts 和 resource-manager.test.ts 中的回归测试重现了促成本次修复的问题（一个包含 3,000 个键的混合文件，以及同时作为叶节点和命名空间的键），并断言每种写入路径都不会丢失键，且只产生单行差异。

从 1.x 迁移

2.0 将 18 个工具整合为 10 个，并更改了两项默认设置。

其他更改：需要 Node 20+；@modelcontextprotocol/sdk 已替换为 @modelcontextprotocol/server 2.0（同时提供 2026-07-28 和 2025 版协议）；默认忽略 glob 现在会跳过常见的构建输出；workspaceDir 限定在配置的根目录内；路径使用 posix 格式；代码正则现在接受 ns:key，并能匹配文件开头处的调用。

对于使用过 1.x 名称的项目，建议使用以下 Agent 指令块：

i18n: never edit src/locales/*.json by hand. Call i18n_project_info once, then
i18n_upsert_translations with values for every locale (en and tr) in one call; it
reports conflicts and placeholder mismatches. Use i18n_get_translations to read,
i18n_audit for QA, i18n_rename_key / i18n_delete_keys with dryRun:false to apply.

MCP Registry

package.json 包含 mcpName: io.github.hepter/i18n-codelens-mcp，而 server.json 描述了该软件包。使用以下命令发布：

npm publish --access public
mcp-publisher login github
mcp-publisher publish

编程式 API

import { createI18nMcpServer, loadProject, createResourceManager, toolUpsertTranslations, createToolContext } from 'i18n-codelens-mcp';

const ctx = createToolContext({ workspaceRoot: '/path/to/project' });
const result = await toolUpsertTranslations({ entries: [{ key: 'nav.home', values: { en: 'Home', tr: 'Ana Sayfa' } }] }, ctx);

每个工具都以普通异步函数的形式导出，接收 (args, ctx)；同时还提供以下基础组件：loadProject（带缓存，支持命名空间）、getCodeIndex（带缓存的代码扫描）、createResourceManager（包含键丢失保护的写入状态）、writeFilePretty、flattenObject、unflattenObject、classifyResourceStructure。

更新日志

2.0.0

• **SDK v2 / 协议 2026-07-28。**使用 @modelcontextprotocol/server 和 serveStdio、zod 4、Node 20+。2026-07-28 和 2025 两个版本均通过 stdio 提供服务。tools/list 和 prompts/list 带有缓存提示。
• 工具从 18 个缩减为 10 个，结果精简为单行，不再提供 structuredContent，也不回显参数。工具定义从 13.5 K 字符缩减至 9.5 K 字符。在同一项目（约 7,600 个键的双语言环境代码库）上与 1.x 对比，搜索命中 50 个键时，结果从 12.5 K 字符缩减至 2.3 K 字符；完整审计从 6.7 K 字符、1.0 s 缩减至 2.0 K 字符、0.4 s。
• **Upsert 语义。**立即写入，操作文件前先验证整个批次（未知语言环境会导致全部操作被拒绝）；报告冲突而不覆盖，除非设置 overwrite:true；对于缺少值的语言环境以及与其他语言环境中对应值不匹配的占位符发出警告。
• **确认对话框。**Delete、rename 和 format 操作在客户端支持时使用 MCP elicitation，否则回退为预览并给出提示。
• 服务说明和提示词（audit、add-key、translate-missing）、服务元数据（websiteUrl、description），版本从 package.json 读取。
• 命名空间布局（{locale}/{namespace}.json，键采用 ns:key 格式）、根据文件名或目录名检测语言环境，并对重复文件和非语言环境文件发出警告。
• **缓存。**解析后的语言环境文件和代码扫描结果会被复用，前提是 mtime/大小未发生变化；审计只扫描一次代码。读取文件前会排除 .gitignore 和常见构建目录。
• **修复。**修正代码正则表达式的字符范围（.-_ 意外涵盖了 :…^）和文件开头匹配；修复 Windows 上的 posix 路径；遵循 CLAUDE_PROJECT_DIR；将 workspaceDir 限定在根目录内；写入时保留缩进和 CRLF；getWorkspaceRoot 不再在每次调用时记录日志。

1.1.0

修复了一个会导致数据丢失的问题：单次 upsert 可能将混合文件转换并丢弃名称同时作为值和命名空间的键。现在不会再转换混合文件；unflattenObject/setNestedValue 遇到冲突时会抛出异常；所有写入操作都会防止键丢失。

许可证

MIT © Mustafa Kuru