EPUB Bilingual Translator

大段翻译、全书术语表、严格占位符校验和 Calibre 视觉 QA。

安装与使用

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env
# 在 .env 中填写 OPENAI_API_KEY；在 config/config.yaml 选择模型及服务地址。
.venv/bin/python main.py input/book.epub --bilingual

不带 --bilingual 输出中文版。支持 OpenAI-compatible Chat Completions 服务；保留项目现有模型配置，不自动更换服务商。chunk_size 是字符数，不是 token 数；按模型上下文及输出上限调整。默认每段请求约 24,000 字符，输出预算 16,000 token，超时 180 秒；输出截断不会被当作成功。不同供应商对 max_completion_tokens 的支持应在接入时确认。

指定该书的术语约定：

.venv/bin/python main.py input/book.epub --bilingual --glossary config/glossary.example.json

示例表用于说明格式，请按书籍内容编辑。未指定术语表时，程序先扫描全书，生成 .work/书名/glossary.json，然后所有并发翻译共用这份表。冲突建议保存在 conflicts 中，已确立译名不会被后续章节覆盖；别名碰撞会报错。人物别名应尽量采用完整名称，避免把同姓的其他人物当作主人公。支持 aliases、notes、forbidden_targets 和 exclude_contexts；单独姓氏之后的 family/clan/dynasty/surname 不适用人物译名，更长的明确术语优先匹配。

质量控制

DOM 遍历保留行内标签，图片、数学公式和脚注作为完整对象保护；占位符须次数正确、嵌套合法，还原后须是合法 XHTML。
大段初译后，只重试未通过校验的条目。网络错误、重复输出 ID、缺失条目、截断和占位符错误保持待处理状态，不写入“错误译文”。正常运行有失败时终止，不静默生成不完整中文版。
在原 EPUB 容器上修改正文；保留 OPF、目录链接及层级、原 CSS 引用、图片、字体和其他资源。双语段落避免复制 ID，中文版保留原锚点；列表和表格不会插入无效兄弟节点。
HTML5 修复处理不闭合标签和重复 ID，抽取不会重复处理嵌套列表/段落；支持裸 div、表格单元、图注和混合容器中的直接文本。
已翻译条目按原文、占位符、标题上下文、术语表、模型及风格指南指纹复用；每个 chunk 完成就保存。源文件变更会重新预处理。旧版本缓存会升级，无法安全复用的译文需要重新翻译。

--skip-translation 用于离线调试/部分样例，不代表全书已翻译。--force-clean 重新预处理；--force-restore 兼容旧用法，但现在每次回填前都会重新校验，旧的缓存 HTML 不再直接被信任。

可重复 QA

.venv/bin/pip install -r requirements-dev.txt
.venv/bin/python -m pytest -q
.venv/bin/python scripts/corpus_regression.py

安装 Calibre 和 Poppler，使 ebook-convert、pdftoppm 在 PATH 中。翻译主流程自动保存结构审计；加 --visual-qa 生成页面截图：

.venv/bin/python main.py input/book.epub --bilingual --visual-qa
# 对已有输出检查，默认抽样前 3 个已译章节：
.venv/bin/python scripts/visual_qa.py input/book.epub output/bilingual_book.epub \
  --manifest .work/book/manifest.json --render --out .work/book/visual-qa

QA 输出包括 report.json、原文/译文 PNG、Calibre 日志及 review.html。--chapter 可重复指定 EPUB 内的章节 href；--max-chapters 0 检查所有章节，--pages 控制截图页数。输出保留源书已经存在的问题，并单独列出新增问题；这是工程审计，不替代 EPUBCheck 的完整标准验证。

打开 review.html 看对照图，再用 Calibre 阅读 EPUB 检查目录、脚注跳转和实际分页。发现问题后补充可复现测试、修改代码、重新构建并重渲染，记录检查页码和结果。生成截图不等于视觉通过，自动报告始终标明 visual_review: pending，实际视觉审核写入独立记录。PDF 是 Calibre 转换后的辅助视图，不能代替 EPUB 阅读器验证。

Mac 沙箱中 Calibre 的 Qt 渲染可能需要允许进程运行。QA 使用项目目录中的独立 Calibre 配置，参见 Calibre 环境变量文档，避免影响日常书库配置。

用子 agent 生成的 Manifest 做离线翻译测试，无需外部 API：

.venv/bin/python scripts/build_sample.py input/book.epub path/to/agent-translations.json --out .work/sample
.venv/bin/python scripts/visual_qa.py input/book.epub .work/sample/bilingual-sample.epub \
  --manifest .work/sample/manifest.json --allow-partial --render --out .work/sample/qa

build_sample.py 只接受与当前原文和占位符完全对应的条目，输出明确标为部分样例。完整架构见 doc/architecture_flow.md；本次测试记录见 doc/QA_2026-10-08.md。

中文正文与标题目录

中文正文（包括章首段）使用 2em 首行缩进；标题、图注、引用和注释保持各自布局。原文段落保留出版社样式。中文段落清除原内联 text-indent，以免 !important 覆盖中文规则。

预处理以目录的目标文件／锚点建立标题映射。每个实际章标题只翻译一次，NAV、NCX、书内目录及阅读器文档标题使用同一结果；目录 href、章节 ID、层级和顺序保留。章号、主标题、副标题分成多个块时，精确匹配相邻标题块并分别回填，不合并 DOM。中文模式把独立章号统一成“第一章”，Part 对应“第一部”；双语模式保留英文标题和目录标签。

无法可靠绑定的目录条目仅翻译标签，不改写猜测的章节正文；具体条目记录在 book_structure.json 的 navigation_titles[].binding_note。这类条目需要检查章节标题是否一致，不能视为全书标题同步已经通过。索引、版权、注释全文仍遵守原有跳过策略；导航中这些页面的名称可以翻译。

后续扫描 PDF/OCR 大版本的图文、结构与目录方案见路线图。