文档 / 指南
机器翻译页面
从源代码中提取键
把代码中已调用的翻译键收集到源语言文件,填写源文本,再交给 translate 翻译。
代码走在消息目录前面时,按本页操作:你在组件里写了 t("cart.empty", "Your cart is empty"),想让这个键进入源语言文件,而不用手工复制。对从未做过国际化的项目,也可以从代码出发,而不是从空的 JSON 文件开始。
verbatra extract 读取你的源代码,只写入源语言文件。它不调用提供商,不需要 API 密钥,也不发出网络请求。
你需要:
- 一份 verbatra 配置(没有的话,运行
verbatra init); - 调用 i18next 的
t(...)、$t(...)或i18n.t(...)的代码,这是extract目前读取的唯一框架; - 每个消息目录文件对应一个命名空间。带命名空间的键(如
t("common:nav.home"))只会报告,不会写入,因为一份配置只对应一个文件。
指定源代码位置
添加 extract 块,列出要扫描的目录:
export default defineConfig({
// ...
extract: {
framework: "i18next",
roots: ["src"],
},
});roots 之外的内容不会读取,node_ 和 dist 等构建输出始终跳过。如果某个根目录下有生成的代码,把它的目录名加入 exclude。所有字段见 extract。
预览将添加的内容
verbatra extract --dry-run摘要列出新键,以及提到它们的文件和行,不写入任何内容。继续之前,先看其中三部分:
- new keys(新键):真正运行时会添加到源文件的键。
- dynamic keys(动态键):键不是一个完整字符串的调用点,例如
t("user." + id)或t(`nav.${page}`)。这些键不会写入。手工把它们加入消息目录,或者把调用改成字面量键。 - conflicts(冲突):同一个键在两个调用点有两个不同的默认值。两个值都不会写入,请选定一种文本,并让调用点保持一致。
添加键
verbatra extractverbatra extract
42 files scanned, 18 keys already present
added 3 keys to locales/en.json
new keys (3):
nav.home src/components/Nav.tsx:14
nav.away src/components/Nav.tsx:15
cart.empty src/routes/cart.tsx:31
next: verbatra translate (translate the new keys)调用点上的默认值成为该键的源文本。消息目录中已有的键保留原值,所以再次运行 extract 不会覆盖你的编辑;没有发现新内容的运行会让文件保持逐字节不变。
调用点没有默认值的键,会以空值添加,并在 --json 结果中列为 withoutDefault。翻译之前,先把它的源文本写入源语言文件。
如果你的格式是 xliff 或 apple-xcstrings,先创建源消息目录(.xcstrings 文件在 Xcode 中创建):extract 只向其中追加,从不创建它。
翻译新键
verbatra translate新键在每个目标语言环境中都是缺失的,所以这次运行只翻译它们,不翻译其他内容。批次较大时,先用 --estimate 预览花费。
如果你使用 TypeScript,用 verbatra types 重新生成键声明,这样新键的拼写错误会让编译失败。
让代码与消息目录保持同步
extract 只添加。另外两个只读检查覆盖相反的方向:
verbatra diff --unused列出不再被任何调用点使用的源键。它复用extract的roots,不删除任何内容,是否移除某个键由你决定。该列表何时完整到值得信任,见未使用的源键。verbatra doctor --literals列出从未经过t(...)的面向用户的字符串,例如 JSX 文本或aria-label。哪些算在内、如何排除某一条,见未翻译的字面量。
添加调用点后,随时再次运行 verbatra extract。重复运行是安全的,而且无论发现什么,它都以退出码 0 结束,所以必须在出现新键时失败的 CI 步骤,应读取 --json 中的 added 列表,而不是退出码。
相关内容
verbatra extract:它读取的调用形式、完整报告和 JSON 结果。- 配置文件:
extract块。 verbatra translate:补全目标语言环境。- 错误码:缺少该块时的
EXTRACT_。NOT_ CONFIGURED