pdf2zh 整本批量翻译（Windows 实战）

把整本英文 PDF（或双层可搜索 PDF）翻译成简体中文，保留原版式，输出纯中文 PDF。基于 pdf2zh-next（BabelDOC）。内置 scripts/translate_book.py 自动分批、断点续翻、合并、核验；scripts/verify_pdf.py 做交付核验。

适用场景

• 英译中整本书 / 长报告（几十到上千页）。
• 原生文字 PDF 直接翻；扫描/图片 PDF 需先用 OCR 导出「双层可搜索 PDF（layered.pdf）」再翻。
• 无 API key 的免费环境（用 Bing 网页翻译）或自备 key 的付费引擎。

安装

uv tool install --python 3.12 pdf2zh-next   # 首次运行下载 DocLayout-YOLO 版面模型 + 中文字体（约 500MB）
pip install -r ~/.workbuddy/skills/pdf2zh-windows-batch/scripts/requirements.txt  # 合并与核验用（pypdf）

一键批量翻译（推荐，已固化脚本）

脚本随 skill 分发，位于安装后的 skill 目录 scripts/ 下。以下用 ~/.workbuddy/skills/... 表示用户级安装位置（Windows CMD/PowerShell 把 ~/ 换成 %USERPROFILE%\ 或 $env:USERPROFILE\）：

# Git Bash / macOS / Linux
SK=~/.workbuddy/skills/pdf2zh-windows-batch/scripts/translate_book.py

python "$SK" --pdf 书.pdf                       # 默认 bing 引擎、每批 20 页、断点续翻
python "$SK" --pdf 书.pdf --engine siliconflow --api-key sk-xxx   # 付费引擎提速/提质量
python "$SK" --pdf 书.pdf --batch 20 --start 1 --end 0 --cover 2  # 显式分页/封面

# Windows PowerShell
python "$env:USERPROFILE\.workbuddy\skills\pdf2zh-windows-batch\scripts\translate_book.py" --pdf 书.pdf

手动命令范式（经实测，必须带齐开关）

pdf2zh_next --bing --no-dual --skip-clean --skip-scanned-detection \
  --lang-in en --lang-out zh-CN --pages "START-END" \
  --only-include-translated-page --output <每批独立新目录> <源PDF>

交付核验

python ~/.workbuddy/skills/pdf2zh-windows-batch/scripts/verify_pdf.py 书_中文.pdf

逐页提取（异常隔离），>80 页自动抽样，避免 1GB 级产物整本 extract_text 被沙箱静默杀。检查：页数 ≈ 原书、汉字总数合理、空白页应为 0、首尾页为正文中文。

超大产物瘦身

译完的书动辄数百 MB～1GB。用栅格化工具转纯图片 PDF（文字不可选中但阅读无碍，体积 5–10x 压缩）：

python ~/.workbuddy/skills/pdf2zh-windows-batch/scripts/rasterize_pdfs.py 书_中文.pdf --dpi 150

格式路由与决策约束

• PDF（要看版式/图表）：用 Read 工具多模态逐页看，不靠文本提取。
• Windows 三致命坑：① --skip-clean 绕字体子集化锁文件；② 每批 --output 指向独立新目录绕残留文件删锁（本机删除通道全 FAIL_CLOSED）；③ 任何书都加 --skip-scanned-detection（封面/版权图会让 pdf2zh 误判整本为扫描件而 abort）。根因与脚本对应处理详见 references/engines-troubleshooting.md。
• 扫描件：纯图片 PDF 翻不了，先 OCR 成双层可搜索 PDF。
• >500 页：先按 1-500 / 501-N 拆批（免费单次约 500 页上限）。
• 免费引擎质量：专有名词/长句偶有瑕疵，需人工通读校正。

退出码 / 失败处理

• 首批发即失败 → 检查网络/引擎/安装；其余批失败可重跑脚本自动续翻。
• 报 Permission denied 必是踩了上面两个 Windows 坑，按 references 处理。

深入资料

• 引擎对照、Windows 三致命坑根因、断点续翻/合并、大文件核验与瘦身、脚本陷阱：references/engines-troubleshooting.md
• 商业化：按页计费、付费引擎提价、批量代翻、私有化交付与定价 SOP：references/monetization.md