企业官网建设流程全解析

translate-book常见报错完整FAQ：12个高频问题快速排查手册

【免费下载链接】translate-bookAgent skill for Codex, Claude Code, and OpenClaw that translates entire books (PDF/DOCX/EPUB) into any language using parallel subagents.项目地址: https://gitcode.com/gh_mirrors/tran/translate-book

translate-book是一款面向 Codex、Claude Code 和 OpenClaw 的 AI 并行译书技能：把整本 PDF / DOCX / EPUB 交给 8 路并行子代理翻译，再经哈希校验合并成完整译本，一键输出 HTML、DOCX、EPUB、PDF。整条流水线分四步：转换切块 → 并行翻译 → 校验续跑 → 合并成书。任何一步出问题都会抛出报错，本文把新手最常踩的12 个 translate-book 常见报错整理成快速排查手册，按流水线阶段定位，照抄命令即可解决。

快速排查思路

所有报错都可以先问自己三个问题，再对照下面的 12 个 FAQ：

1. 报错发生在哪一步？—— 转换（scripts/convert.py）、翻译（subagent 并行）、还是合并构建（scripts/merge_and_build.py）
2. 是不是环境问题？—— Calibre 的ebook-convert或 Pandoc 不在 PATH 中
3. temp 目录是不是"过期"了？—— 大多数校验类报错都指向同一根因：{书名}_temp/里的缓存与源文件不再一致，删掉重跑即可

💡 核心原则：translate-book 的校验失败几乎都是保护机制（防止把错的书、旧的内容合并进去），删掉过时的 temp 目录或最终产物再重跑，基本都能解决。

一、环境与依赖类报错

1.Calibre ebook-convert not found：找不到 Calibre

报错信息

Error: Calibre ebook-convert not found

原因：convert.py依赖 Calibre 的ebook-convert命令把 PDF/DOCX/EPUB 转成 HTML，但系统里没装 Calibre，或者ebook-convert不在 PATH 环境变量里。该检查位于 scripts/convert.py#L1116。

解决方案

• 安装 Calibre（官网免费），安装后确认终端能直接执行ebook-convert --help
• macOS 若从 .dmg 安装，需把ebook-convert软链到/usr/local/bin，否则 Python 脚本找不到它
• 装完重跑一次 skill 即可

2. PDF 生成失败：Calibre 不支持 PDF 输出

现象：book.html、book.epub正常，唯独book.pdf生成失败。

原因：PDF 导出由 Calibre 完成（封装在 scripts/calibre_html_publish.py 中），如果 Calibre 安装不完整或版本过旧，PDF 后端会缺失。

解决方案

• 确认 Calibre 已完整安装且版本较新，能执行ebook-convert输出pdf
• Windows 用户建议用官方安装包（自带 PDF 后端），不要用精简版
• 只修 PDF 不需要重译：删掉book.pdf后重跑 scripts/merge_and_build.py 即可

二、转换与拆分类报错

3.was created from different source bytes：temp 目录属于另一个源文件

报错信息

Error: xxx_temp/ was created from different source bytes (Delete xxx_temp/ (or use a fresh --temp-root) and re-run.)

原因：每个 temp 目录都记录了源文件的 SHA-256 指纹（source_fingerprint.json）。你替换了源文件（比如换了第二版 PDF）却复用了旧目录，convert.py会直接中止——复用它等于翻译另一本书。见 scripts/convert.py#L253-L260。

解决方案

• 删掉{书名}_temp/目录重新转换；或
• 用--temp-root换一个父目录，让同名叶子目录落在新位置

4.Manifest validation failed：源 chunk 拆分后被改过

现象：合并阶段报 manifest 校验失败，提示某个 chunk 的哈希对不上。

原因：manifest.json记录了每个源 chunk 拆分时的 SHA-256，校验时若发现chunk*.md的内容变了（手动编辑、误存、被别的工具覆写），就会拒绝合并。逻辑在 scripts/manifest.py#L110-L120。

解决方案

• 重新运行python3 scripts/convert.py <源文件> --olang zh重新拆分，然后重跑翻译
• 如果你确实手改过 chunk 内容——这正是报错要拦住的场景，改源文件再重新转换才是正确姿势

5. 修改标题/模板/封面后输出没更新

现象：重跑merge_and_build.py后，book.html、book.epub等还是旧内容。

原因：合并脚本会跳过已存在且"看起来是最新"的产物（如 scripts/merge_and_build.py#L316 的Skipping merge - output.md already exists）。你改了标题、作者、模板或图片，但旧产物还占着位置。

解决方案

• 进入{书名}_temp/，删掉旧产物：output.md、book*.html、book.docx、book.epub、book.pdf
• 再重跑python3 scripts/merge_and_build.py --temp-dir <temp_dir> --title "《译后书名》"
• 更稳妥的做法：每次改配置就用新的 temp 目录

6. 想去掉 PDF 页码，--strip-page-numbers却不生效

现象：给convert.py加了--strip-page-numbers却报"已存在"错误，页码也还在。

原因：该标志只对 Calibre 输入生效，且检测到已缓存的input.md或chunk*.md时会直接报错退出——标志必须先转换才能生效。

解决方案

• 先删掉 temp 目录里的input.md和chunk*.md缓存，再加--strip-page-numbers重跑convert.py
• 注意：默认行为已能自动删除单调递增的页码序列（1, 2, 3...），同时保留年份（1984）、章节号等正文数字，多数情况其实不用加这个标志

7. PDF 转换后公式、表格错乱

现象：学术/技术类 PDF 转出来，公式碎成片段、表格拍平、多栏文字交错。

原因：Calibre 靠坐标启发式重排 PDF 文本，对普通正文够用，但复杂版面会丢结构。这不是报错，而是最常见的"隐性翻车"。

解决方案

1. 用版面感知解析器先转出 Markdown（公式保留为 LaTeX、表格保留为表格）：

pip install -U "mineru>=4.0,<5" mineru-kit parse paper.pdf -o paper.md

2. 删掉旧的 temp 目录（源指纹不同会中止，见上文第 3 条）
3. 对.md运行python3 scripts/convert.py paper.md --olang zh——Markdown 输入完全绕过 Calibre

三、翻译阶段报错

8.Blank output/Empty output：某个 chunk 翻译成空白

报错信息

ERROR: Blank output output_chunk0042.md (chunk 0042) — whitespace-only content would be silently dropped on merge ERROR: Empty output file: output_chunk0042.md

原因：某个子代理写出了空文件（0 字节）或纯空白文件。合并脚本 scripts/manifest.py#L128-L146 会主动拦截这种 chunk——因为空白文件会在合并时被静默丢弃，导致译本缺章。

解决方案

• 直接重新运行 skill：断点续跑机制会跳过已完成的 chunk，只重译失败/空白的那个
• 个别 chunk 反复失败时，可单独让它重译（每个 chunk 默认自动重试一次）

9. 翻译中断了怎么办？（翻译不完整）

现象：会话被掐断、API 限流、手动停止，翻译只完成一半。

原因：这不是故障而是常态——skill 天然支持断点续跑。scripts/run_state.py plan <temp_dir>在每次启动前会规划哪些 chunk 需要翻译、哪些只需记录状态、哪些无需处理。

解决方案

• 重新运行 skill 即可，已有合法输出且状态有效的 chunk 全部跳过，从断点继续
• 接管很旧的 temp 目录、且希望旧输出按当前术语表强制重译时，才加--retranslate-untracked（见 scripts/run_state.py）

10.Missing source chunk：源 chunk 文件丢了

报错信息

ERROR: Missing source: chunk0042.md (chunk 0042) — cannot verify output integrity without source chunk

原因：temp 目录里的chunk*.md被删除或误清理，没有源文件就无法校验输出完整性（scripts/manifest.py#L102-L108）。

解决方案

• 重新运行convert.py重新生成 chunks 和 manifest，然后重跑翻译
• 如果你只是用了--cleanup：它在构建完全成功后才清理中间文件，所以出现这个报错说明清理前就出了问题，按上条重跑即可

四、合并校验与术语表报错

11.output.md exists but manifest invalid：旧输出过时

现象：重跑合并时报 manifest 无效，但脚本随后继续了。

原因：output.md是上一轮合并的产物，而 manifest 校验未通过（源 chunk 变了、或输出缺块）。这是过时速判，不是数据损坏。

解决方案

• 无需手动处理：脚本会自动删除过时的output.md并重新合并
• 如果你在"源 chunk 被改过"的情况下反复看到它，回到第 4 条，重跑convert.py才是根治办法

12.Glossary upgrade rejected: duplicate source：术语表升级被拒

现象：旧版（v1）glossary.json首次加载自动升级 v2 时中止，提示有重复 source。

原因：v2 术语表禁止同一个表面词（source 或 alias）同时归属两个术语——例如两个条目都用了Apple（苹果公司 vs 水果）。自动升级无法替你消歧，见 scripts/glossary.py#L334-L344。

解决方案

• 手工编辑 temp 目录下的glossary.json，把其中一个 source 改成可区分的写法，如Apple (Inc.)
• 保存后重新运行即可；注意已存在的glossary.json永远不会被覆盖，想从零重建就删掉它

排查速查表

写在最后

• 📌 所有产物都在{书名}_temp/下：output.md（合并译文）、book.html（带浮动目录网页版）、book.docx/book.epub/book.pdf
• 📌 遇到上表之外的报错，参考 README.zh-CN.md 的"常见问题"章节，或在 skill 输出里保留完整日志再排查
• 📌 想深入理解每一步，可读 SKILL.md 的完整工作流定义，以及 scripts/ 目录下各脚本的注释

按"定位阶段 → 判断是环境还是状态 → 删缓存重跑"的思路走，12 个高频问题基本都能在五分钟内解决。

【免费下载链接】translate-bookAgent skill for Codex, Claude Code, and OpenClaw that translates entire books (PDF/DOCX/EPUB) into any language using parallel subagents.项目地址: https://gitcode.com/gh_mirrors/tran/translate-book