文档 / 概念
机器翻译页面
锁文件与来源记录
verbatra.lock.json 和 verbatra.provenance.json 记录什么、如何检测漂移、并发运行如何串行化,以及为什么两者都要提交。
verbatra.lock.json 是每次运行比对所依据的基线,所以运行可以跳过已是最新的内容,并重新翻译已漂移的内容。与它并列的 verbatra.provenance.json 记录每个值由谁或什么写入。
记录的内容
对每个目标语言环境,锁文件为每个已翻译的键记录一个哈希,对应当前译文所依据的源条目,另有一个 version 字段:没有译文,也没有密钥。该哈希涵盖源值,以及它的描述、含义、复数标志和占位符,所以描述有更改,该键同样变为过期。哈希计算前,Unicode 规范化为 NFC,换行符规范化为 LF,所以用 CRLF 换行符重新保存源文件不会产生任何更改。
如何检测漂移
目标语言环境缺少的非空源键属于缺失。对目标已有的键,把当前源哈希与记录的哈希比较:不同说明源值有更改,该键会重新翻译;相同则永远不会发送,所以没有源值编辑的第二次运行不产生费用。流程见运行的工作原理。
受保护的键
例外是值由人编写或导入、且已更改的键:默认情况下这类键受保护(见保留人工翻译),保持过期,不会重新翻译。
接入现有项目
已经包含审校过的译文的语言文件不会重新翻译。首次运行时没有锁文件,所以不存在过期的键:目标已有的键保留原值,只翻译它缺少的键,运行把每个源哈希记录为基线,不产生提供商费用。
接入按键是否存在判断,从不看值,这有两个后果:
- 空值或未翻译的值算作已翻译:删除该键(清空值不够),下次运行才会翻译它。
- 过时的译文会被记录为最新:首次运行前,先修正或删除它。
同一规则会保留手写的复数形式,所以接入时使用 generatePlurals 是安全的。要预览这一切,运行 verbatra diff 或 verbatra translate --dry-run。
更新方式
- 完整运行(
translate、watch或导入)用本次运行的结果替换某个语言环境的条目。 - 单键操作(例如在 Studio 中重新翻译)只合并该键的条目。
无论哪种方式,本次运行中搁置的键(完整性检查或提供商调用失败,或源值是无效的 ICU)都保留之前的哈希,所以下次运行会重试。孤立的键没有条目,排序后的键让差异保持精简。
写锁
两次运行同时处理同一个语言环境,可能都与过期的基线比对而重复付费,所以每次写入都会在 .verbatra-local/ 下为该语言环境持有一个跨进程锁。后来的写入方等待,然后与包含先写入方结果的基线比对。不同语言环境从不互相阻塞。
锁保证的内容:
- 超时不产生费用:
--lock-timeout只限制任何提供商调用之前的等待,所以放弃的语言环境没有花费,也没有写入;记录已写入的文件时,等待上限是完整的默认 10 分钟,不受--lock-timeout限制。 - 过期的锁不会阻塞你:持有进程已不在本机上的锁会立即回收;超过 30 秒未刷新的锁(持有者每 10 秒刷新一次)视为已过期。
- 中断会释放锁:
translate或import期间按 Ctrl-C 或收到 SIGTERM,以及强制停止watch的第二次中断,都会在进程退出前释放所有锁。 - 丢失的锁会停止写入:每个锁带一个随机令牌,每次写入前都会检查;另一次运行接管了锁时,写入以
LOCK_停止,不写入任何内容。CONTENDED
锁不覆盖的情况:
- 来自另一台机器的锁(共享网络驱动器)或来自早于 0.12.0 的 verbatra 的锁,永远不会自动回收;清除步骤见故障排查。
- 检查与写入之间的长时间暂停:在令牌检查之后立刻暂停的运行(机器休眠、进程被停止),恢复后仍可能写入一次。
- 主机名相同的主机:在 Linux 之外,主机名是唯一的机器标识,所以两个主机名相同、共享
.verbatra-local/的容器,可能把对方有效的锁误认为已过期的锁。给每个容器设置各自的主机名或工作副本。
写法不同的语言环境代码
锁文件、缓存和来源记录文件都以配置中的语言环境代码作为状态的键。你改动某个代码的写法(例如把 pt_ 改为 pt-BR)时,下次 translate 或 watch 运行会把旧状态一次性迁移到新的语言环境代码下,并报告 LOCALE_。重命名之前的源值更改仍会重新翻译,缓存的译文仍会复用。
只有在没有歧义时才会迁移:pt-BR 自己没有状态,并且文件中恰好有一种下划线写法(或它的 gettext 写法,例如 sr-Latn 对应的 sr@latin)持有状态,比较时不区分大小写。pt-BR 已有的状态永远不会被覆盖。如果迁移无法写入,该语言环境不运行,并以 LOCALE_ 失败,所以下次运行会再试一次;其他语言环境照常运行。
在此之前,每次读取都把旧状态当作 pt-BR 的状态,且不写入,所以过期的键仍报告为过期。单键写入(编辑、重新翻译、审校决定)和 verbatra import 会以同样的方式先迁移状态。verbatra doctor 的 locale-state 检查会列出遗留的状态。
缺失或损坏
缺失锁文件属于首次运行,不是错误。锁文件无法解析、结构有误、体积过大或版本不受支持时,运行以 LOCK_ 失败,而不是覆盖它,这样你可以恢复它,不会丢失基线。
来源记录:谁写了每个值
verbatra.provenance.json 记录语言文件中的每个现有值由哪条写入路径产生,以及是否有人审校过。较旧的 verbatra(例如固定在 CI 中的版本)会忽略它。
| 来源 | 写入方 |
|---|---|
machine | translate、watch 或单键重新翻译中提供商的应答,附带提供商的 id,已知时还有模型 |
memory | 精确的缓存命中,包括纯人工运行(提供商为 none)填入的每个值 |
fuzzy | 模糊缓存命中 |
human | 人通过 SDK 的 editEntry 所做的编辑,Studio 的编辑对话框即是如此 |
agent | AI 智能体通过 editEntry 并带 actor: "agent" 所做的编辑 |
import | 来自 verbatra import 的已接受行 |
unknown | 对没有记录的值所做的审校决定,或本版本不认识的来源 |
另有两个来源在读取时推导:unrecorded 是没有记录的值,升级后每个键都是如此;external 是不再与其记录的哈希一致的值,因为 verbatra 之外有东西更改了它,例如译者的 pull request、较旧的 verbatra 或一次合并。每次读取返回的字段见 SDK 参考。
该文件保证的内容:
- 稳定的差异:没有译文文本,也没有时间戳,每行一条排序后的记录,所以没有更改的运行会让文件保持不变。发生合并冲突时,取与你保留的语言文件一致的那一侧:不匹配的记录读取为
external,这会保护该值不被重新翻译。 - 新值有新记录:更改了值的写入会用一条新的、未审校的记录替换原记录;值和源都没有更改的写入会保留原记录。
- 没有静默覆盖:文件损坏时,每次写入都以
PROVENANCE_停止,此时还没有任何语言文件被更改;报告则改为省略其来源记录字段。来自较新 verbatra 的文件保持不动,增长到无法再读回的文件不会写入(FILE_ INVALID PROVENANCE_)。FILE_ TOO_ LARGE
它不防篡改;要把它转成报告,见记录机器翻译证据。
审校决定
记录可以带一个审校决定:approved 或 rejected,还可附带可选的 reviewer 名称。Studio 的 Review(审校)页面(在 Studio 中审校)、SDK 的审校函数(审校与重新翻译)和 MCP 审校工具(verbatra mcp)都会写入它们;MCP 工具转达的是某个人的决定,并要求提供其名称。决定只适用于审校人员看到的那个确切的值,该值有更改时,决定会被拒绝。
- 批准只更改来源记录文件,源文本有更改后,该值重新读取为未审校。
- 拒绝会删除该值及其锁条目,所以在下次
translate运行或有人写入新值之前,该键读取为缺失。记录会保留已删除文本的哈希,并丢弃缓存条目,所以运行不会把同一段文本放回去。XLIFF 无法删除单条译文,所以在那里拒绝会以REVIEW_被拒绝。REJECT_ UNSUPPORTED
只有 machine、memory、fuzzy 和 agent 的值会进入审校队列和 --require-reviewed 门禁。check 和 lock.state 中的 byReviewState 计数按记录的决定涵盖每个值,所以人写入或导入、没有决定的值在那里计为 unreviewed,尽管它不在队列中;请结合 byOrigin 阅读。
决定保存在这个已提交的文件中,所以审校队列和 verbatra check --require-reviewed 在任何地方看到的状态都相同,reviewer 名称是公开的;verbatra 从不自动填写它。
提交这两个文件
把 verbatra.lock.json 和 verbatra.provenance.json 与语言文件一起提交,且不要手动编辑:它们是你的团队和 CI 比对所依据的基线,也是回滚(见撤销一次运行)恢复的内容。