EPUB 翻译

将英文 .epub 书籍翻译为简体中文 .epub。模型调用由当前聊天环境中的主代理或子代理完成；本技能不绑定 OpenAI、Claude、Gemini 或任何特定 API。

脚本只做确定性的 EPUB 工程处理：

解包 EPUB → 提取正文/目录/元数据文本分块 → agent 翻译 JSONL → 写回 EPUB → 重新打包 EPUB

快速开始

先把 EPUB 拆成待翻译分块：

python3 scripts/translate_epub.py prepare book.epub -w work/book-zh

翻译 work/book-zh/chunks/*.jsonl，把译文写入 work/book-zh/translated/ 下同名 JSONL 文件。

检查是否全部翻译完成：

python3 scripts/translate_epub.py check -w work/book-zh

生成中文 EPUB：

python3 scripts/translate_epub.py build -w work/book-zh -o book.zh-Hans.epub

翻译分块格式

prepare 会从正文 XHTML、EPUB 3 nav.xhtml、EPUB 2 toc.ncx 和 OPF 标题元数据中生成 JSONL 文件，每行一个文本节点：

{"id":"t000001","source":"Chapter 1","translation":""}

翻译时必须：

• 保留每行 JSONL 一行一条记录。
• 保留 id 和 source。
• 只填写 translation 字段。
• 不新增解释、摘要、注释或额外字段。
• 不合并、拆分、重排记录。
• 如果 source 中包含 [t:0]、[t:1] 这类标签占位符，translation 中必须按原数量和原顺序保留；这些占位符代表链接、脚注、斜体、粗体等 EPUB 内联标签。

翻译后示例：

{"id":"t000001","source":"Chapter 1","translation":"第一章"}

agent 工作流

1. 确认输入是 .epub 文件，并确定输出路径；默认建议 <原文件名>.zh-Hans.epub。
2. 运行 prepare，生成 manifest.json、chunks/、translated/ 和解包后的 source/；提取范围包含正文、目录和书名 metadata。
3. 建立术语表：在翻译前，先通读/扫描所有待翻译的文本内容，识别出书中的高频核心专业词汇、专有名词、主要人物姓名或特定短语，在工作目录下建立统一的术语对照表（如 glossary.md），确保后续翻译中术语的前后一致性。
4. 按 chunk 翻译：

- 小书可由主代理逐个处理 chunks/*.jsonl。 - 大书可并行分配给子代理，每个子代理只处理若干 chunk。 - 每个子代理翻译前必须读取 glossary.md，并按其中译名保持术语一致。 - 子代理产物必须写入 translated/chunk-xxxx.jsonl，不要改动 source/。

1. 运行 check，确保所有 id 都有非空 translation，且不存在重复 ID、未知 ID、空白译文或占位符不匹配。
2. 运行 build，把译文写回正文、目录和 metadata，并把 EPUB 语言代码更新为 zh-Hans 后重打包。
3. 抽查输出 EPUB：目录页、前言、第一章、含脚注章节、含图片章节。

翻译原则

• 目标语言：默认简体中文。
• 保留原意、语气、段落边界和阅读节奏。
• 人名、品牌名、专有名词可保留英文；必要时使用自然中文译名。
• 术语前后一致；同一 chunk 内不要反复改译。
• 不翻译 URL、邮箱、代码、命令、文件名、锚点。
• 不删减内容；不因为文本重复、枯燥或短小而跳过。
• 不添加原书没有的解释、总结、标题或译者注。

CLI 命令

常用选项：

失败处理

安装

脚本只使用 Python 标准库，无需安装第三方依赖。