文档 / 概念
机器翻译页面
运行的工作原理
翻译流程全貌:从读取源语言环境、找出已更改的键,到写入译文并更新锁文件。
一次运行是一条流程:读取源语言环境,把每个目标与锁文件比对,只把需要处理的内容发给提供商,检查返回的结果,写入文件,并记录结果。无论运行来自 CLI、SDK 还是 watch,流程都相同。
读取源语言环境
格式适配器把源文件读成一组中立的带键条目,因此后续每一步对所有格式的处理方式都一致。源键的值若不符合该格式的消息语法(无效的 ICU),verbatra 会把它单独列出并报告,不会把损坏的值发给提供商。源文件缺失或无法解析时,运行失败,详见 SOURCE_ 和 SOURCE_。
与锁文件基线比对
比对让每次运行都是增量的。verbatra 读取现有的目标文件(文件不存在时视为空,但 xliff 和 apple-xcstrings 的写入器会拒绝缺失的目标),并把每个源键与锁文件(见锁文件与来源记录)比对。锁文件记录了此前翻译过的内容:
| 类别 | 含义 | 运行的处理 |
|---|---|---|
| missing | 目标中没有该键 | 翻译 |
| changed | 源值与记录的哈希不再一致 | 翻译 |
| unchanged | 源值仍与记录的哈希一致,或没有记录 | 不处理 |
| empty source | 源值为空白 | 跳过并单独计数 |
| orphaned | 该键在目标中,但不在源中 | 报告;仅在使用 --prune 或 prune: true 时删除 |
暂缓的键
有两类候选键会暂缓处理。已更改的键若当前值由人工编写或导入,默认受保护(humanEdits);匹配 pinnedKeys 的键从不机器翻译。两类键都保持过期,直到有人处理,详见保留人工翻译。
分批发给提供商
每个候选键先在翻译缓存中查找。命中的值直接复用,不会到达提供商。未命中的键中,源内容相同的键会合并为一组,因此同一段文本每个语言环境只产生一次请求,而不是每个键一次。
这些组按顺序分成子批次发给你的提供商,每个子批次最多 maxBatchSize 个条目(默认 50),并附带条目、该语言环境的术语表条目和你的 tone。某个子批次失败时(速率限制、超时、密钥被撤销),其中的键本次搁置,其余子批次继续运行。每个提供商如何使用这些输入,详见提供商。
校验响应
提供商的输出是数据,不是自由文本。对 LLM 提供商,响应必须符合固定的 schema:
- 响应格式错误,或包含从未请求过的键,整个子批次失败。
- 请求的键在响应中缺失或重复,会再请求一次。
- 之后仍未解决的键,本次运行不翻译。
机器翻译提供商没有响应 schema,但它们的结果同样要经过完整性门禁。
运行完整性门禁
符合 schema 的译文仍可能是损坏的,因此 verbatra 根据候选值本身判断是否接受,从不信任提供商自己的报告。候选译文丢失占位符、破坏 ICU 消息或其内联标记、返回为空或发生退化时,会被搁置,不会写入。具体检查见翻译安全。
通过适配器写入
通过检查的译文合并进目标,由格式适配器以原子方式、按稳定的键顺序写入:目标中已有的键保持原位置,新键按源顺序追加在现有键之后。中断的写入不会留下写了一半的文件,审查 pull request 的人看到的差异小而稳定。
更新锁文件
语言环境写入后,其锁条目用当前的源哈希刷新。本次搁置的键保留之前的哈希,因此下次运行仍会认为它需要处理。每个语言环境都在跨进程的写锁下写入,两次重叠的运行因此不会与过期的基线比对,也不会为同一次调用付两次费。
一次一个语言环境,失败也是数据
每个目标语言环境独立运行,一个语言环境失败不会阻止其他语言环境。运行会按语言环境返回摘要:已翻译、未更改、孤立、搁置、标记为待审校,以及通知。各字段的含义见 RunSummary。
这套设计保证:
- 源文件没有任何编辑时,第二次运行不会调用提供商。
- 被检查拒绝的内容绝不会写入,被搁置的内容也不会记为已完成。
- 试运行(
--dry-run)在比对后停止,返回相同结构的摘要,不会构造提供商,也不会写入文件。
这套设计不做的事:从不判断译文好坏。这要靠审校标记和人工审校。
相关内容
verbatra translate:一次运行的选项、输出和退出码。- 锁文件与来源记录:基线记录了什么。
- 翻译缓存:缓存复用按什么匹配。
- 翻译安全:完整性门禁和审校标记。
- 错误码:一次运行可能报告的所有错误码。