跳到正文
跳到正文

文档 / 入门

机器翻译页面

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

用 AI 智能体配置 verbatra

给 AI 编码智能体的简短提示词:在已有 i18n 配置的项目中加入 verbatra,产生任何花费之前先由人工确认。

本页适用于已经提交了语言文件的项目。把上方的给 AI 智能体的提示词粘贴到 Claude Code、Codex、Gemini CLI、Cursor 或任何能运行 shell 命令的智能体中。智能体会按下面的步骤操作,并向你确认三件事:

  • 使用哪个提供商,项目中已有明确选择时除外。
  • API 密钥:智能体在 .env 中留空对应的变量,由你填写,它从不索要密钥。
  • 同意运行:首次真正执行 translate 之前需要你确认,因为它会立即产生花费。

智能体遵循的步骤

智能体:按顺序执行这些步骤,绝不能跳过第 6 步的停下确认。

1. 检查现有配置

更改任何内容之前,先在 package.json 中找出 i18n 库(例如 i18next、vue-i18n 或 next-intl)和语言文件。记下源语言环境、已有的每个目标语言环境,以及带 {locale} 占位符的路径模式,例如 locales/{locale}.json。选择技术栈列出了每个技术栈对应的格式 id 和布局;格式说明哪些文件必须已经存在。没有 i18n 库的纯 JSON:{{name}} 占位符对应 i18next-json,单花括号 {name} 对应 vue-i18n-json。

2. 安装 CLI

npm install --save-dev @verbatra/cli

pnpm、yarn 和 bun 同样可用。不要批准任何安装脚本,无论是 pnpm approve-builds 还是 npm 的 allowScripts:verbatra 不需要它们。

3. 生成配置和智能体文件

npx @verbatra/cli init --provider <provider> --yes --json --agent

除非项目中已有明确选择,否则询问用户使用哪个提供商。不要选择会向用户未同意的服务产生花费的提供商,也不要向 init 传入密钥值。提供商列出了各个 id,none 会关闭机器翻译。init 会检测格式、路径模式和语言环境,输出一个 JSON 信封(envelope),并且从不提示输入。--agent 还会在 AGENTS.md 中写入 verbatra 部分(当 CLAUDE.md 是唯一的指令文件,或已包含 verbatra 部分时,则写入 CLAUDE.md),并把 verbatra MCP 服务器(付费工具关闭)写入它检测到的每个客户端的配置;检测到 Claude Code 或没有检测到任何客户端时,写入 Claude Code 的 .mcp.json。result.agent.clients 列出这些文件。

退出码与错误码操作
0把 result.config 与第 1 步比对,先看 result.sources 中每个标注为 default 的条目;只有文件没有按原样书写语言环境时,才会出现 result.config.files.localeStyle。如有不对,用正确的 --format、--path、--source 或 --targets 加上 --force 重新运行。
2,FORMAT_AMBIGUOUS 或 LAYOUT_AMBIGUOUS从 candidates 中选一个,用 --format 或 --path 重新运行。命名空间文件并排存放:停下来询问用户,因为一份配置只覆盖一个文件路径模式。
2,MISSING_OPTIONS错误信息列出了仍需提供的每个选项
2,CONFIG_EXISTS告诉用户现有配置使用哪个提供商,并等待确认。然后运行 npx @verbatra/cli init --agent --json,它会保留配置,只添加智能体文件。传入 --force 之前先询问。

init 记录了每个选项。

4. 把 API 密钥留给人工

提供商为 none 时跳过此步骤。密钥变量是 result.apiKeyEnvVar;出现 CONFIG_EXISTS 之后它为 null,此时从 npx @verbatra/cli doctor --json 中失败的 api-key 检查里取变量名。把 .env.example 复制为 .env;如果 init 没有写入示例文件,就新建 .env。在其中写下该变量名并留空值,然后告诉用户自行填写。永远不要写入、编造或索要密钥值。不必等待,继续后面的步骤。

5. 不产生花费,检查配置

npx @verbatra/cli doctor --json
npx @verbatra/cli check --json
npx @verbatra/cli diff --json
npx @verbatra/cli translate --dry-run --json

这些命令都不会调用提供商,不需要密钥,也不会写入文件。能在 verbatra.config.ts 中修复的失败 doctor 检查都要修复;只有用户设置好密钥后,api-key 检查才会通过,所以不要在它上面反复重试。check 或 diff 返回退出码 1(不同步)在首次运行前属于预期情况;只有退出码 2 才说明配置有问题。提供商为 none 时,只要还有键留给人工译者,translate --dry-run 就会以退出码 3 退出。只有目标中缺失的键才会被翻译,空字符串算作已存在,所以删除占位用的 "" 键之前先询问。

6. 停下来询问

汇总每个语言环境有多少键待处理,以及 translate --dry-run 报告了什么,然后停下。真正的运行会立即产生花费,自身没有确认提示,所以要等用户明确同意。除非用户要求,否则不要使用 --prune。

7. 获得同意后翻译

npx @verbatra/cli translate --json

报告摘要中的 succeeded、partial 和 failed 列表。状态为 partial 或 failed 的语言环境会保留已成功的部分。

8. 提交并连接

提交 verbatra.config.ts、.env.example(如果存在)、第 3 步生成的指令文件和客户端配置文件、verbatra.lock.json、运行写入后的 verbatra.provenance.json,以及翻译后的语言文件。不要提交 .env、.env.local、.verbatra-local/ 或 verbatra.cache.json;确认 .gitignore 已经覆盖它们。

然后告诉用户重启客户端,并批准该项目的 verbatra 服务器。在 Claude Code 中不要再安装 verbatra 插件,否则会注册两次;claude mcp list 会显示连接情况。init 没有检测到的客户端,需要的唯一一项配置见连接 MCP 客户端。

接下来

在 GitHub 上编辑

本页内容