translate-book 上手：用 Claude Code Skill 翻译整本书的工程化流程

translate-book 不是一个“把 PDF 丢给模型然后等结果”的小脚本。它更像一条面向整本书翻译的工程流水线：先把 PDF、DOCX、EPUB 统一转成 Markdown，再按 chunk 拆分，用并行 subagent 翻译，最后用 manifest、术语表和构建脚本把输出合并成 HTML、DOCX、EPUB、PDF。

官方仓库 deusyu/translate-book 将它定义为 Claude Code Skill，主语言是 Python，MIT 许可。项目 README 和 SKILL.md 显示，它依赖 Claude Code CLI、Calibre 的 ebook-convert、Pandoc、Python 3，以及 pypandoc；beautifulsoup4 可用于更好的目录生成。它的核心价值不是“支持多语言”，而是把长文本翻译最容易失控的部分拆成可验证的步骤。

为什么整本书翻译不能只靠一次长会话

书籍翻译的难点不是单段文字，而是长度、连续性和可恢复性。一本书可能被拆成几十到上百个片段。若把全部内容塞进一个对话，容易遇到上下文堆积、输出截断、术语漂移、失败后难以续跑等问题。

translate-book 的设计是让每个 chunk 由独立 subagent 处理。每个 subagent 拿到一个源 chunk、目标语言、术语表、相邻 chunk 的短上下文和翻译规则，然后只写对应的 output_chunkNNNN.md。这样做牺牲了一部分全局上下文，但换来了可并发、可重试、可定位失败点的流程。

核心流水线

用 Calibre 将 PDF/DOCX/EPUB 转为 HTMLZ，再转成 HTML 和 Markdown。
把 Markdown 拆成 chunk0001.md、chunk0002.md 等片段，每片约数千字符。
用 manifest.json 记录每个源 chunk 的 SHA-256，防止源文件变化后继续合并旧输出。
抽样构建 glossary.json，固定人名、地名、组织名和领域术语译法。
默认按 8 路并发启动 subagent 翻译 chunk。
校验源 chunk 与输出 chunk 一一对应，再合并成 output.md。
通过 Pandoc 和 Calibre 导出 HTML、DOCX、EPUB、PDF。

术语表是这类工具能不能用的分水岭

fresh-context subagent 的问题是显而易见的：同一个人名、地名或技术名词可能在不同 chunk 里被翻成不同版本。translate-book 的 README 详细说明了术语表机制：从首尾和中间样本 chunk 中抽取术语，写入 glossary.json，再统计频次；翻译每个 chunk 前，脚本会输出该 chunk 相关术语表，并注入到 subagent prompt。

更重要的是，run_state.json 会记录每个 chunk 使用过的术语状态。后续修改 glossary 的 target、aliases、category 后，系统可以只重译受影响的 chunk，而不是把整本书从头跑一遍。这是它区别于普通“批量翻译脚本”的关键工程设计。

适合的使用场景

需要翻译公版书、长报告、内部手册、技术文档、研究材料。
输入格式来自 PDF/DOCX/EPUB，而不是已经清理好的 Markdown。
希望失败后能从断点继续，而不是重新消耗整本书成本。
需要最终交付 Word、EPUB、PDF 或带目录的 HTML。
愿意在翻译前后维护术语表和校验输出质量。

采用前要看清边界

translate-book 不能替代译审。它能把长文档翻译流程拆得更稳，但文学风格、专有名词判断、版权合规、版式修复、脚注和图片处理仍然需要人工抽检。PDF 转换也会受源文件质量影响，扫描件、复杂双栏、页眉页脚、脚注和公式都可能带来噪声。

更稳的做法是先用一小本书或一个章节跑通完整链路，检查 chunk 质量、术语表、输出格式和合并结果，再处理长书。对需要正式出版或对外分发的内容，至少要做术语抽样、章节抽样和最终格式校对。

最小实践路径

npx skills add deusyu/translate-book -a claude-code -g
# 安装 Calibre、Pandoc，并确保 ebook-convert 可用
# 在 Claude Code 中：
translate /path/to/book.epub to Chinese

输出会落在 {book_name}_temp/ 下，包括 output.md、book.html、book.docx、book.epub、book.pdf。不要把这个临时目录当成垃圾文件随手删掉；它包含 manifest、glossary 和 run_state，是断点续跑和精确重译的依据。

如果你只是偶尔翻译几页文章，translate-book 可能偏重。若目标是稳定翻译整本书或长文档，它的价值就在于把“模型翻译”变成一套可以检查、可以恢复、可以迭代的生产流程。