KAERIS i18n

KAERIS i18n — MCP 服务

基于 Model Context Protocol 的 AI 原生本地化。让 Claude Desktop、Cursor、 Claude Code（或任何 MCP 客户端）能够将应用中的字符串翻译成 46 种语言 — 安全保留占位符、识别格式、支持增量翻译，并内置翻译 QA。

工具

工具	功能	会调用 API 吗？
kaeris_scan_repo	发现仓库的 i18n 设置：找到的语言区域文件、基础语言、目标语言、框架猜测（i18next/next-intl/vue-i18n/Flutter/Android/iOS/gettext/通用）	否
kaeris_status	各目标语言区域的完整度/健康状况 — 缺失键、多余键、占位符不匹配，以及在 CI 中阻止合并的质量检测：数字偏差、行内标签丢失、实体/转义字符损坏、ICU/CLDR 复数规则缺失（与 kaeris check --json 的判定结果相同）	否
kaeris_list_missing_keys	某个目标语言区域中确切缺失/损坏的键（附带源文本），让 Agent 清楚知道需要修复什么	否
kaeris_list_languages	列出所有受支持的目标语言	是，免费（不占用配额）
kaeris_translate	翻译内联字符串 → 按语言返回结果，并执行 QA（标记占位符丢失和 UI 溢出；verify=True 会回译以检查含义）	是
kaeris_translate_file	翻译磁盘上的文件（JSON/YAML/.strings/.xcstrings/.po/ARB/XML/CSV/XLIFF/.properties/.resx/.ftl/Markdown），可选增量翻译 — 可通过 kaeris.lock 重现	是
kaeris_add_language	初始化全新的目标语言区域：将整个源文件翻译成该语言	是

前三个工具仅在本地运行（不联网、不产生费用），而 kaeris_list_languages 只会调用一次免费 API，且不受任何限额影响 — Agent 可以免费使用这四个工具来审查并了解仓库的 i18n 设置，再决定是否需要翻译。

专为可重现性设计

kaeris_translate_file 配合 only_new=True 使用时，会在源文件旁保留一个 kaeris.lock — 与 CLI 写入的锁文件相同，因此共享仓库的 Agent 和开发者可以保持同步。它会记录每个源字符串的哈希值 以及生成译文的设置：语气、词汇表、应用上下文和模型。这意味着：

• 编辑一个字符串 — 只会重新翻译该字符串；其他所有内容都保持逐字节不变。
• 更改语气、词汇表或上下文 — 会重新翻译整个语言区域，不会混用新旧译文。
• 更改套餐 — 每个套餐等级都使用同一个模型（Gemini 2.5 Flash-Lite），因此升级无需强制重新翻译。锁文件始终会记录模型；若将来更换模型，整个语言区域会重新生成，而不是悄然混入两个模型的产出。

将 kaeris.lock 与源文件一同提交，确保 Agent、团队成员和 CI 对已完成的工作保持一致。

安装

pip install kaeris-mcp

或使用 Docker 运行

docker build -t kaeris-mcp .
docker run -i --rm -v "$PWD:/work" -w /work kaeris-mcp

该服务通过 stdin/stdout 使用 JSON-RPC 通信，因此无需暴露端口 — -i 用于保持会话开启。将项目挂载到 /work，面向仓库的工具（scan_repo、status、list_missing_keys）就可以直接读取项目； 传入 -e KAERIS_API_KEY=… 即可使用你的 KAERIS 密钥。

配置客户端

Claude Desktop — 添加到 claude_desktop_config.json （macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）：

{
  "mcpServers": {
    "kaeris-i18n": {
      "command": "kaeris-mcp",
      "env": {
        "KAERIS_API_KEY": "kaerisp_optional"
      }
    }
  }
}

Cursor — Settings → MCP → Add，或使用 .cursor/mcp.json：

{ "mcpServers": { "kaeris-i18n": { "command": "kaeris-mcp" } } }

Claude Code — 执行一条命令：

claude mcp add kaeris-i18n kaeris-mcp

重启客户端；KAERIS 工具将自动显示。

身份验证与层级（均为可选）

环境变量	用途
KAERIS_API_KEY	你的 KAERIS 密钥，例如从 kaeris.dev/docs/key 获取的免费 API 密钥（每个文件 50k 个字符，无需账户）——不提供密钥时，将使用免费的 10k 字符演示版
KAERIS_OPENROUTER_KEY	用于 Lifetime/BYOK 的 OpenRouter 密钥——无月度用量上限
KAERIS_API_URL	覆盖 API 基础 URL
KAERIS_NO_UPDATE_CHECK	设为 1 可关闭每日一次的“有新版本可用”提示（仅输出到 stderr；CI 中已关闭）

无需密钥即可试用——免费演示版开箱即用。

提示词示例

• “将 locales/en.json 中的字符串翻译成德语、乌克兰语和日语。”
• “为这些按钮添加法语和西班牙语翻译：Save、Cancel、Delete。”
• “只翻译我添加到 en.json 的新键——不要重做整个文件。”
• “检查此仓库的 i18n，并告诉我有哪些内容缺失或有问题。”（扫描后报告状态——不调用 API）
• “我们还没有乌克兰语——添加它。”（通过翻译初始化新的语言环境）

许可证

MIT