translate-book

translate-book 技能概览

translate-book 是什么

translate-book 技能是一套面向 PDF、DOCX 和 EPUB 文件的图书翻译流水线。它会先把源书拆成 Markdown 分块，再由多个并行子代理分别翻译这些块，最后把结果重建为 HTML、DOCX、EPUB 和 PDF。对于长篇内容的 Translation 工作，如果你需要 translate-book，而单个提示词对整本书来说太脆弱或上下文太短，这套流程会很有帮助。

适合谁安装

如果你经常翻译书籍、手册或书籍长度的文档，并且在意可重复输出、按分块续跑能力和格式重生成，建议安装 translate-book。它特别适合想要一套引导式工作流、而不是从零手写一次性翻译提示词的用户。如果你只需要一小段摘录或快速摘要，它就没那么合适。

它的不同之处

translate-book 技能的核心差异在于流水线设计：转换、分块、并行翻译、hash 校验和重建都是明确步骤。这种结构能减少上下文丢失，也有助于在最终组装前发现遗漏或过期的分块。相比一个泛泛的“把这个文件翻译一下”的提示词，它还能给你更清晰的安装判断，因为这个 repo 对工具链和输出产物都有明确偏好。

如何使用 translate-book 技能

安装并检查前置条件

先按项目提供的安装流程执行，然后确认流水线依赖的外部工具都已可用：python3、pandoc，以及 Calibre 的 ebook-convert 或 calibre。如果缺少 ebook-convert，translate-book install 这一步可能能成功，但工作流会在转换阶段失败，所以务必先验证运行环境。

从完整输入提示开始

这个技能最适合你一次性提供文件路径、目标语言和任何风格约束。一个好的提示词示例是：Translate /path/to/book.epub into Japanese, keep technical terms consistent, preserve chapter structure, and use a formal tone. 这样能让 translate-book usage 拿到足够上下文来选择参数，减少来回沟通。如果你省略文件路径，技能应该直接停止并向你索取。

先读对文件

如果你是从安装决策角度评估，建议先读 SKILL.md，然后再看 README.md、AGENTS.md 和 CLAUDE.md，了解实现与测试说明。在这个 repo 里，脚本比只扫一遍 README 更重要：scripts/convert.py、scripts/manifest.py、scripts/glossary.py 和 scripts/merge_and_build.py 会说明分块如何生成、如何追踪、如何保持一致，以及如何重建。这是最快判断 translate-book 是否符合你工作流的方式。

按分块感知的方式工作

不要把它当成一次性的翻译调用。它预期的流程是：输入文件 → Markdown 分块 → 翻译后的分块输出 → 合并成整本书。提问时，要把任何会影响分块质量的因素讲清楚：脚注、表格或代码块是否必须完整保留；专有名词是否要保持不译；是否需要整本书统一术语表。这些信息能帮助子代理减少后续会互相冲突的局部决定。

translate-book 技能 FAQ

translate-book 适合新手吗？

如果你能提供文件路径和目标语言，那么答案是适合。这个技能把多步骤流水线隐藏起来了，但它仍然要求你理解书籍级别的约束，比如格式保真和术语一致性。新手通常从较短的 EPUB 或 DOCX 开始，效果会比直接上大型扫描版 PDF 更好。

什么时候不该用 translate-book？

如果只是短段落、随便聊聊式的翻译，或者你只需要大意，就不该用它。对于 OCR 很差、扫描很重的 PDF，它也不是最佳选择，因为源文件转换质量会直接限制后续翻译质量。如果输入文件本身无法干净转换，任何提示词都没法把结构完整救回来。

它和普通翻译提示词有什么不同？

普通提示词通常只在一个上下文窗口里完成翻译，容易出现截断、漂移和术语不一致。translate-book 围绕分块、校验和重建步骤构建，所以更适合需要保持连续性的长文档。代价是前期设置更多，依赖检查也更多。

translate-book 适用于任何语种组合吗？

这个 repo 面向多种目标语言设计，但质量仍然取决于源内容复杂度和术语负载。最好的结果通常来自明确指定目标语言代码，并为领域术语提供术语表指引。对于 Translation 密集型项目，这种一致性指引和语言选择本身一样重要。

如何改进 translate-book 技能

给出更好的源文件约束

最大的质量提升来自告诉 translate-book 哪些内容绝对不能变。请提供要保留的章节标题、保持英文不译的术语、偏好的音译、表格或代码块的格式规则，以及受众层级，比如学术风格还是面向普通读者的语气。例如：Keep API names unchanged, translate prose formally, and preserve Markdown headings exactly.

尽早减少术语漂移

由于流水线使用并行子代理，如果你不在前期定义关键术语，术语就容易漂移。在处理大部头书籍之前，先准备一个小型术语表，包含名称、产品术语和重复出现的技术短语。对于 translate-book for Translation 项目来说，这一点尤其重要，因为一个不一致的术语会在很多分块里扩散开。

留意转换和分块失败

常见失败模式包括 OCR 破损、源格式异常，以及分块边界把表格或列表切得很别扭。如果第一次输出看起来不均衡，先检查中间分块文件和 manifest，再去怀疑翻译质量。最有用的 translate-book guide 习惯是先修好源流水线，再用干净分块重新跑翻译。

基于首轮结果继续迭代

第一轮完成后，不要只看最终合并好的整本书，最好抽查几段具有代表性的分块。重点看章节开头、术语表、标题，以及源文中格式密集的地方。如果需要，优先通过更严格的指令重新跑一遍，而不是手工改整本书；这通常是提升下一次 translate-book skill 运行结果最快的方法。