跳到正文
跳到正文

文档 / 入门

机器翻译页面

本页面为自动翻译,可能有错误或表述不够自然。内容以英文版本为准。阅读英文原文。

快速上手

安装 CLI,生成配置,不用 API 密钥预览运行,然后翻译你的第一个语言文件。

学完本页,英文语言文件就有了对应的德文文件,由提供商编写、经 verbatra 检查,另有锁文件,让之后每次运行只翻译已更改的内容。你需要 Node.js ^22.22.0 || >=24,大约 10 分钟。前 4 步不需要账号,也不需要 API 密钥。

已经有语言文件和编码智能体了?

把用 AI 智能体配置 verbatra 中的提示词交给你的智能体。它会围绕项目已有的语言文件添加 verbatra,并在产生任何花费之前停下。下面的步骤从零开始。

以下技术栈另有包含“在应用中加载译文文件”这一步的快速上手:React、Next.js、Vue、Angular 和 Flutter。

步骤

安装 CLI

npm install --save-dev @verbatra/cli

下面的命令使用 npx。使用 pnpm、yarn 或 bun 时,改为运行 pnpm verbatra、yarn verbatra 或 bun run verbatra。如果 pnpm 以 ERR_PNPM_IGNORED_BUILDS 退出,见故障排查。

添加源语言文件

如果项目已经有语言文件,跳过这一步。否则创建一个:

locales/en.json
{
  "greeting": "Hello, {{name}}!",
  "cart": {
    "empty": "Your cart is empty."
  }
}

生成配置

npx @verbatra/cli init --format i18next-json --provider gemini --yes

--format 指定文件格式:选择技术栈列出了每个框架对应的 ID。--yes 直接采用 init 检测到的结果,不再提示;省略它,就要逐一回答 verbatra init 列出的提示问题。

输出
created verbatra.config.ts
created .env.example
created .gitignore (.env, .env.local, .verbatra-local/, verbatra.cache.json)
detected format i18next-json, pattern locales/{locale}.json, locales en (confidence: medium)
next steps:
  - Copy .env.example to .env and set GEMINI_API_KEY there. Never commit .env.
  - npx @verbatra/cli doctor  (Check the setup. It calls no provider and reads no key value.)
  - npx @verbatra/cli translate --dry-run  (Preview what a run would translate, without calling the provider.)

新生成的 verbatra.config.ts 把 en 翻译为 de。要增加语言,把语言环境代码加入 targetLocales。

不用密钥预览运行

npx @verbatra/cli translate --dry-run
输出
verbatra: dry run over 1 locale, no provider call
verbatra: de done, 2 would translate
verbatra translate (dry run)
  de: 2 would translate, 0 unchanged
1 succeeded, 0 partial, 0 failed (dry run: nothing written)
[ok] dry run done in 0.0s, nothing written
next: verbatra translate (run it for real)

这是交互式终端中的形式;通过管道或在 CI 中,每一步还会各有一行输出,见终端输出。试运行不会构造提供商,所以不需要密钥,不产生花费,也不写入任何内容。verbatra doctor 以同样的方式检查其余配置。

翻译

cp .env.example .env

打开 .env,把你的密钥粘贴到 GEMINI_API_KEY= 之后。密钥只会来自环境变量,CLI 会把 .env.local 和 .env 加载到环境中。还没有密钥?Gemini 有免费套餐:在 Google AI Studio 创建一个。其他提供商及其变量见提供商。

npx @verbatra/cli translate

verbatra 把缺失的 2 个键发送给 Gemini,检查每条结果,然后写入德文文件。摘要以 de: 2 translated, 0 unchanged 开头,并列出本次运行用掉的 token。具体措辞取决于模型,例如:

locales/de.json
{
  "greeting": "Hallo, {{name}}!",
  "cart": {
    "empty": "Dein Warenkorb ist leer."
  }
}

检查所有语言环境是否同步

npx @verbatra/cli check
输出
[ok] checking the locales (0.0s)
verbatra check
  de: 0 missing, 0 stale, 2 up-to-date (in sync)
all locales in sync

check 不调用提供商,语言环境一旦不同步就以 1 退出,所以同一条命令可以用门禁拦住 pull request。

刚才发生了什么

  • locales/de.json 的键与源文件相同,顺序也相同,{{name}} 完好保留:丢失占位符的结果会被搁置,绝不写入。见翻译安全。
  • verbatra.lock.json 记录每条译文所对应源字符串的哈希,所以下次运行只发送新增和已更改的键。见锁文件与来源记录。
  • verbatra.provenance.json 记录每个值由哪个提供商和模型写成。见来源记录。
  • verbatra.cache.json 和 .verbatra-local/ 保存可重新生成的翻译缓存和本地运行状态。init 已经把两者加入 gitignore。见翻译缓存。

把语言文件、锁文件和来源记录文件一起提交,让每台机器和你的 CI 都与同一个基线比对。

接下来

在 GitHub 上编辑

本页内容