跳到正文
跳到正文

文档 / 概念

机器翻译页面

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

运行的工作原理

翻译流程全貌:从读取源语言环境、找出已更改的键,到写入译文并更新锁文件。

一次运行是一条流程:读取源语言环境,把每个目标与锁文件比对,只把需要处理的内容发给提供商,检查返回的结果,写入文件,并记录结果。无论运行来自 CLI、SDK 还是 watch,流程都相同。

verbatra translate
en.json
de.json
"cart.checkout": "Checkout"
"cart.checkout": ""
"cart.empty": "Empty"
"cart.empty": "Leer"
"cart.total": "Total"
"cart.total": "Gesamt"
只有已更改的键会发送给提供商,已是最新的键保持不变。

读取源语言环境

格式适配器把源文件读成一组中立的带键条目,因此后续每一步对所有格式的处理方式都一致。源键的值若不符合该格式的消息语法(无效的 ICU),verbatra 会把它单独列出并报告,不会把损坏的值发给提供商。源文件缺失或无法解析时,运行失败,详见 SOURCE_UNREADABLE 和 SOURCE_INVALID。

与锁文件基线比对

比对让每次运行都是增量的。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)在比对后停止,返回相同结构的摘要,不会构造提供商,也不会写入文件。

这套设计不做的事:从不判断译文好坏。这要靠审校标记和人工审校。

相关内容

在 GitHub 上编辑

本页内容