CLI
verbatra check$ npx @verbatra/cli check
verbatra check
de: 0 missing, 1 stale, 13 up-to-date (out of sync)
out of sync (run verbatra translate to update)锁文件
en.json 2 个已更改
{
……另有 12 个,未更改
"checkout": {
"title": "Review and checkout", 已更改
"pay": "Pay and place order" 已更改
}
}verbatra.lock.json 2 stale, 12 up-to-date
{
"version": 1,
"locales": {
"de": {
……另有 4 个,未更改
"cart.total": "692deda3edfe75da",
"checkout.pay": "bcdca4b40874a53a", 过期
"checkout.title": "f0eeada9213af138", 过期
"errors.notFound": "427078dedd81b2ce",
……另有 6 个,未更改
}
}
}过期(stale)表示记录的哈希与当前 en.json 值的哈希不一致。其余 12 个一致。
verbatra translate 2 translated, 12 unchanged
$ npx @verbatra/cli translate
de: 2 translated, 12 unchangedde.json 预先生成,非实时
{
……另有 12 个,未更改
"checkout": {
"title": "Überprüfen und zur Kasse gehen", 已更改
"pay": "Bezahlen und Bestellung aufgeben" 已更改
}
}gemini-2.5-flash,
verbatra.lock.json:2 个哈希已更新。
门禁
每条候选译文都要先通过完整性门禁,才会进入你的文件。 docs/translation-safety
profile.greeting gemini-2.5-flash
en.json 已更改
"Welcome back, {name}!"
"Good to see you, {name}!"de 提供商的回答
"Schön, Sie zu sehen!" {name} 缺失尚未检查,也尚未写入。
verbatra translate 未写入 1 integrity-withheld
$ npx @verbatra/cli translate
de: failed, 0 translated, 13 unchanged, 1 integrity-withheld
integrity-withheld:
profile.greeting: placeholder (-{name})
0 succeeded, 0 partial, 1 failedde.json 未更改
"profile": {
"greeting": "Willkommen, {name}!",
...verbatra check exit 1
$ npx @verbatra/cli check
de: 0 missing, 1 stale, 13 up-to-date (out of sync)
out of sync (run verbatra translate to update)de.json 未更改
"profile": {
"greeting": "Willkommen, {name}!",
...de.json 保留之前的值。该键仍为过期状态,下次运行时会重试。
一个锁
命令
从源代码中的第一个字符串,到线上已审校的译文。
verbatra extractverbatra extract 2 个新键
$ npx @verbatra/cli extract --dry-run
verbatra extract
1 file scanned, 2 keys already present
would add 2 keys to messages/en.json
new keys (2):
checkout.giftNote src/Checkout.tsx:8
checkout.backToCart src/Checkout.tsx:10
dry run, nothing writtenwould add 2 keys to messages/en.json
扫描代码中的翻译调用,在任何人翻译之前,先把新键添加到源语言环境。
docs/cli/extractverbatra typesverbatra-types.d.ts 14 个键已声明
$ npx @verbatra/cli types
verbatra types
14 keys declared, 1 of them taking arguments, from messages/en.json
wrote verbatra-types.d.tsexport interface VerbatraMessages {
……另有 8 个
"profile.greeting": { readonly "name": VerbatraArgument };
……另有 3 个
"checkout.title": VerbatraNoArguments;
"checkout.pay": VerbatraNoArguments;
}14 keys declared, 1 of them taking arguments, from messages/en.json
为键和消息参数生成 TypeScript 声明,键名拼错就会导致构建失败。
docs/cli/typesverbatra doctorverbatra doctor 无需 API 密钥
$ npx @verbatra/cli doctor
verbatra doctor
[ok ] Configuration: Loaded .verbatrarc.json.
[ok ] Format adapter: Format "next-intl-json" resolves to an adapter.
[ok ] Provider: Provider "gemini" resolves to a factory.
[fail] API key environment variable: The GEMINI_API_KEY environment variable is not set.
fix: Set GEMINI_API_KEY in the environment, or, with the CLI, in a .env file in the project directory.
……更多检查,全部通过
1 problem found (run verbatra doctor again after fixing it)
$ npx @verbatra/cli translate --dry-run
verbatra translate (dry run)
de: 2 would translate, 12 unchanged
1 succeeded, 0 partial, 0 failed (dry run: nothing written)de: 2 would translate, 12 unchanged
doctor 无需 API 密钥即可检查配置,估算则在产生费用前评估一次运行的规模。
docs/cli/doctorverbatra watchverbatra watch 每次保存时
$ npx @verbatra/cli watch
verbatra: watching en (messages/{locale}.json); running initial translation
verbatra: translating de
verbatra: de batch 1/1
verbatra: de: writing
verbatra: de done, 2 translated
verbatra: run finished, 1 locale processed
verbatra translate
de: 2 translated, 12 unchanged
1 succeeded, 0 partial, 0 failed
verbatra: waiting for changes...de: 2 translated, 12 unchanged
开发时保持监听进程运行,每次保存都会翻译源语言环境的更改。
docs/cli/watchverbatra exportverbatra-translations/de.csv 2 行待翻译
$ npx @verbatra/cli export --format csv
verbatra export -> verbatra-translations
de: 2 rows
2 rows across 1 locale| Key | Source | Status | Translation |
|---|---|---|---|
| checkout.pay | Pay and place order | changed | 由译者填写 |
| checkout.title | Review and checkout | changed | 由译者填写 |
de: 2 rows
导出 Excel 工作簿、CSV、TSV 或 XLIFF 交给译者,再导入回来。导入的值受保护,之后的机器运行不会覆盖。
docs/cli/exportverbatra studio结果
每个入口读取的都是同一个锁文件,所以在 profile.greeting 被拒绝的情况下,无论在哪里查看,德语都是 1 个过期、13 个最新。
verbatra.lock.json 1 stale, 13 up-to-date
"profile.greeting": "deb45ffcf3548530", stale$ npx @verbatra/cli check
verbatra check
de: 0 missing, 1 stale, 13 up-to-date (out of sync)
out of sync (run verbatra translate to update)import { check } from "@verbatra/sdk";
const summary = await check({ config });
summary.locales[0];
// { locale: "de", missing: 0,
// stale: 1, upToDate: 13,
// inSync: false, ... }npm install --save-dev @verbatra/sdk
status.check({})
{ "inSync": false, "locales": [
{ "locale": "de", "missing": 0,
"stale": 1, "upToDate": 13, ... }
] }claude mcp add --transport stdio --scope project verbatra -- npx -y @verbatra/mcp
替代方案
决定翻译工作流的关键点,针对团队最常比较的工具逐一作答。
| 问题 | Verbatra | Crowdin | Tolgee | Lingo.dev | 手动流程 |
|---|---|---|---|---|---|
| 无需供应商账号即可使用 | 是 | 否 | 部分 | 否 | 是 |
| 使用你自己的提供商密钥 | 是 | 是 | 部分 | 部分 | 是 |
| 只翻译已更改的键 | 是 | 部分 | 部分 | 是 | 否 |
| 翻译缺失或过期时让 CI 失败 | 是 | 是 | 否 | 是 | 否 |
| 翻译后检查占位符和 ICU | 是 | 是 | 是 | 部分 | 否 |
| 面向译者的网页编辑器 | 部分 | 是 | 是 | 部分 | 否 |
最后核查于 2026年11月16日
常见问题
简短的回答,每条都附有可深入了解的文档页面。
是的。Verbatra 免费,采用 MIT 许可证 (在新标签页中打开)开源;你只需为已更改的键向提供商付费,运行前估算费用可以先估出规模。
Anthropic、OpenAI、Gemini、DeepL、Google Cloud Translation、OpenCode、OpenAI-compatible和LibreTranslate。在 provider 中设置其一,只由人工翻译时设为 none;提供商页面逐一介绍。
只发给你配置的提供商,且仅在命令翻译时发送;没有遥测。密钥只留在环境变量中,数据处理与隐私页面列出各提供商会收到什么。
是的。只要有语言环境存在缺失或过期的键,verbatra check 就以退出码 1 退出,无需 API 密钥;GitHub Action 会在 pull request 上运行它。
它是在你自己提交的文件上运行的 CLI,不是托管平台。对比表格把它与其他工具逐项对照,也包括对方更强的地方。
在花掉任何 token 之前
这条路径适用于已有语言文件的项目,两个步骤都不需要 API 密钥。
npx @verbatra/cli initnpx @verbatra/cli translate --dry-run