---
title: "运行的工作原理"
description: "翻译流程全貌：从读取源语言环境、找出已更改的键，到写入译文并更新锁文件。"
type: "concept"
---
# 运行的工作原理

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

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

<DiffPanel />

## 读取源语言环境 [#读取源语言环境]

格式适配器把源文件读成一组中立的带键条目，因此后续每一步对所有格式的处理方式都一致。源键的值若不符合该格式的消息语法（无效的 ICU），verbatra 会把它单独列出并报告，不会把损坏的值发给提供商。源文件缺失或无法解析时，运行失败，详见 [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#source_unreadable) 和 [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#source_invalid)。

## 与锁文件基线比对 [#与锁文件基线比对]

比对让每次运行都是增量的。verbatra 读取现有的目标文件（文件不存在时视为空，但 `xliff` 和 `apple-xcstrings` 的写入器会拒绝缺失的目标），并把每个源键与锁文件（见[锁文件与来源记录](https://verbatra.kreitz-webdev.de/zh-CN/docs/the-lock-file.md)）比对。锁文件记录了此前翻译过的内容：

| 类别 | 含义 | 运行的处理 |
| --- | --- | --- |
| missing | 目标中没有该键 | 翻译 |
| changed | 源值与记录的哈希不再一致 | 翻译 |
| unchanged | 源值仍与记录的哈希一致，或没有记录 | 不处理 |
| empty source | 源值为空白 | 跳过并单独计数 |
| orphaned | 该键在目标中，但不在源中 | 报告；仅在使用 `--prune` 或 `prune: true` 时删除 |

### 暂缓的键 [#暂缓的键]

<AvailableFrom version="0.12.0" />

有两类候选键会暂缓处理。已更改的键若当前值由人工编写或导入，默认受保护（`humanEdits`）；匹配 `pinnedKeys` 的键从不机器翻译。两类键都保持过期，直到有人处理，详见[保留人工翻译](https://verbatra.kreitz-webdev.de/zh-CN/docs/protecting-human-translations.md)。

## 分批发给提供商 [#分批发给提供商]

每个候选键先在[翻译缓存](https://verbatra.kreitz-webdev.de/zh-CN/docs/the-cache.md)中查找。命中的值直接复用，不会到达提供商。未命中的键中，源内容相同的键会合并为一组，因此同一段文本每个语言环境只产生一次请求，而不是每个键一次。

这些组按顺序分成子批次发给你的提供商，每个子批次最多 `maxBatchSize` 个条目（默认 50），并附带条目、该语言环境的术语表条目和你的 `tone`。某个子批次失败时（速率限制、超时、密钥被撤销），其中的键本次搁置，其余子批次继续运行。每个提供商如何使用这些输入，详见[提供商](https://verbatra.kreitz-webdev.de/zh-CN/docs/providers.md)。

## 校验响应 [#校验响应]

提供商的输出是数据，不是自由文本。对 LLM 提供商，响应必须符合固定的 schema：

- 响应格式错误，或包含从未请求过的键，整个子批次失败。
- 请求的键在响应中缺失或重复，会再请求一次。
- 之后仍未解决的键，本次运行不翻译。

机器翻译提供商没有响应 schema，但它们的结果同样要经过完整性门禁。

## 运行完整性门禁 [#运行完整性门禁]

符合 schema 的译文仍可能是损坏的，因此 verbatra 根据候选值本身判断是否接受，从不信任提供商自己的报告。候选译文丢失占位符、破坏 ICU 消息或其内联标记、返回为空或发生退化时，会被搁置，不会写入。具体检查见[翻译安全](https://verbatra.kreitz-webdev.de/zh-CN/docs/translation-safety.md#完整性门禁)。

## 通过适配器写入 [#通过适配器写入]

通过检查的译文合并进目标，由格式适配器以原子方式、按稳定的键顺序写入：目标中已有的键保持原位置，新键按源顺序追加在现有键之后。中断的写入不会留下写了一半的文件，审查 pull request 的人看到的差异小而稳定。

## 更新锁文件 [#更新锁文件]

语言环境写入后，其锁条目用当前的源哈希刷新。本次搁置的键保留之前的哈希，因此下次运行仍会认为它需要处理。每个语言环境都在跨进程的[写锁](https://verbatra.kreitz-webdev.de/zh-CN/docs/the-lock-file.md#写锁)下写入，两次重叠的运行因此不会与过期的基线比对，也不会为同一次调用付两次费。

## 一次一个语言环境，失败也是数据 [#一次一个语言环境失败也是数据]

每个目标语言环境独立运行，一个语言环境失败不会阻止其他语言环境。运行会按语言环境返回摘要：已翻译、未更改、孤立、搁置、标记为待审校，以及通知。各字段的含义见 [RunSummary](https://verbatra.kreitz-webdev.de/zh-CN/docs/sdk/run-summary.md)。

这套设计保证：

- 源文件没有任何编辑时，第二次运行不会调用提供商。
- 被检查拒绝的内容绝不会写入，被搁置的内容也不会记为已完成。
- 试运行（`--dry-run`）在比对后停止，返回相同结构的摘要，不会构造提供商，也不会写入文件。

这套设计不做的事：从不判断译文好坏。这要靠[审校标记](https://verbatra.kreitz-webdev.de/zh-CN/docs/translation-safety.md#审校标记)和人工审校。

## 相关内容 [#相关内容]

- [`verbatra translate`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/translate.md)：一次运行的选项、输出和退出码。
- [锁文件与来源记录](https://verbatra.kreitz-webdev.de/zh-CN/docs/the-lock-file.md)：基线记录了什么。
- [翻译缓存](https://verbatra.kreitz-webdev.de/zh-CN/docs/the-cache.md)：缓存复用按什么匹配。
- [翻译安全](https://verbatra.kreitz-webdev.de/zh-CN/docs/translation-safety.md)：完整性门禁和审校标记。
- [错误码](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md)：一次运行可能报告的所有错误码。
