跳到正文

只翻译已更改的内容

Verbatra 把每个键的哈希存入锁文件,只向你的提供商发送已更改的键,漂移时让 CI 失败。

开始使用
npm i -D @verbatra/cli

适配你已在用的语言文件和提供商

文件格式

  • i18next JSON
  • vue-i18n JSON
  • next-intl JSON
  • ngx-translate JSON
  • XLIFF
  • YAML
  • Flutter ARB
  • Java/Spring .properties
  • Apple .strings
  • Xcode String Catalog
  • Android strings.xml
  • gettext .po/.pot
  • INI
  • .NET .resx

提供商

  • Anthropic
  • OpenAI
  • Gemini
  • DeepL
  • Google Cloud Translation
  • OpenCode
  • OpenAI-compatible
  • LibreTranslate

锁文件

两个键已更改,两个键已发送

编辑你在源文件中更改了 2 个值。

en.json 2 个已更改

{
……另有 12 个,未更改
"checkout": {
"title": "Review and checkout", 已更改
"pay": "Pay and place order" 已更改
}
}
比对Verbatra 为每个键计算哈希,再与锁文件比对。2 个已记录的哈希不再匹配。

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 个一致。

发送只有这 2 个键会发送给提供商。其余 12 个不会发送。

verbatra translate 2 translated, 12 unchanged

$ npx @verbatra/cli translate
  de: 2 translated, 12 unchanged

de.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(在 en.json 中)。提供商返回了译文,但丢失了 {name}。

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 failed

de.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 保留之前的值。该键仍为过期状态,下次运行时会重试。

一个锁文件,每条命令都读取它。

命令

覆盖整个翻译工作流程

从源代码中的第一个字符串,到线上已审校的译文。

  1. verbatra extract

    verbatra 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 written

    would add 2 keys to messages/en.json

    扫描代码中的翻译调用,在任何人翻译之前,先把新键添加到源语言环境。

    docs/cli/extract
  2. verbatra types

    verbatra-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.ts
    export 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/types
  3. verbatra doctor

    verbatra 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/doctor
  4. verbatra watch

    verbatra 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/watch
  5. verbatra export

    verbatra-translations/de.csv 2 行待翻译

    $ npx @verbatra/cli export --format csv
    verbatra export -> verbatra-translations
      de: 2 rows
    2 rows across 1 locale
    KeySourceStatusTranslation
    checkout.payPay and place orderchanged由译者填写
    checkout.titleReview and checkoutchanged由译者填写

    de: 2 rows

    导出 Excel 工作簿、CSV、TSV 或 XLIFF 交给译者,再导入回来。导入的值受保护,之后的机器运行不会覆盖。

    docs/cli/export
  6. verbatra studio

    verbatra studio 真实截图

    覆盖整个项目的本地仪表盘:浏览所有语言环境,处理审校队列,就地编辑值。

    docs/cli/studio

结果

无论问哪个入口,答案都一样

每个入口读取的都是同一个锁文件,所以在 profile.greeting 被拒绝的情况下,无论在哪里查看,德语都是 1 个过期、13 个最新。

verbatra.lock.json 1 stale, 13 up-to-date

"profile.greeting": "deb45ffcf3548530", stale

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)

Studio

Locales
语言环境覆盖率
LocaleCoverageMissingStaleUp to date
de93% 13 / 14 keys0113

SDK

check()
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

MCP 服务器

不调用提供商
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 与其他工具的对比

决定翻译工作流的关键点,针对团队最常比较的工具逐一作答。

Verbatra 与 Crowdin、Tolgee、Lingo.dev 和手动流程的对比
问题VerbatraCrowdinTolgeeLingo.dev手动流程
无需供应商账号即可使用是否部分否是
使用你自己的提供商密钥是是部分部分是
只翻译已更改的键是部分部分是否
翻译缺失或过期时让 CI 失败是是否是否
翻译后检查占位符和 ICU是是是部分否
面向译者的网页编辑器部分是是部分否

最后核查于 2026年11月16日

常见问题

安装 Verbatra 之前

简短的回答,每条都附有可深入了解的文档页面。

Verbatra 免费吗?

是的。Verbatra 免费,采用 MIT 许可证 (在新标签页中打开)开源;你只需为已更改的键向提供商付费,运行前估算费用可以先估出规模。

Verbatra 支持哪些翻译提供商?

Anthropic、OpenAI、Gemini、DeepL、Google Cloud Translation、OpenCode、OpenAI-compatible和LibreTranslate。在 provider 中设置其一,只由人工翻译时设为 none;提供商页面逐一介绍。

Verbatra 会把我的字符串或 API 密钥发到别处吗?

只发给你配置的提供商,且仅在命令翻译时发送;没有遥测。密钥只留在环境变量中,数据处理与隐私页面列出各提供商会收到什么。

缺少翻译时,Verbatra 能让 pull request 失败吗?

是的。只要有语言环境存在缺失或过期的键,verbatra check 就以退出码 1 退出,无需 API 密钥;GitHub Action 会在 pull request 上运行它。

Verbatra 与其他 i18n 工具有何不同?

它是在你自己提交的文件上运行的 CLI,不是托管平台。对比表格把它与其他工具逐项对照,也包括对方更强的地方。

在花掉任何 token 之前

先做一次试运行

这条路径适用于已有语言文件的项目,两个步骤都不需要 API 密钥。

npx @verbatra/cli init
npx @verbatra/cli translate --dry-run