雨人翻译书

英语 | 中文

Claude Code 技能，利用并行子代理将整本书（PDF/DOCX/EPUB）翻译成任何语言。

灵感来源于 claude_translater。原项目以 Shell 脚本为入口，通过多步骤脚本协调 Claude CLI 进行分块翻译。本项目则将工作流重构为 Claude Code 技能，使用子代理并行翻译各块，并结合清单驱动的完整性检查、可续接运行以及多格式输出，统一整合到一个管道中。由于项目结构和实现与原项目有显著差异，因此这是一个独立项目，而非分支。

---

工作原理

输入 (PDF/DOCX/EPUB)
  │
  ▼
Calibre ebook-convert → HTMLZ → HTML → Markdown
  │
  ▼
拆分为多个小块 (chunk0001.md, chunk0002.md, ...)
  │  manifest.json 记录各小块的哈希值
  ▼
并行子代理（默认并发8个）
  │  每个子代理：读取1个小块 → 翻译 → 写入 output_chunk*.md
  │  分批执行以遵守 API 速率限制
  ▼
验证（清单哈希校验，源文件与目标文件1:1匹配）
  │
  ▼
合并 → Pandoc → HTML（带目录）→ Calibre → DOCX / EPUB / PDF

每个小块都由独立的子代理处理，拥有全新的上下文窗口。这可以防止在单次会话中翻译整本书时出现的上下文堆积和输出截断问题。

特性

• 并行子代理 — 每批8个并发翻译器，各自拥有隔离的上下文
• 可续接 — 支持按小块续接；已翻译的小块在重新运行时会被跳过（如需更改元数据或模板，请使用全新运行）
• 清单验证 — 通过 SHA-256 哈希追踪，防止陈旧或损坏的输出被合并
• 多格式输出 — HTML（带悬浮目录）、DOCX、EPUB、PDF
• 多语言支持 — 中文、英文、日文、韩文、法文、德文、西班牙文（可扩展）
• PDF/DOCX/EPUB 输入 — Calibre 负责繁重的格式转换工作

先决条件

• Claude Code CLI — 已安装并认证
• Calibre — 必须可用 ebook-convert 命令（下载）
• Pandoc — 用于 HTML↔Markdown 转换（下载）
• Python 3 需配备：
  • pypandoc — 必需（pip install pypandoc）
  • beautifulsoup4 — 可选，用于生成更好的目录（pip install beautifulsoup4）

快速开始

1. 安装技能

选项 A：npx（推荐）

npx skills add deusyu/translate-book -a claude-code -g

选项 B：ClawHub

clawhub install translate-book

选项 C：Git 克隆

git clone https://github.com/deusyu/translate-book.git ~/.claude/skills/translate-book

2. 翻译一本书

在 Claude Code 中，输入：

translate /path/to/book.pdf to Chinese

或者使用斜杠命令：

/translate-book translate /path/to/book.pdf to Japanese

技能会自动处理整个流程——转换、分块、并行翻译、验证、合并，并生成所有输出格式。

3. 查找输出文件

所有文件均位于 {book_name}_temp/ 目录下：

文件	描述
output.md	合并后的翻译 Markdown
book.html	带悬浮目录的网页版
book.docx	Word 文档
book.epub	电子书
book.pdf	可打印的 PDF

流程细节

第一步：转换

python3 scripts/convert.py /path/to/book.pdf --olang zh

Calibre 将输入文件转换为 HTMLZ 格式，随后解压并转换为 Markdown，再将其分割成若干小块（每块约6000字符）。manifest.json 文件会记录每个源小块的 SHA-256 哈希值，以便后续验证。

第二步：翻译（并行子代理）

技能会分批启动子代理（默认并发8个）。每个子代理执行以下步骤：

1. 读取一个源小块（例如 chunk0042.md）
2. 翻译为目标语言
3. 将结果写入 output_chunk0042.md

如果运行中断，再次运行时会跳过已有有效输出文件的小块。失败的小块会自动重试一次。

第三步：合并与构建

python3 scripts/merge_and_build.py --temp-dir book_temp --title "《translated title》"

在合并之前，脚本会进行如下验证：

• 每个源小块都有对应的输出文件（1:1匹配）
• 源小块的哈希值与清单一致（无陈旧输出）
• 输出文件不为空

随后进行合并 → Pandoc 转换为 HTML → 注入目录 → Calibre 生成 DOCX、EPUB 和 PDF。

注意： {book_name}_temp/ 是单次翻译运行的工作目录。若更改标题、作者、输出语言、模板或图片素材，需使用全新的临时目录，或在重新运行前删除现有的最终成果文件（output.md、book*.html、book.docx、book.epub、book.pdf）。

项目结构

文件	用途
SKILL.md	Claude Code 技能定义 — 协调整个流程
scripts/convert.py	PDF/DOCX/EPUB → Markdown 小块，通过 Calibre HTMLZ 转换
scripts/manifest.py	小块清单：SHA-256 追踪与合并验证
scripts/merge_and_build.py	合并小块 → HTML → DOCX/EPUB/PDF
scripts/calibre_html_publish.py	Calibre 包装器，用于格式转换
scripts/template.html	带悬浮目录的网页 HTML 模板
scripts/template_ebook.html	电子书 HTML 模板

故障排除

问题	解决方案
Calibre ebook-convert 未找到	安装 Calibre 并确保 ebook-convert 在 PATH 中
清单验证失败	源小块自分割后发生了变化 — 重新运行 convert.py
缺少源小块	源文件被删除 — 重新运行 convert.py 以重新生成
翻译不完整	重新运行技能 — 它会从上次停止的地方继续
更改了标题/模板/素材但输出未更新	删除临时目录中的 output.md、book*.html、book.docx、book.epub、book.pdf，然后重新运行 merge_and_build.py
output.md 存在但清单无效	输出已陈旧 — 脚本会自动删除并重新合并
PDF 生成失败	确保 Calibre 已安装且支持 PDF 输出

星标历史

如果您觉得这个项目很有帮助，请考虑给它点个 Star ⭐！

赞助

如果这个项目为您节省了时间，请考虑赞助以维持其持续开发和改进。

许可证

MIT

translate-book 快速上手指南

translate-book 是一个基于 Claude Code 的技能工具，能够利用并行子代理（subagents）将整本书籍（PDF/DOCX/EPUB 格式）翻译成任意语言。它通过分块处理、并行翻译和完整性校验，有效避免了长文本翻译中的上下文丢失和输出截断问题。

环境准备

在开始之前，请确保您的系统已安装以下依赖：

1. 核心工具

• Claude Code CLI：需已完成安装并认证登录。
• Calibre：用于电子书格式转换，必须确保 ebook-convert 命令可用。
  • 下载地址：https://calibre-ebook.com/
  • 国内用户若下载缓慢，可尝试寻找国内软件站提供的 Calibre 安装包。
• Pandoc：用于 HTML 与 Markdown 之间的转换。
  • 下载地址：https://pandoc.org/

2. Python 环境

需要 Python 3 及以下 pip 包：

pip install pypandoc
pip install beautifulsoup4  # 可选，用于生成更优质的目录

安装步骤

您可以选择以下任一方式将技能安装到 Claude Code 中：

方式 A：使用 npx（推荐）

npx skills add deusyu/translate-book -a claude-code -g

方式 B：使用 ClawHub

clawhub install translate-book

方式 C：手动 Git 克隆

git clone https://github.com/deusyu/translate-book.git ~/.claude/skills/translate-book

注：若 GitHub 访问较慢，可先克隆镜像源代码后移动至对应目录。

基本使用

安装完成后，直接在 Claude Code 对话界面中输入指令即可启动翻译流程。工具会自动执行格式转换、分块、并行翻译、校验及最终文件生成。

最简单的使用示例

示例 1：自然语言指令 将指定路径的 PDF 书籍翻译为中文：

translate /path/to/book.pdf to Chinese

示例 2：斜杠命令 将指定路径的书籍翻译为日文：

/translate-book translate /path/to/book.epub to Japanese

获取结果

翻译完成后，所有输出文件将保存在 {书名}_temp/ 目录下，包含以下格式：

• output.md：合并后的翻译 Markdown 文件
• book.html：带悬浮目录的网页版
• book.docx：Word 文档
• book.epub：电子书格式
• book.pdf：可直接打印的 PDF 文件

提示：该工具支持断点续传。若翻译过程中中断，重新运行相同命令会自动跳过已完成的章节，仅处理剩余部分。