agame/docs/limboai-stable/.workbuddy/memory/2026-10-15.md

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/类名/节点名/文件名保留英文。