# 2026-10-15

## LimboAI 文档汉化（index.html → index.zh.html）

- 目标：把 readthedocs 离线包（单页 Sphinx 文档，`index.html`，588KB，2190 个可翻译块）汉化为中文。
- 方案：块级抽取 + 占位符标记 + 批量人工翻译 + 回填重建。
  - `_i18n/serialize.py`：把每个块（p/h1-h6/td/th/dt/dd/li）序列化为紧凑模板：
    `<n/>`=不译的内联元素（code/img/abbr 等原样保留），`<lN>...</l>`=链接，`<b>`/`<i>`=加粗/斜体，其余内联标签透明化。
  - `_i18n/make_batches.py`：按首次出现顺序去重并分配稳定 uid，切成 `batches/batchNN.txt`（11 批，1451 条唯一模板）。
  - `_i18n/trans/batchNN.json`：uid → 中文模板（全部 11 批已完成）。
  - `_i18n/build.py`：回填重建 + 校验（标记一致性、结构对比）、页脚/面包屑/abbr title/代码注释润色、侧栏汉化徽标。
- 关键实现坑（后续复用注意）：
  1. 片段回填必须用 `html.parser`，`lxml` 会把裸文本包成 `<p>` 破坏结构。
  2. `<td>` 内含 `<p>` 的“容器块”要跳过重建，否则会拍平丢失内层 `<p>`（280 个，已用容器检测处理）。
  3. 标题里的 `a.headerlink` 需在 clear() 前取出再回填，否则丢失 303 个标题锚点。
  4. 校验只强制 `<n/>`、`<lN>`、`</l>` 必须一致，`<b>/<i>` 允许额外配对。
- 结果：`index.zh.html`（580KB），结构计数与原文件一致（section/p/li/a/code/pre/table/td 全部对齐），无英文残留（仅类名/方法名等标识符保留英文），45 处代码注释已译。
- 术语约定：Behavior Tree→行为树、State Machine→状态机、Blackboard→黑板（类名保留）、Inherits:→继承：、Inherited By:→被继承：、Properties→属性、Method Descriptions→方法说明；所有 API/类名/节点名/文件名保留英文。