---
title: "Verbatra：只翻译已更改键的 i18n 命令行工具"
description: "Verbatra 是开源的 i18n CLI 和 SDK。它找出语言文件中缺失和已更改的键，只用你自己的提供商密钥翻译这些键，并在有键缺失时让 CI 失败。"
---

# 只翻译已更改的内容

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

- [开始使用](https://verbatra.kreitz-webdev.de/zh-CN/docs/quickstart.md)
- [与其他工具对比](https://verbatra.kreitz-webdev.de/zh-CN#compare)

```sh
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

[全部格式](https://verbatra.kreitz-webdev.de/zh-CN/docs/formats.md)

### 提供商

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

[全部提供商](https://verbatra.kreitz-webdev.de/zh-CN/docs/providers.md)

## 锁文件

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

- **编辑**: 你在源文件中更改了 2 个值。
- **比对**: Verbatra 为每个键计算哈希，再与锁文件比对。2 个已记录的哈希不再匹配。
- **发送**: 只有这 2 个键会发送给提供商。其余 12 个不会发送。

**en.json** 2 个已更改

```json
{
  ……另有 12 个，未更改
  "checkout": {
    "title": "Review and checkout", 已更改
    "pay": "Pay and place order" 已更改
  }
}
```

**verbatra.lock.json** 2 stale, 12 up-to-date

```json
{
  "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

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

**de.json** 预先生成，非实时

```json
{
  ……另有 12 个，未更改
  "checkout": {
    "title": "Überprüfen und zur Kasse gehen", 已更改
    "pay": "Bezahlen und Bestellung aufgeben" 已更改
  }
}
```

gemini-2.5-flash, 生成于 2026年11月13日
verbatra.lock.json：2 个哈希已更新。

## 门禁: 提供商出错时，不会写入任何内容

每条候选译文都要先通过完整性门禁，才会进入你的文件。 [docs/translation-safety](https://verbatra.kreitz-webdev.de/zh-CN/docs/translation-safety.md)

- **候选译文**: 你更改了 profile.greeting（在 en.json 中）。提供商返回了译文，但丢失了 {name}。
- **已拒绝**: 门禁把候选译文与源文本比对后拒绝了它，文件保持原样。
- **仍为过期**: 该键保持过期，所以检查仍会失败。

**profile.greeting** gemini-2.5-flash

**en.json** 已更改

```text
- "Welcome back, {name}!"
+ "Good to see you, {name}!"
```

**de** 提供商的回答

```text
"Schön, Sie zu sehen!" {name} 缺失
```

尚未检查，也尚未写入。

**verbatra translate** 未写入 1 integrity-withheld

```text
$ 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** 未更改

```json
"profile": {
  "greeting": "Willkommen, {name}!",
  ...
```

**verbatra check** exit 1

```text
$ 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** 未更改

```json
"profile": {
  "greeting": "Willkommen, {name}!",
  ...
```

de.json 保留之前的值。该键仍为过期状态，下次运行时会重试。

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

## 命令: 覆盖整个翻译工作流程

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

### 从源码提取

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

[`verbatra extract`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/extract.md)

**verbatra extract** 2 个新键

```text
$ 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
```

### 带类型的键

为键和消息参数生成 TypeScript 声明，键名拼错就会导致构建失败。

[`verbatra types`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/types.md)

**verbatra-types.d.ts** 14 个键已声明

```text
$ npx @verbatra/cli types
verbatra types
  14 keys declared, 1 of them taking arguments, from messages/en.json
  wrote verbatra-types.d.ts
```

```ts
export interface VerbatraMessages {
  ……另有 8 个
  "profile.greeting": { readonly "name": VerbatraArgument };
  ……另有 3 个
  "checkout.title": VerbatraNoArguments;
  "checkout.pay": VerbatraNoArguments;
}
```

### 花费之前先了解

doctor 无需 API 密钥即可检查配置，估算则在产生费用前评估一次运行的规模。

[`verbatra doctor`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/doctor.md)

**verbatra doctor** 无需 API 密钥

```text
$ 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)
```

### 构建时监听

开发时保持监听进程运行，每次保存都会翻译源语言环境的更改。

[`verbatra watch`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/watch.md)

**verbatra watch** 每次保存时

```text
$ 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...
```

### 交接给人工

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

[`verbatra export`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/export.md)

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

```text
$ 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 | 由译者填写 |

### 在 Studio 中审校

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

[`verbatra studio`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/studio.md)

**verbatra studio** 真实截图

## 结果: 无论问哪个入口，答案都一样

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

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

```text
"profile.greeting": "deb45ffcf3548530", stale
```

### CLI

```text
$ 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)
```

[docs/cli/check](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/check.md)

### Studio

| Locale | Coverage | Missing | Stale | Up to date |
| --- | --- | --- | --- | --- |
| de | 93% 13 / 14 keys | 0 | 1 | 13 |

[docs/cli/studio](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/studio.md)

### SDK

```ts
import { check } from "@verbatra/sdk";
const summary = await check({ config });
summary.locales[0];
// { locale: "de", missing: 0,
//   stale: 1, upToDate: 13,
//   inSync: false, ... }
```

```sh
npm install --save-dev @verbatra/sdk
```

[docs/sdk/inspect](https://verbatra.kreitz-webdev.de/zh-CN/docs/sdk/inspect.md)

### MCP 服务器

不调用提供商

```text
status.check({})
{ "inSync": false, "locales": [
  { "locale": "de", "missing": 0,
    "stale": 1, "upToDate": 13, ... }
] }
```

```sh
claude mcp add --transport stdio --scope project verbatra -- npx -y @verbatra/mcp
```

[docs/cli/mcp](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/mcp.md)

## 替代方案: Verbatra 与其他工具的对比

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

Verbatra 与 Crowdin、Tolgee、Lingo.dev 和手动流程的对比

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

最后核查于 2026年11月16日

来源:

- **无需供应商账号即可使用**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/sdk/src/config/provider-config.ts> <https://github.com/verbatra/verbatra/blob/main/packages/ai-providers/src/env.ts>
  - Crowdin: <https://crowdin.github.io/crowdin-cli/> <https://github.com/crowdin/crowdin-cli>
  - Tolgee: <https://docs.tolgee.io/tolgee-cli/usage> <https://docs.tolgee.io/platform/self_hosting/licensing>
  - Lingo.dev: <https://lingo.dev/en/docs/cli>
- **使用你自己的提供商密钥**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/ai-providers/src/env.ts>
  - Crowdin: <https://support.crowdin.com/crowdin-ai/> <https://support.crowdin.com/machine-translation/>
  - Tolgee: <https://docs.tolgee.io/platform/projects_and_organizations/llm-providers> <https://docs.tolgee.io/platform/translation_process/machine_translation>
  - Lingo.dev: <https://lingo.dev/pricing> <https://lingo.dev/en/docs/platform/llm-models>
- **只翻译已更改的键**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/sdk/src/flow/locale-run.ts>
  - Crowdin: <https://support.crowdin.com/pre-translation/>
  - Tolgee: <https://docs.tolgee.io/platform/projects_and_organizations/machine-translation-settings>
  - Lingo.dev: <https://lingo.dev/en/docs/cli/ci>
- **翻译缺失或过期时让 CI 失败**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/cli/src/run.ts>
  - Crowdin: <https://crowdin.github.io/crowdin-cli/commands/crowdin-status>
  - Tolgee: <https://github.com/tolgee/tolgee-cli/tree/main/src/commands> <https://raw.githubusercontent.com/tolgee/tolgee-cli/main/src/commands/sync/compare.ts>
  - Lingo.dev: <https://lingo.dev/en/docs/cli/ci>
- **翻译后检查占位符和 ICU**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/core/src/placeholder/integrity.ts> <https://github.com/verbatra/verbatra/blob/main/packages/sdk/src/flow/integrity-gate.ts>
  - Crowdin: <https://support.crowdin.com/project-settings/qa-checks/>
  - Tolgee: <https://docs.tolgee.io/platform/translation_process/qa_checks>
  - Lingo.dev: <https://lingo.dev/en/docs/platform/ai-reviewers>
- **面向译者的网页编辑器**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/studio/src/server/create-studio-server.ts>
  - Crowdin: <https://support.crowdin.com/online-editor/>
  - Tolgee: <https://docs.tolgee.io/platform/>
  - Lingo.dev: <https://lingo.dev/en/docs/api/pipeline/human-review>

## 常见问题: 安装 Verbatra 之前

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

### Verbatra 免费吗？

是的。Verbatra 免费，采用 [MIT 许可证](https://github.com/verbatra/verbatra/blob/main/LICENSE)开源；你只需为已更改的键向提供商付费，[运行前估算费用](https://verbatra.kreitz-webdev.de/zh-CN/docs/estimating-cost.md)可以先估出规模。

### Verbatra 支持哪些翻译提供商？

Anthropic、OpenAI、Gemini、DeepL、Google Cloud Translation、OpenCode、OpenAI-compatible和LibreTranslate。在 `provider` 中设置其一，只由人工翻译时设为 `none`；[提供商页面](https://verbatra.kreitz-webdev.de/zh-CN/docs/providers.md)逐一介绍。

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

只发给你配置的提供商，且仅在命令翻译时发送；没有遥测。密钥只留在环境变量中，[数据处理与隐私](https://verbatra.kreitz-webdev.de/zh-CN/docs/data-handling.md)页面列出各提供商会收到什么。

### 缺少翻译时，Verbatra 能让 pull request 失败吗？

是的。只要有语言环境存在缺失或过期的键，`verbatra check` 就以退出码 1 退出，无需 API 密钥；[GitHub Action](https://verbatra.kreitz-webdev.de/zh-CN/docs/github-action.md) 会在 pull request 上运行它。

### Verbatra 与其他 i18n 工具有何不同？

它是在你自己提交的文件上运行的 CLI，不是托管平台。[对比表格](https://verbatra.kreitz-webdev.de/zh-CN#compare)把它与其他工具逐项对照，也包括对方更强的地方。

相关文档:

- [快速上手](https://verbatra.kreitz-webdev.de/zh-CN/docs/quickstart.md)
- [翻译安全](https://verbatra.kreitz-webdev.de/zh-CN/docs/translation-safety.md)
- [对比表格](https://verbatra.kreitz-webdev.de/zh-CN#compare)

## 先做一次试运行

在花掉任何 token 之前

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

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

- [npm 来源证明](https://www.npmjs.com/package/@verbatra/cli)
- [MIT 许可证](https://github.com/verbatra/verbatra/blob/main/LICENSE)
- [CLI 不发送任何遥测](https://verbatra.kreitz-webdev.de/zh-CN/docs/data-handling.md)
- [90% 覆盖率门禁](https://codecov.io/gh/verbatra/verbatra)
- [CI 工作流](https://github.com/verbatra/verbatra/actions/workflows/ci.yml)
