AI Localization Agent

ai-l10n-mcp

为 AI Agent 提供访问 l10n.dev 的 MCP 服务——这是一个专为软件 i18n 文件打造的专业本地化服务。

AI Agent 需要翻译你的应用时，最简单的办法就是把文件内容粘贴到聊天中。但这种做法很快就会遇到瓶颈：本地化文件很大、格式要求严格、占位符必须原样保留、术语表在不同会话间容易不一致，而且 Agent 在每次运行之间没有记忆。此 MCP 用专用的本地化引擎取代这种脆弱的工作流，Agent 可以将其作为工具调用，无需浪费上下文窗口来放置原始文件内容，即可获得专业水准的输出。

**可以把它看作是为你的 AI Agent 配备了一位专业本地化副驾驶：**Agent 负责理解意图和编排；l10n.dev 负责实际翻译，确保准确、一致，并保证格式无误。

---

为什么不直接让 AI Agent 翻译？

	仅使用 AI Agent	ai-l10n-mcp
支持 165 种语言	因情况而异，通常支持有限	✅ 全面支持
处理大型文件	内容被截断或跳过	✅ 完全由服务端处理
保留格式	不可靠——占位符、键和结构可能损坏	✅ 有保证——翻译后会验证源格式
术语表一致性	不同会话和文件分块之间无法保持	✅ 持久化术语表会应用于所有文件和分块
需要后期编辑？	通常需要	✅ 不需要——输出可直接用于生产环境
令牌成本	高——原始文件占用上下文	✅ 低——仅返回元数据
增量更新	每次都要完整读取并重新翻译	✅ 仅处理新增或更改的字符串

---

功能

• 165 种语言——一次调用即可翻译为丰富多样的世界语言
• 格式有保证——支持 JSON、JSONC、Flutter ARB、YAML、PO (gettext)、XLIFF、MD 及所有基于文本的 i18n 格式；占位符、键和结构都会在翻译后保留并验证
• 自动检测目标语言，并从项目结构中推断
• 持久化术语表——根据内容生成术语表并保存，之后会自动应用于每个文件和分块，确保术语一致
• 语言指示——为每种语言对保存风格/语气规则（例如“使用正式语气”）
• 增量翻译——基于哈希值检测更改，跳过已翻译的字符串，节省配额并保护现有译文
• 主动质量控制——在翻译前检查每种语言对的指示和术语表，而不是翻译后检查

将 Claude Desktop、Cursor、Windsurf、GitHub Copilot、OpenAI Codex 或任何兼容 MCP 的 Agent 直接连接到 l10n.dev 的翻译引擎。

---

安装与配置

获取 API 密钥

创建免费账户，并在 https://l10n.dev/ws/api-keys 获取 API 密钥。

**提示：**你也可以让 AI 使用 l10n_set_api_key 保存密钥，而不是在每个配置中设置 L10N_API_KEY。密钥会保存到 ~/.ai-l10n/config.json，并自动使用。

Claude Desktop

在 Claude Desktop 中，打开 Settings > Developer > Edit Config。Claude Desktop 会打开与你的安装相对应的 MCP 配置文件。在 macOS 上，该文件通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json。在 Windows 上，配置文件的实际路径可能因安装方式而异，因此建议使用 Edit Config，而不是手动查找。添加：

{
  "mcpServers": {
    "l10n": {
      "command": "npx",
      "args": ["-y", "ai-l10n-mcp"],
      "env": {
        "L10N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

在 Cursor 中打开 Customize，以添加和管理 MCP 服务。若要使用基于文件的配置，请创建以下配置文件之一：

• ~/.cursor/mcp.json，用于用户级配置
• 在项目中创建 .cursor/mcp.json，用于工作区专属配置

添加：

{
  "mcpServers": {
    "l10n": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ai-l10n-mcp"],
      "env": {
        "L10N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windsurf

在 Windsurf 中，打开 Cascade 中的 MCPs 面板，或前往 Devin Settings > Cascade > MCP Servers。如果需要手动添加，请编辑 ~/.codeium/windsurf/mcp_config.json 并添加：

{
  "mcpServers": {
    "l10n": {
      "command": "npx",
      "args": ["-y", "ai-l10n-mcp"],
      "env": {
        "L10N_API_KEY": "your-api-key-here"
      }
    }
  }
}

GitHub Copilot (VS Code)

打开命令面板并选择 MCP: Open User Configuration。或者，在工作区或用户设置中创建 .vscode/mcp.json 文件。添加：

{
  "servers": {
    "l10n": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ai-l10n-mcp"],
      "env": {
        "L10N_API_KEY": "your-api-key-here"
      }
    }
  }
}

OpenAI Codex (CLI and IDE)

对于全局用户配置，添加到 ~/.codex/config.toml；对于受信任的项目，则添加到 .codex/config.toml：

[mcp_servers.l10n]
command = "npx"
args = ["-y", "ai-l10n-mcp"]

[mcp_servers.l10n.env]
L10N_API_KEY = "your-api-key-here"

你也可以从终端添加：

codex mcp add l10n --env L10N_API_KEY=your-api-key-here -- npx -y ai-l10n-mcp

Claude Code (CLI and VS Code extension)

从终端添加服务：

claude mcp add --env L10N_API_KEY=your-api-key-here --transport stdio l10n -- npx -y ai-l10n-mcp

对于共享项目配置，Claude Code 也可以将 MCP 服务存储在项目根目录下的 .mcp.json 文件中。

---

可用工具

翻译

工具	说明
l10n_translate_file	将 i18n 源文件翻译为一种或多种目标语言
l10n_detect_project_structure	扫描源文件，以检测结构类型、源语言、目标语言和目标文件路径

这两个工具都能检测语言代码位于语言代码文件夹中（locales/en/common.json， 报告为 folder-based）以及位于文件名中（file-based）的情况——无论文件名本身就是语言代码（locales/en.json），还是将语言代码与其他部分组合在一起（app_en.arb、 locales/emails.en.json、locales/en-US.common.json、messages_en_US.properties）。对于无法识别的命名约定，请传入 languageCodeRegex，即包含 (?<language>...) 分组的正则表达式，例如 ^emails\.(?<language>[\w-]+)\.json$。分组周围的文本会沿用于目标文件，因此 emails.en.json 会生成 emails.ru-RU.json。

语言指令

工具	说明
l10n_list_instructions	列出所有已保存的语言指令（语气、风格、品牌声音）
l10n_create_instruction	为一组语言创建新的指令
l10n_update_instruction	更新现有指令
l10n_delete_instruction	删除指令

术语表

工具	说明
l10n_list_glossaries	列出所有已保存的术语表
l10n_get_glossary	获取特定术语表的完整详细信息和词条
l10n_create_glossary	创建新的空术语表
l10n_update_glossary	更新术语表名称或启用状态
l10n_delete_glossary	永久删除术语表
l10n_add_glossary_entry	向术语表添加术语映射
l10n_delete_glossary_entry	移除术语映射

账户

工具	说明
l10n_get_balance	查看剩余字符额度
l10n_set_api_key	在本地存储 API 密钥，以便自动使用
l10n_get_api_key_status	检查是否已配置 API 密钥

---

可用提示词

l10n_project_setup

指导你检查和配置语言指令及术语表，以获得最佳翻译质量。请在新项目开始时，或检查 l10n.dev 设置时调用。

参数：

• sourceLanguage — 源语言代码（默认值：en）
• targetLanguages — 以逗号分隔的目标语言代码（例如：es,fr,de）

l10n_setup_automation

扫描项目中的 i18n 源文件（使用 l10n_detect_project_structure），检查语言指引、术语表和余额，然后通过 GitHub Actions 或 npm 脚本交互式设置全自动翻译。

对于 GitHub Actions，会引导你选择以下四种触发方式：

• A) 每次推送到 main 时——翻译并直接提交回仓库
• B) 创建拉取请求时——翻译并创建 PR 以供审核
• C) 按计划触发——每晚翻译或按 cron 触发
• D) 仅手动触发——workflow_dispatch

会写入 ai-l10n.config.json 和 .github/workflows/translate.yml（或更新 package.json 脚本），然后告知你在哪里添加 API 密钥，以及下次触发时会发生什么。

参数：

• sourceLanguage — 源语言代码（默认为 en）
• targetLanguages — 以逗号分隔的目标语言代码（例如 es,fr,de）

---

示例工作流

用户：“将我的应用翻译成西班牙语和法语”

Claude（使用此 MCP 服务）将会：

1. 调用 l10n_list_instructions — 未找到适用于 es/fr 语言对的指引
2. 询问：“未找到适用于西班牙语/法语的指引——翻译前要设置语气/风格规则吗？（例如：正式、随意、品牌术语保留原文）”
3. 用户回答：“语气要随意，这是面向拉丁美洲的美食应用”
4. 使用该风格规则调用 l10n_create_instruction
5. 调用 l10n_list_glossaries — 未找到适用于 es/fr 的有效术语表
6. 询问：“未找到适用于西班牙语/法语的术语表——要为本次运行启用术语表生成吗？这样可以保存关键术语，确保今后的翻译保持一致。”
7. 用户回答：“是”
8. 检测到 es.json 和 fr.json 已存在——询问：“目标文件已存在——要启用增量模式以跳过未更改的字符串并节省配额吗？”
9. 用户回答：“是”
10. 使用 sourceFile、targetLanguages: ["es", "fr"]、instruction、generateGlossary: true、translateOnlyNewStrings: true 调用 l10n_translate_file
11. 报告结果

---

增量翻译

对于基于 JSON 的格式，启用 translateOnlyNewStrings: true 可跳过已翻译的字符串。每个源字符串的哈希值（而非其内容本身）都会存储在 l10n.dev 服务端，用于检测更改——只有新增或已更改的字符串会被翻译，从而节省字符配额。

注意： 首次翻译时，只会翻译新增字符串，因为哈希表为空，无法检测已更改的字符串。

---

自动化：CLI 和 GitHub Actions

有关 CI/CD 自动化和命令行用法，请参阅：

• ai-l10n CLI — 从终端或 CI 流水线翻译文件
• GitHub Action — 在推送、PR 或手动触发时自动翻译

---

定价

• 免费套餐 — 每月免费翻译 10,000 个字符，无需信用卡。
• 按量付费 — 价格实惠，按字符计费，无需订阅。
• 当前套餐 — 请访问 l10n.dev/#pricing 查看最新定价。

---

隐私与安全

• 不保留数据 — 除处理请求所需的时间外，l10n.dev 服务器不会存储源文本或译文。
• 加密通信 — 所有 API 调用均使用 HTTPS。
• 隐私优先 — 由开发者为开发者打造，将隐私、可靠性和质量作为核心优先事项。

---

支持

📧 电子邮件	[email protected]
🐛 问题反馈	GitHub Issues
📚 API 文档	api.l10n.dev/doc
🌐 网站	l10n.dev

---

许可证

MIT