---
title: "文档翻译请求"
---

<!-- i18n: source=docs/architecture/documentation-translation.md blob=f3c39bd59c115e29a52e9ce3c79a91bd7e85666a model=claude-sonnet-5-5 -->
> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/architecture/documentation-translation.md)翻译，内容以英文原文为准。
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/documentation-translation.md), which is authoritative.

<a id="documentation-translation-requests"></a>

翻译生成器将准备好的英文文本拆分为有界请求，并在写入之前检查组装后的译文。英文始终是权威来源。

<a id="request-planning"></a>

## 请求规划

`english_requests` 使用页面范围内的单一计数器分配标题锚点。它优先选择安全的二级标题切分点，并将过大的章节打包为每片最多 16 KiB 的源切片。这些切片用换行符连接后，可以精确还原带锚点的英文。

规划器使用 CommonMark 词法单元的源范围来处理列表项、代码块和表格行。围栏代码和缩进代码、行内代码、完整的 HTML 元素以及注释都保持在一起。表头与其分隔行保持在一起。无法再分且超出大小的单元，会在该页面首次调用模型之前被拒绝。成本估算使用与翻译相同的请求列表。

站点的列表扩展接受两个空格的续行缩进，包括有序列表项。其解析器没有源码映射，因此除 CommonMark 范围外，还通过缩进扫描来保护这些列表项。两种方言的列表项都不可再分。

部分站点扩展表格在 CommonMark 中属于缩进代码。该代码范围保持不可再分，因此存在这种歧义且超出大小的块，会在提供方准入之前被拒绝。在英文中把表格移出其扩展容器即可消除这种歧义。

<a id="original-unit-reconciliation"></a>

## 原始单元对账

`reconcile_completed_units` 是一个纯规划 API，用于在英文修改后保留已完成的请求。它接受历史和当前的 `PreparedSource` 容器，以及完整的 `OriginalUnit` 清单及其摘要。两个容器都包含准备好的链接和页面范围的锚点。每个原始范围和源哈希都必须与历史容器匹配；范围之间的间隙只能是空字符串或一个 LF。清单摘要绑定这些元数据，包括每个被选中的回复引用。

调用方需要对照其请求账本、缓存和被选中的回复回执，验证完整的原始计划和完成状态。缓存文件缺失不能证明任何事情。`reply_ref=None` 的原始单元明确声明：在不确定的尝试得到解决后，没有已完成的回复。已完成且确认存在错误的回复会保留其引用和一个 `UnitFault`；不能通过省略该引用把它变成未完成的工作。调用方还需提供针对整个语言区域/源配对、跨源版本的拒绝记录。

计划只保留唯一、单调、字节完全相同、位于当前解析器安全边界上的完整已完成单元。载荷可以自带其末尾换行，也可以留一个 LF 给组装阶段；相邻的载荷保持相邻。每个处置结果都带有其当前 `SourceContext`、原始来源、错误标识符和精确的分隔符。已完成单元在不调用提供方而被复用时，可以超过请求大小限制。保留范围之外的未完成间隙和新插入的英文使用有界规划器。`chunks.split` 接受 `source_context`，使没有表头的表格切片使用完整当前表格的行边界。

处置结果区分复用、同输入修正、输入已更改和未完成的工作。影响同一个原始单元的源修改和错误共享同一个输入已更改的处置结果。重复的候选、重叠或乱序的范围、不安全的边界、未知的错误以及配对拒绝都会返回冲突。在多个未匹配的原始单元中，若有一个已完成单元发生变化，则需要经过证明的对应切分点；规划器不会猜测划分方式。整页已完成单元的替换不受支持。整页的精确复用仍然可行，但该 API 并不解决所有页面变更的映射。

`chunks.split` 和 `reconcile_completed_units` 都接受 `bounded_new_request_bytes`，其取值为 1 到 16384 的整数，不包括布尔值。默认值保持 16 KiB 的切分。该限制适用于每一个预期的请求，包括输入已更改和同输入的修正。被复用的已完成单元即使超出该限制也保持完整。无法容纳的已更改或有错误的已完成单元会返回冲突，而不是被拆分。

较低的限制可以在回复被截断后细分未完成的工作。调用方需要验证已结算的请求、源范围、回复和用量、所有完成与拒绝状态，以及后续的账本条目。其执行数据包绑定所选的限制和精确的当前计划，包括对应范围和保留的已完成引用。仅有限制本身并不能建立这些证据、解除挂起或准许调用。被截断的响应前缀不是已完成单元，更小的输入也不能保证得到完整的回复。

`translate_text` 接受可信的 `initial_feedback` 以及当前源上下文，用于输入已更改时的约束。`request_system` 将该反馈原样包含在发送给提供方的规范 SYSTEM 中，因此实际的请求载荷绑定了这些约束。反馈限制为 4096 字节的可打印 ASCII 和 LF；空反馈保留默认的 SYSTEM。第一条消息只包含当前英文。不会重放针对旧输入的 assistant 响应；机械重试只能使用针对当前输入返回的响应。无效的反馈或不匹配的源上下文会在产生费用或调用提供方之前被拒绝。

对账计划不会解析回复、准许提供方调用或写入输出。使用方需要验证已解析的回复，并按其当前上下文进行校验，然后验证完整的组装页面。内容不变量和两种表格方言仍然适用。发布还需要对照当前英文进行语义和语言完整性审查；结构上成功并不能消除已确认的错误或拒绝。

<a id="assembled-validation"></a>

## 组装后验证

组装后的页面在其输出目录或文件创建之前，要通过现有的内容不变量和表格检查。表格检查同时使用文档站点的 Markdown 解析器和带表格扩展的 CommonMark：二者的容器规则不同。检查会保留表格组、行、单元格、对齐方式以及单元格是否为空。站点的列表、提示块和代码扩展都参与检查。单元格文本在序列化并还原原始 HTML 之后再度量，因此空标记无法掩盖缺失的文本，转义后的字面标签仍然是文本。

解析器包在翻译依赖和开发扩展中固定了版本。站点解析器的固定版本与文档构建器一致。源字节数限制并不能保证译文回复符合输出 token 的限制。被截断的回复仍然算作失败，结构检查也不能确立翻译质量或行文的完整性。

<a id="source-spelling-contracts"></a>

## 源拼写约定

标签验证区分源拼写和普通描述。针对特定源的名称声明保护精确的产品和项目片段。文件名标签必须与其源链接目标处被跟踪的仓库文件一致；惯用的 `README` 标签可以省略 `.md` 后缀。操作字段声明保护返回的字符串词汇表和一个有文档记录的字段公式。若字符串类型字段的整个描述都是带引号的标识符备选项，则它也声明字面值。仅凭引号、大小写和类似文件名的拼写不能获得豁免。

这些声明需要源证据：包或项目标识、明确的术语、真实的文件目标，或操作的线上约定。修改这些源声明时，需要检查相应的证明及其针对性的回归用例。受保护片段周围的普通限定语仍然要接受标签验证。

现有的站点解析器和 CommonMark 解析器提供表格单元格，包括转义的管道符和行内代码中的管道符。每个有界请求都在其完整的英文容器中检查，而不会把周围的文本发送给提供方。没有源码映射的仅站点单元格在页面组装时检查。重试、组装和已存储页面的检查共用同一规则：受保护的片段必须保留其拼写、出现顺序以及源标签或字段。这是一个有限的源约定，不是语言分类器，也不是语义审查。

<a id="invariants"></a>

## 不变量

- 发送给提供方的每个源切片都在限制之内；所有源字节和页面范围的锚点都在组装后保留。被复用的已完成单元保留其完整载荷。
- 不可再分的单元会在提供方准入之前被拒绝。
- 无论页面如何拆分，提供方设置、输出 token 限制、重试和累计财务检查都对每个请求独立生效。
- 只有组装后验证成功，才会写入输出。

<a id="source-entry-points"></a>

## 源码入口

- `scripts/i18n/translate.py`：`english_requests`、`request_chars`、`translate_page`。
- `scripts/i18n/translate.py`：`request_system`、`translate_text` 和初始反馈。
- `scripts/i18n/reconcile.py`：`reconcile_completed_units`、`OriginalUnit` 和清单绑定。
- `scripts/i18n/chunks.py`：受保护范围、上下文相关的源切分点和已解析的表格单元格。
- `scripts/i18n/context.py`：源拼写声明和残留标签投影。
- `scripts/i18n/requirements.in`：翻译运行时依赖。
