Shipi18n

在发布之前捕获损坏的翻译。 一个针对你的语言文件的开源 QA 门禁——而且，当你需要时，它也是一个使用你自己的 LLM 密钥运行的 i18n 翻译引擎。

当英语为 Hello {{name}} 时，你的 es.json 却写着 Hola。占位符不见了，构建绿灯，bug 随之发布。Shipi18n 能发现这一点，也能发现更难的那种：所有占位符都在、却仍然表达错误的字符串。

这是真实运行，不是模拟——docs/check-demo.tape 可以重现。

npx @shipi18n/cli check ./locales -s en

无需 API 密钥，无需账户，无需配置。缺失的键、丢失的占位符、合并的复数形式、空值和未翻译的文案——以人类可读输出、JSON、SARIF（GitHub PR 注释）或 JUnit 形式呈现。

然后，当你希望检查语义时，请使用你自己的密钥。评判器需要与 CLI 一起使用一个 provider SDK：

npm i -D @shipi18n/cli @anthropic-ai/sdk       # or `openai`
export ANTHROPIC_API_KEY=sk-ant-...            # or OPENAI_API_KEY
npx shipi18n check ./locales -s en --semantic

LLM 读取每一对翻译，并报告误译、遗漏和增添：

⚠ es  coverage 100.0%  0 error(s), 1 warning(s)
    warning  delete  semantic-mistranslation — Translation says 'will save' (guardará)
                     instead of 'will delete' (eliminará/borrará)

每个占位符都完好，每个键都存在，因此结构检查会通过此文件。只有真正阅读它才能发现这个 bug。默认仅建议——它发出警告，但不会使你的构建失败。

有数据为证，而非空口断言。 在一个包含 228 对翻译、且是在评判器编写之前提交的语料上 （60d699b），并且阈值事先固定： 54/54 个人为植入的错误被发现（100%），在干净翻译对上有 12/168 个误报（7.1%），并发现 6/6 个术语表违规。在两次独立运行（2026-08-16 和 2026-08-17）中使用 claude-haiku-4-5、3 轮、 ~59k tokens、耗时 156 秒复现。标签准确率在两次运行之间有所变化（100% → 98.1%）——它是一个 模型，所以请将这些结果视为一个范围，而非恒定值。 测试框架位于 evals/semantic/。你可以用自己的模型运行它。

没有任何数据经过我们的服务器，因为根本没有服务器。唯一的网络调用是从你的机器到你选择的提供商。

包

Related MCP server: i18n Agent

为什么

生成翻译是个已解决的问题。五六个好工具就能填满你的语言文件，而且 agent 会免费完成。但没有人检查结果。 你的 CI 会检查 JavaScript 的 lint、对类型做类型检查并运行测试——然后发布了一个没人读过的 de.json，它由没人审计过的模型生成。

现有的检查都是结构性的：它们对比键集合，然后仅此而已。这能发现缺失的键，却无法发现那种拥有所有键和所有占位符、仍然向你的德语用户传达了与你本意相反信息的翻译。

Shipi18n 就是那道缺失的门禁，分两层：

• 确定性、离线、无需密钥。 缺失和孤立的键、丢失或格式错误的占位符（{{name}}、{count}、%s、%d、%1$s、$t(...)、%{name}、HTML）、合并的复数形式、空值、未翻译的文案、每种语言的覆盖率。

• 语义检查，使用你自己的密钥。 仅对更改过的键执行 LLM 作为评判器的检查，并通过多轮多数投票来判定，因为单轮评判器的得分不稳定。报告误译、遗漏和增添。默认仅建议——一个会让构建失败的 QA 工具会被卸载。

再加上让它日常可用的部分：

• 超越 JSON 的格式。 Flutter .arb 和 Apple .xcstrings，包括 %@/%lld 说明符。

• CI 原生。 正确的退出码、--fail-on、--min-coverage、用于 PR 注释的 SARIF、JUnit。

• 手工编辑受到保护。 shipi18n lock 记录人工认可的翻译，并在任何内容覆盖它们或源文本在它们之下发生变化时发出警告。

• 编辑器内无需密钥。 MCP 服务器的验证器完全不调用模型。

• 它也能翻译。 与提供商无关、保留结构、增量式——内置 Anthropic 和 OpenAI，任何具有 complete(prompt) 方法的对象都是有效的适配器。

从你的编辑器检查——无需 API 密钥

@shipi18n/mcp 将检查功能带到任何 MCP 客户端。验证工具不调用模型，因此完全不需要密钥：

// claude_desktop_config.json
{
  "mcpServers": {
    "shipi18n": { "command": "npx", "args": ["-y", "@shipi18n/mcp"] }
  }
}

“将 ./locales 与英语对照，然后告诉我西班牙语里有什么问题。”

review_locales 更进一步，同样不需要密钥：它把翻译对和评审标准交给你的 agent，然后你的 agent 用它已在运行的模型来推理语义。

在 CI 中检查——无需密钥

这些检查适用于来自任何来源的翻译——TMS、另一个工具、agent 或人工。每次 push 时运行：

npx @shipi18n/cli check ./locales -s en

缺失的键、丢失的占位符、合并的复数形式、空值和未翻译的文案——以人类可读输出、JSON、SARIF（GitHub PR 注释）或 JUnit 形式报告。适用于普通 JSON 树、Flutter .arb 包和 Apple .xcstrings 目录。确定且离线：无 LLM，无 API 密钥。

保护手工编辑的翻译

手工修复一个字符串，将其锁定，如果任何内容覆盖了它——或英文在它下面发生了变动——check 就会警告你：

npx @shipi18n/cli lock ./locales --keys 'legal.*'

.shipi18n/locks.json 仅存储哈希值，可以安全提交，并且这些发现是警告——保护人工成果绝不应阻塞流水线。详情见 CLI README。

它也能翻译

检查功能适用于来自任何地方的翻译，但如果你也希望 Shipi18n 来生成译文，它也能做到——使用你的密钥、你的模型，中间没有任何中间环节。

npm i -D @shipi18n/cli @anthropic-ai/sdk       # or `openai`
export ANTHROPIC_API_KEY=sk-ant-...            # or OPENAI_API_KEY
npx shipi18n translate locales/en.json -t es,fr,de

✔ es → locales/es.json (2 translated, 0 reused)

或者从 Node 中使用（相同的 SDK 要求）：

import { translateJSON } from '@shipi18n/core'

const { result, stats } = await translateJSON({
  content: { greeting: 'Hello {{name}}' },
  from: 'en',
  to: 'es',
  provider: 'anthropic',        // 'anthropic' | 'openai' | custom { complete } adapter
})
// result → { greeting: 'Hola {{name}}' }

保留结构、占位符安全且增量式——只有新增或更改过的键才会被发送给模型。然后用同一个工具检查结果。

开发

这是一个 pnpm + turbo 的 monorepo。

pnpm install
pnpm test          # all packages
pnpm --filter @shipi18n/core test

版本管理由 Changesets 负责：运行 pnpm changeset 添加一个版本变更。

贡献

欢迎提交 Issue 和 pull request——请参阅 CONTRIBUTING.md。运行 pnpm install && pnpm test 会针对一个 mock 适配器运行 105 个测试，因此你无需 API 密钥即可参与开发。

许可证

Apache-2.0 © Shipi18n。请参阅 NOTICE。