跳到正文
跳到正文

参考 / 配置

机器翻译页面

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

配置文件

每个配置项的类型、默认值和引入它的版本,以及配置文件可以放在哪里、错误的配置会如何失败。

verbatra 读取一个不含密钥的配置对象,并在开始任何工作之前校验它。配置中从不读取任何 API 密钥(见提供商),因此可以放心提交配置。

最小配置

verbatra.config.ts
import { defineConfig } from "@verbatra/cli";

export default defineConfig({
  // Locales and files: required
  sourceLocale: "en",
  targetLocales: ["de", "fr"],
  format: "i18next-json",
  files: {
    // {locale} is the only token
    pattern: "locales/{locale}.json",
  },

  // Provider: required; the API key comes from the environment, never from here
  provider: {
    id: "gemini",
    options: {
      // example model id; use your provider's current one
      model: "gemini-2.5-flash",
      maxOutputTokens: 4096,
    },
  },

  // Optional groups, each off or at its default until you add it:
  // tone: "informal",
  // glossary: "glossary.json",
  // network: { policy: "local-only" },
  // sensitiveData: { mode: "warn" },
  // maxTokens: 200000,
  // budgetBehavior: "stop",
});

参见语言环境与文件、provider、glossary、network、敏感数据、预算、rates 和 extract。

defineConfig 只为它的参数提供类型:options.model 会补全提供商的模型 ID,但运行时任何非空字符串都会被接受。

所有配置项

未知的键名在每一层都会被拒绝,只有 $schema 和键名由你自己命名的映射除外,例如 maxLength、rates.table、localeMap 和内联的 glossary,因此 API 密钥无法放进配置。

配置项类型默认值引入版本作用
$schema字符串无0.9.0让编辑器指向 JSON Schema;运行时忽略。
sourceLocale语言环境代码必填0.1.0源字符串所用的语言环境。
targetLocales语言环境代码数组必填0.1.0至少一个;不能包含 sourceLocale,也不能有两个忽略大小写后相同的值。
format格式 ID必填0.1.0语言文件的格式,或指向外部适配器(编写自定义格式适配器)的 custom: ID。
files.pattern字符串必填0.1.0每个语言文件的路径,含 {locale} 占位符。
files.localeStyle"literal"、"posix"、"android""literal"0.7.0{locale} 在路径中的写法。
provider.id提供商 ID必填0.1.0翻译提供商,设为 none 表示不用机器翻译。
provider.options对象必填,none 除外0.1.0提供商的专有选项(见提供商)。
glossary对象或文件路径无0.1.0固定译法、禁用译法和不翻译的术语。
tone"formal"、"informal"、"neutral",或一个映射无0.1.0翻译所用的语气,按提供商应用。映射为每个目标语言环境指定语气,另加 default。新
prune布尔值false0.3.0从目标文件和锁文件中移除孤立的键;translate --prune 会覆盖它。
generatePlurals布尔值false0.3.0为目标语言补全它所需的 CLDR 复数形式。
fuzzyCache.enabled布尔值该块中必填0.11.0复用略有更改的源文本的译文。
fuzzyCache.threshold数字,0.5 到 10.90.11.0新旧源文本需要多相似。
humanEdits"protect"、"suggest"、"overwrite""protect"0.12.0运行如何处理人工写入且已过期的键。
pinnedKeys字符串数组无0.12.0任何机器写入都不会触及的键模式(* 通配符)。
network.policy"any"、"local-only"、"allowlist""any"0.12.0提供商可以连接哪些主机(见限制网络访问)。
network.allowedHosts字符串数组无;"allowlist" 时必填0.12.0额外允许的主机:名称、*.suffix 通配符、IP 或 CIDR 范围。
sensitiveData.mode"off"、"warn"、"block"、"redact"该块中必填;没有该块时为 "off"0.12.0发送前,运行如何处理敏感内容。
sensitiveData.detectors检测器 ID 数组secret、email、iban、credit-card0.12.0要运行的检测器;phone、ip、private-host 需要主动启用。
sensitiveData.patterns字符串数组无0.12.0用于你自己的术语(例如项目代号)的正则表达式。
sensitiveData.allow字符串数组无0.12.0永不报告的匹配;* 是通配符,忽略大小写。
maxBatchSize正整数500.3.0每次提供商请求最多包含的条目数。
maxLength键到正整数的映射无0.11.0按键设置的长度预算,以字素簇计。
maxTokens正整数无0.5.0整次运行的 token 预算。
budgetBehavior"warn"、"stop""warn"0.5.0达到 maxTokens 时是警告还是停止发送。
rates.asOfYYYY-MM-DD 日期该块中必填0.11.0你查看单价的日期。
rates.currency三个大写字母该块中必填0.11.0所有单价的币种,例如 USD。
rates.table单价键到单价的映射该块中必填0.11.0按单价键列出的单价。
extract.framework"i18next"该块中必填0.11.0源代码扫描要查找哪种调用点。
extract.roots字符串数组该块中必填0.11.0要扫描的目录,至少一个。
extract.exclude字符串数组无0.11.0要额外跳过的目录名。
extract.literals.ignore字符串数组无0.11.0doctor --literals 不报告的完整文本。
extract.unused.ignore字符串数组无0.11.0diff --unused 永不报告的键或 * 模式。

语言环境与文件

  • files.pattern 必须包含 {locale}(它唯一的占位符),并相对于项目根目录解析:locales/{locale}.json 变成 locales/de.json。它是字面路径,不是 glob,所以一份配置对应每个语言环境一个文件(见命名空间布局);apple-xcstrings 把所有语言环境解析到同一个消息目录文件(见 Xcode String Catalogs)。

  • files.localeStyle 决定占位符展开成什么:

    • literal 按配置原样写出标签,大多数布局都需要这样。
    • posix 为 gettext 和 Java 的 messages_{locale}.properties 把 - 替换为 _(pt-BR 变成 pt_BR);de-1996 这样的变体没有 posix 写法。gettext-po 按 gettext 的方式书写文字(见下一节)。
    • android 展开为资源目录,写作 res/{locale}/strings.xml:源语言环境用 values,其后是 values-de、values-pt-rBR、values-b+zh+Hans。

    样式无法表示某个语言环境时,会拒绝该语言环境。

gettext 语言环境名称

使用 format: "gettext-po" 和 localeStyle: "posix" 时,文件采用 gettext 名称(language_REGION@modifier),而配置仍使用 BCP 47 代码:

配置中的代码文件名
pt-BRpt_BR
es-419es_419
sr-Latnsr@latin
sr-Latn-RSsr_RS@latin
uz-Cyrluz@cyrillic
ks-Deva-INks_IN@devanagari
zh-Hant-TWzh_TW
sr-Cyrl-RSsr_RS

语言和地区已经隐含的文字会被省略,因此 zh-TW 与 zh-Hant-TW 同时出现会以 LOCALE_PATH_COLLISION 失败;没有 gettext 修饰符的文字,例如单独的 zh-Hant,会以 LOCALE_LAYOUT_INVALID 失败。verbatra init 会把这些名称读回来。其他格式沿用 ICU 写法(sr_Latn)。

语言环境代码

每个语言环境代码都必须是 Intl.getCanonicalLocales 接受的标签,语言子标签为两个或三个字母,否则加载会以 CONFIG_INVALID 失败:pt_BR(使用 localeStyle: "posix" 时请写 pt-BR)和 german 都会被拒绝。有效但不规范的代码,例如 zh-hant-tw 或已弃用的 iw,可以按原样使用。

provider

provider.id 选择一个提供商,或选择 none;none 的 options 可以省略,否则必须是 {}(见不用机器翻译运行)。其他每个提供商都接受 options.localeMap 和 options.requestTimeoutMs(见提供商);自 0.12.0 起,放错位置的键(例如 provider 下的 localeMap)会以 CONFIG_INVALID 失败。

glossary

按固定方式翻译的术语,可以内联写出,也可以是指向同样结构的 JSON 文件的路径(二者不会合并)。版本 1 把每个源术语映射到一个适用于所有语言环境的译文:

verbatra.config.ts
export default defineConfig({
  // ...
  glossary: {
    "Sign in": "Anmelden",
  },
  // or: glossary: "glossary.json",
});

相对路径相对于配置文件所在目录解析;文件必须是 UTF-8 编码,且不超过 1 MiB,并在加载时读取一次。文件缺失、JSON 无效或结构无效时,会以 CONFIG_INVALID 失败,并给出路径,版本 2 还会给出字段。需要 __proto__ 术语时请放进文件,因为 JavaScript 字面量会把它变成原型。

按语言环境的术语表(版本 2)

版本 2 增加了按语言环境设置的译文、禁用译法和保持原样的术语:

glossary.json
{
  "version": 2,
  "terms": [
    {
      "source": "Dashboard",
      "targets": { "de": "Übersicht", "fr": "Tableau de bord" },
      "forbidden": { "de": ["Instrumententafel"] },
      "note": "The start page after sign-in",
      "partOfSpeech": "noun"
    },
    { "source": "Sign in", "target": "Anmelden", "caseSensitive": true }
  ],
  "doNotTranslate": ["verbatra", { "term": "Acme", "caseSensitive": false }]
}
字段含义
version始终为 2;其他数字都会失败。
terms[].source源术语;每个术语只出现一次。
terms[].target没有自己 targets 条目的每个语言环境所用的译文。
terms[].targets按语言环境设置的译文。语言环境先用自己的条目,再用其基础语言的条目(de 涵盖 de-AT),最后用 target;代码按规范形式比较,忽略大小写。
terms[].forbidden语言环境绝不能使用的译法;地区语言环境同样遵守其基础语言的列表。
terms[].caseSensitive匹配术语、译文和禁用译法时区分大小写。默认为 false。
terms[].note、terms[].partOfSpeech自由文本形式的上下文,作为数据发送给 LLM 提供商。
doNotTranslate原样复制、不翻译的术语。纯字符串保持大小写;{ "term", "caseSensitive": false } 可以改变大小写。

每个术语都需要一个 target、一个 targets 条目或一个 forbidden 列表;术语不能禁用自己的译文,不能重复列出同一个语言环境,也不能同时出现在 doNotTranslate 中。任何文本都不能为空白;术语最多 200 个字符,译文或禁用译法最多 2000 个字符,note 最多 500 个字符,partOfSpeech 最多 50 个字符。语言环境的翻译缓存指纹只覆盖它自己的术语。版本 1 的文件保留它的指纹;只有遇到版本 1 无法表达的编辑时,updateGlossaryTerm 才会把它改写为版本 2。

Studio(见在 Studio 中审校)只编辑文件形式,一次一个术语。提供商说明了哪些提供商会应用它;每条输出之后都会被检查(见翻译安全)。

generatePlurals

为 true 时,verbatra 会补全目标语言需要、源文本却没有的 CLDR 复数形式,例如波兰语的 few 和 many,并按 CLDR 序数规则生成序数键(<key>_ordinal_<category>)。只有搭配 LLM 提供商的 i18next-json 支持此功能;其他情况,以及没有 CLDR 规则的语言环境,会得到复数警告(序数按 other 处理)。没有对应的 CLI 选项;SDK 的 translate() 接受按次运行的覆盖值。

fuzzyCache

fuzzyCache: { enabled: true } 让已更改的源文本在与它先前版本的相似度至少达到 threshold 时,复用先前版本的译文,并始终标记为 FUZZY_CACHE_REUSE(见模糊复用);--no-cache 会绕过它。

humanEdits 与 pinnedKeys

humanEdits 适用于值由人写入且已过期的键(来源为 human、import 或 external);匹配 pinnedKeys 的键(例如 ["legal.*", "brand.name"])无论 humanEdits 如何设置,都绝不会被机器写入。* 匹配任意一段字符,包括点号,且匹配区分大小写。每种模式的具体行为见保留人工翻译。

network

参见限制网络访问。

verbatra.config.ts
network: { policy: "local-only", allowedHosts: ["gpu.lan"] }

maxBatchSize

缺失和已更改的条目依次分成子批次发出,每个子批次不超过该大小。没有 CLI 选项可以覆盖它。

maxLength

按键设置的长度限制,用于受布局约束的字符串:

verbatra.config.ts
maxLength: {
  "nav.dashboard": 18,
  "cta.submit": 12,
}
  • 写在这里,或写在 verbatra.limits.json 中: 键按字面匹配,不当作 glob;两处都没有设置的键永不测量。setKeyLengthLimit 只接受源键,因此 Studio 无法限制生成的复数形式;手写的、针对其自身键的条目会生效。锁文件旁边的文件接受 { "version": 1, "maxLength": { ... } },同一个键以配置为准,并由 setKeyLengthLimit 写入。
  • 字素簇:长度按用户感知的字符计算,包括空白:一个表情符号、一个带重音的字母或一个 CJK 字符都算一个。长度正好等于上限时不算超出。
  • 何时检查:translate 为该键产生的每个值,包括复用缓存的值;已是最新的键只有在 check --qa、check --file 或 export --include-unchanged 读取它时才检查。
  • 仅供参考:超出限制的值仍会写入并锁定,并标记 MAX_LENGTH_EXCEEDED 以待审校。

maxTokens 与 budgetBehavior

maxTokens 是整次运行的预算:所有提供商调用(翻译和复数生成)以及所有目标语言环境的输入与输出 token 之和。translate --max-tokens 可以为单次运行收紧它,但不能放宽,并且始终是硬性的 "stop"。

budgetBehavior 决定此时发生什么:

  • 默认的 "warn" 会统计花费并标记超出,但继续运行。
  • "stop" 把它变成对每个提供商都有效的上限。每次请求之前,运行会像运行前估算费用中所述那样预测它的费用,并拒绝会超过 maxTokens 的请求。该请求的键,以及所有尚未尝试的键(该语言环境的其余部分和之后的每个语言环境,它们的差异比对和孤立键报告仍会运行)都会被搁置,保留它们先前的锁文件哈希,并在下次运行时重试。

在 "stop" 下:

  • 每次请求之后,总量会按提供商报告的用量校正,因此运行结束时可能略高于 maxTokens(见运行摘要的 budget)。机器翻译提供商不报告 token,按预测值计入预算。
  • 失败或被截断的请求按全额计费。
  • 预测值会加上固定的 LLM 提示词余量,机器翻译提供商也一样,并且覆盖整个批次,因此低于单个批次预测值的 maxTokens 会让它每次运行都被拒绝。
  • 有键被搁置的语言环境为 partial,一个键都没有写入时为 failed,两者都以退出码 1 退出。在 "warn" 下,退出码从不改变。

预算只约束一次 translate 运行,不约束单个条目的重新翻译;watch 每次运行都从新的预算开始。有预算时,实际运行不允许 --concurrency 大于 1;试运行不受此限。

两个不同的 maxTokens

顶层的 maxTokens 是这个整次运行的预算;Anthropic 的 provider.options.maxTokens 与它无关,只限制单次响应(见提供商)。

rates

由 translate --estimate 读取,并用于为每次已记录的运行计算历史费用。

verbatra.config.ts
rates: {
  asOf: "2026-01-15",
  currency: "USD",
  table: {
    // placeholders: copy the current rates from each provider's pricing page
    "gemini/gemini-2.5-flash": { inputPerMillionTokens: 1, outputPerMillionTokens: 2 },
    deepl: { perMillionCharacters: 1 },
  },
}

table 的键是 provider/model,没有模型的提供商(deepl、google-translate)则直接用提供商 ID。每个条目要么按 token 计费(inputPerMillionTokens、outputPerMillionTokens),要么按字符计费(perMillionCharacters),不能两者兼有;负数单价、超过每百万 1,000,000,000 的单价,或单位错误,都会被拒绝。openai-compatible 和 libretranslate 不会产生账单,因此只报告用量,不给出单价。

extract

只由 extract、doctor --literals 和 diff --unused 读取。

verbatra.config.ts
extract: {
  framework: "i18next",
  roots: ["src", "app"],
  exclude: ["generated"],
  literals: { ignore: ["Acme Inc."] },
  unused: { ignore: ["emails.*"] },
}
  • framework 必须指定一个有提取器的框架(见调用形式);其他值会被拒绝。
  • roots 相对于项目根目录解析;exclude 添加目录名(不是路径),在根目录下的任何位置匹配,并入始终跳过的集合。
  • literals.ignore 匹配字面量的完整文本,空白会被合并,引用会被解码(见未翻译的字面量)。
  • unused.ignore 匹配解码后的键(见 diff --unused)。

查找顺序

verbatra 从工作目录向上查找,取第一个匹配项,查找到最近的含 .git 的目录为止,否则到你的主目录为止(主目录不在工作目录之上时则到工作目录为止),因此它绝不会取用仓库之上的配置:

  1. package.json("verbatra" 属性)
  2. .verbatrarc
  3. .verbatrarc.json
  4. .verbatrarc.yaml
  5. .verbatrarc.yml
  6. .verbatrarc.js
  7. .verbatrarc.cjs
  8. .verbatrarc.ts
  9. verbatra.config.js
  10. verbatra.config.cjs
  11. verbatra.config.ts

--config <path> 改为加载指定的一个文件,路径相对于工作目录;SDK 的优先级见 loadConfig。

编辑器校验

@verbatra/sdk 附带一份由其 zod schema 生成的 JSON Schema,也发布在一个稳定的 URL 上,适用于任何安装方式,包括 npx、依赖提升的 monorepo 和远程智能体:

https://verbatra.kreitz-webdev.de/schema/v1/config.json

离线时,或要固定已安装的版本时,使用包内的副本 ./node_modules/@verbatra/sdk/dist/config-schema.json(见所有 schema)。

.verbatrarc.json 和 .verbatrarc 可以为 VS Code 添加 $schema 键:

.verbatrarc.json
{
  "$schema": "https://verbatra.kreitz-webdev.de/schema/v1/config.json",
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "format": "i18next-json",
  "files": { "pattern": "locales/{locale}.json" },
  "provider": { "id": "gemini", "options": { "model": "gemini-2.5-flash", "maxOutputTokens": 4096 } }
}

没有扩展名的 .verbatrarc 还需要工作区文件匹配:

.vscode/settings.json
{
  "json.schemas": [
    {
      "fileMatch": [".verbatrarc", ".verbatrarc.json"],
      "url": "https://verbatra.kreitz-webdev.de/schema/v1/config.json"
    }
  ]
}

YAML 配置可以使用 YAML Language Server 注释:

.verbatrarc.yaml
# yaml-language-server: $schema=https://verbatra.kreitz-webdev.de/schema/v1/config.json
sourceLocale: en
targetLocales: [de, fr]
format: i18next-json
files:
  pattern: "locales/{locale}.json"
provider:
  id: gemini
  options:
    model: gemini-2.5-flash
    maxOutputTokens: 4096

package.json 不支持 schema;可执行形式的配置由 defineConfig 提供类型。

文档无法检查的内容

只有加载配置时才会检查这些规则:targetLocales 的规则和语言环境代码,localeMap 与 tone 映射的键,openai-compatible 的 baseUrl 和 apiKeyEnvVar 规则,有效的 network.allowedHosts 地址和范围,符合安全规则的 sensitiveData.patterns,以及内联的版本 2 术语表的术语规则。

工作目录与 .env

工作目录(你运行 verbatra 的位置,或 --cwd)是配置查找的起点,也存放环境文件。语言环境路径、verbatra.lock.json、缓存、来源记录文件和 .verbatra-local/ 都相对于项目根目录(即找到的配置所在的目录)解析,所以在子目录中运行会使用同样的文件。使用 --config 时,工作目录就是根目录,配置位于其他位置时,stderr 中会输出一条提示,因为它的术语表路径相对于它自己的目录解析。你传入的路径,例如 --out 或 check --file,相对于工作目录解析。

加载失败时

  • CONFIG_NOT_FOUND:查找的任何位置都没有配置,或 --config 指定的路径不存在。
  • CONFIG_INVALID:找到了配置但无法使用。错误信息会列出每个问题及其键路径;遇到未知键时还会附上“API 密钥来自环境变量”的提示。解析失败会给出文件名(YAML 还会给出行号和列号),但从不引用其内容,并且每条错误信息都会经过密钥脱敏。

两种情况下 CLI 都以退出码 2 退出。

在 GitHub 上编辑

本页内容