shipi18n

Shipi18n

在发布前捕获有问题的翻译。 Shipi18n 是一款用于检查区域设置文件的开源工具：当人工、TMS 或 AI Agent 提供的翻译遗漏或破坏占位符、复数形式或键时，它会让 CI 失败，并指出确切的修复方法。

• 检测内容： 遗漏或重命名的占位符（{name}、{{count}}、%{name}、%s、%1$s、%@）；分隔符丢失或缺少该语言所需形式的复数（波兰语的 few/many、阿拉伯语的 two，适用于 ICU、i18next 键、Rails、Android 和 .xcstrings）；无效的 ICU MessageFormat；缺失和孤立的键；同一个 JSON 对象中重复书写的键；空字符串和未翻译字符串。
• 支持格式： JSON（i18next、vue-i18n、next-intl，扁平或嵌套）、YAML（包括 Rails）、Flutter ARB、Apple .xcstrings、Android strings.xml、gettext .po、XLIFF。
• 会上传任何内容吗？ 不会。检查在离线环境下运行，可以在你的机器或 CI 运行器上执行。
• 需要密钥或账户吗？ 不需要。只有可选的 --semantic 审查和 translate 功能会使用你自己的大模型密钥。

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

退出码 0 表示干净无问题，1 表示发现问题（每项都附带一行 fix），2 表示用法错误。输出格式包括文本、JSON、SARIF（GitHub PR 注释）或 JUnit。

实际运行，并非样例 — docs/check-demo.tape 可重现此过程。

选择你的任务

我想要……	使用
在本地或任何 CI 中检查区域设置文件	npx @shipi18n/cli check ./locales -s en
为 GitHub 拉取请求添加注释	Shipi18n/shipi18n-github-action@v3 (设置)
不使用 Node 运行	Docker ghcr.io/shipi18n/cli，或 pre-commit 钩子
不使用 npm 运行	从 GitHub releases 获取单文件 shipi18n.mjs，附带 SHA-256 和构建来源证明
在 Python、Ruby、Go 或 Java 项目中使用	通过 Docker、pre-commit 或单文件使用同一个 CLI。没有可导入的 Python 或 Ruby 包
让我的 AI 编码 Agent 检查自己的翻译	npx @shipi18n/cli init --agents，或使用 MCP 服务 @shipi18n/mcp
检查含义，而不只是结构	使用你自己的 Anthropic 或 OpenAI 密钥运行 check --semantic
翻译（可选）	使用你自己的密钥运行 shipi18n translate

它不做什么

• 它不是托管服务或 TMS：没有账户、控制面板或定价。（早期的托管翻译 API 已停止服务。）
• 它不是可从 Python 或 Ruby 导入的库；它是可在任何 CI 中运行的 CLI。
• 不使用 --semantic 时，它检查的是结构，而不是译文读起来是否通顺。

真实项目中的发现。 在真实项目中运行同一条命令——Hoppscotch 当时的南非语区域设置（仅检查结构；关闭缺失键提示，让占位符问题更醒目）：

$ npx @shipi18n/cli check packages/hoppscotch-common/locales -s en \
    --severity 'missing-key=off,untranslated=off,orphan-key=off'

✗ af  coverage 100.0%  7 error(s), 5 warning(s)
    error  import.file_size_limit_exceeded_warning_multiple_files  placeholder-missing — dropped {sizeLimit}
    error  import.file_size_limit_exceeded_warning_single_file  placeholder-missing — dropped {sizeLimit}
    error  state.connected_to  placeholder-missing — dropped {name}
    warning  state.connected_to  placeholder-added — unexpected {naam}
    error  team.invited_to_team  placeholder-missing — dropped {workspace}
    warning  team.invited_to_team  placeholder-added — unexpected {team}
    …

{naam} 是 {name} 的译文；vue-i18n 永远不会替换它。我们扫描公开仓库，逐条对照源语言手动核实每项发现，并向上游提交修复。持续统计，每个仓库一行： shipi18n.com/oss — 已扫描 95 个仓库 · 23 个仓库存在已核实的损坏字符串 · 已手动核实 402 个字符串 · 已在 8 个仓库中向上游提交修复。

仓库	发生了什么
Solidus	pt-BR 中有 13 处 %{…} 插值被删掉——PR 当天合并，获三位核心成员批准
Plane	捷克语提示消息丢失了 {templateName}/{templateType}——PR 在 3 小时内合并
nocodb	我们提交的问题 → 维护者提交 PR，修复全部 39 个区域设置；之后又发现13 个区域设置中的 182 处复数形式，其 | 被机器翻译转换成了 <unk>，并在当天修复
Excalidraw	我们提交的问题 → 贡献者修复问题并添加占位符一致性测试套件
Hoppscotch	上面的 af 运行结果——PR 已合并，共 7 个字符串
24pullrequests	在两个 PR 中修复了 20 处被删掉的插值，随后在其自己的测试套件中添加了插值检查
devise_invitable	修复了 %{email) 拼写错误，随后将检查添加到其 CI 中

扫描暴露出的每个我们自有检查器的误报，都会先成为 evals/placeholders/corpus.jsonl 中的测试样例。

如果这项检查在你的项目中发现了问题，不妨给仓库点个星——有星标，遇到损坏的 es.json 的下一个人才能找到它。

接下来，当你想检查含义时，请自备密钥。除了 CLI，评审器还需要一个提供商 SDK：

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

大模型会读取每一对文本，并报告误译、遗漏和增译：

⚠ 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á)

每个占位符都完好无损，每个键也都存在，因此这个文件通过了结构检查。只有阅读内容才能发现这个错误。默认情况下仅提供建议——它会发出警告，不会导致构建失败。

有实测数据，而非空口断言。 在编写评审器之前提交的 228 对语料上（60d699b），并且预先固定了阈值： 54/54 个植入错误均被发现（100%），168 对无误译文本中有 12 对误报（7.1%），并发现了 6/6 处术语表违规。在两次独立运行中复现（2026-08-16 和 2026-08-17），使用 claude-haiku-4-5，运行 3 轮，约消耗 59k 个 token，耗时 156s。标签准确率在两次运行间有所波动（100% → 98.1%）——它是一个模型，因此请将这些结果视为一个范围，而非固定值。 测试框架位于 evals/semantic/。你可以用自己的模型运行测试。

所有请求都不会经过我们的服务器，因为我们没有服务器。唯一的网络请求是从你的机器发送到你选择的提供商。

软件包

软件包	描述
@shipi18n/core	引擎：翻译检查、语义评审、占位符验证，以及与提供商无关、保留结构的增量翻译。
@shipi18n/cli	在 CI 中运行 shipi18n check ./locales，用 --semantic 检查含义，用 lock 保护手动编辑，需要时用 translate。
@shipi18n/mcp	MCP 服务——在 Claude Desktop、Cursor 或任何 MCP 客户端中检查、比较和审阅语言区域文件。验证无需 API 密钥。
vite-plugin-shipi18n	Vite 插件，使用你自己的大模型密钥在构建时翻译语言区域文件，并提供缓存。
shipi18n-github-action	在每个 PR 中检查语言区域文件（无需密钥，提供 SARIF 注释）；也可选用自带密钥重新翻译。

为什么

生成翻译的问题已经解决。有不少优秀工具可以填充语言区域文件，Agent 也能免费完成这件事。但没有任何工具会检查结果。 你的 CI 会检查 JavaScript 代码、进行类型检查并运行测试，最后却发布一个没人审阅、由未经审核的模型生成的 de.json。

现有检查大多只关注结构：比较键集合，然后就此打住。这样能发现缺失的键，却无法发现这样的翻译：所有键和占位符都齐全，却仍然把你原本的意思反过来告诉德语用户。

Shipi18n 正是缺失的这一道关卡，分为两层：

• 确定性、离线、无需密钥。 检查缺失键和孤立键、丢失或格式错误的占位符（{{name}}、{count}、%s、%d、%1$s、$t(...)、%{name}、HTML）、被合并的复数形式、空值、未翻译文案，以及各语言的覆盖率。
• 语义检查，使用你自己的密钥。 仅针对已更改的键运行 LLM-as-judge 检查，并通过多轮多数表决来应对单轮评审分数不稳定的问题。报告误译、遗漏和增译。默认仅供参考——会导致构建失败的 QA 工具最终只会被卸载。

此外，还有一些功能让它适合日常使用：

• 支持 JSON 以外的格式。 YAML（.yaml/.yml）、Flutter .arb、Apple .xcstrings、Android strings.xml、gettext .po/.pot 和 XLIFF 1.2/2.0——包括 %@/%lld 格式说明符。
• 原生支持 CI。 提供正确的退出代码、--fail-on、--min-coverage、用于 PR 注释的 SARIF，以及 JUnit。
• 可用于杂乱的目录。 --baseline 接受当前待处理问题，只对新增问题报错（Stylelint/RuboCop 模式）；--severity 可调整或关闭任意规则（error|warning|info|off）。
• 随处运行，无论是否有 Node。 可使用 GitHub Action、pre-commit 钩子，或 Docker 镜像 ghcr.io/shipi18n/cli，用于 GitLab / Bitbucket / Jenkins / 本地环境——无需 Node 工具链。请参阅 CLI README。
• WordPress .po ↔ JED 同步。 shipi18n wp-sync 可发现 JS 翻译 JSON 是否与 .po 文件不一致，因为没人重新运行 wp i18n make-json——这是其他工具都不会检查的隐蔽错误。
• 隐私预检。 --semantic 将任何内容发送给大模型之前，会先扫描并阻止包含机密或个人身份信息（PII）的字符串（密钥、银行卡号、电子邮件）；--detect-secrets 可独立运行此扫描，无需大模型。
• 保护手动编辑。 shipi18n lock 会记录人工确认过的翻译，并在有内容覆盖这些翻译或源文本发生变化时发出警告。
• 在编辑器中无需密钥。 MCP 服务的验证器完全不会调用模型。
• 它也能翻译。 与提供商无关、保留结构、支持增量翻译——内置 Anthropic 和 OpenAI 支持，任何具有 complete(prompt) 方法的对象都可用作适配器。

在编辑器中检查 — 无需 API 密钥

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

Claude Code — 一行配置：

claude mcp add shipi18n -- npx -y @shipi18n/mcp

Claude Desktop / 任何 MCP 客户端 — 粘贴配置：

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

“检查 ./locales，与英语对比，并告诉我西班牙语中有哪些问题。”

review_locales 还能做得更多，同样不需要密钥：它会将翻译对和审核标准交给你的 Agent，由你的 Agent 使用现有模型推理含义。

在 CI 中检查 — 无需密钥

这些检查适用于来自任何来源的翻译——TMS、其他工具、Agent 或人工翻译。每次推送时运行：

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

缺失的键、丢失的占位符、被折叠的复数形式、空值和未翻译的文本——均可通过人类可读输出、JSON、SARIF（GitHub PR 注释）或 JUnit 报告。支持普通 JSON 树、YAML、Flutter .arb、Apple .xcstrings、Android strings.xml、gettext .po/.pot 和 XLIFF（1.2/2.0）。确定性离线运行：无需 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/cli 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}}' }

保留结构、保障占位符安全并增量处理——只有新增或变更的键才会发送给模型。然后使用同一工具检查结果。

示例

examples/ 中提供了可运行的项目——react（Vite + react-i18next）、nextjs（App Router）、vue（vue-i18n）和 nodejs（@shipi18n/core）。进入其中一个目录，安装依赖，然后运行其检查／翻译脚本。

开发

这是一个 pnpm + turbo 单体仓库。

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

使用 Changesets 管理版本：运行 pnpm changeset 添加一个变更集。

参与贡献

欢迎提交问题和拉取请求——请参阅 CONTRIBUTING.md。运行 pnpm install && pnpm test，即可使用模拟适配器运行 105 项测试，因此开发时无需 API 密钥。

许可证

Apache-2.0 © Shipi18n。请参阅 NOTICE。