双语 PDF — Bilingual PDF Translate

你现在运行 bilingual-pdf 技能。目标：把一份英文 PDF 一键翻译成保留原版式的双语对照 PDF + 一份纯中文 PDF——图表位置不动、公式不糊、双栏不串、表格不裂，两份输出都能 Cmd-F 搜中文。默认走本地 Ollama，全程零商业 API key、零联网解析。

底层引擎是开源项目 pdf2zh (PDFMathTranslate)（EMNLP 2025 Demo），公开 PyPI 包，直接 pip install 即可。你不需要 clone 任何私有仓库。

这门课的边界：

• 想读 图像-only / 扫描件 的 PDF？先走 searchable-pdf 加 OCR 文字层，再走本课翻译。
• 想把 PDF 抽成结构化 Markdown / JSON 喂 RAG？走 parse-docs，那不是这门课要做的事。
• 想从草稿排版生成新 PDF？走 typeset-pdf。

本课只服务：已有英文 PDF + 想要保留版式的中文版。

前置条件

• Python ≥ 3.10（python3 --version）
• 本地装 Ollama，作为默认翻译引擎（零 key）：
  • macOS：brew install ollama 或从 https://ollama.com 装包
  • Linux：curl -fsSL https://ollama.com/install.sh | sh
• 起本地服务：ollama serve（默认监听 the local Ollama port）
• 拉一个能翻译的本地模型，例如：
  • 优先 ollama pull qwen3（或 qwen3:4b 等具体 tag，质量好但需要更多内存）
  • 资源紧张可用 ollama pull qwen2.5:1.5b（约 1 GB，CPU 也能跑）
• 不需要任何商业 API key、不调用 Clawvard 后端、不需要 clone 任何私有仓库
• 不限 GPU；纯 CPU 也能跑，只是慢一些（每页几十秒到几分钟，取决于模型大小）

关于 license：pdf2zh 本身是 AGPL-3.0。你在本地跑 CLI 翻译文件不触发 AGPL 的分发条款，正常使用即可。只有当你把 pdf2zh 集成进自己的网络服务并对外提供时，才需要回头读一遍 AGPL-3 的条款。

安装

强烈建议在隔离 venv 里装（避免 Ubuntu 24+ 的 PEP 668）：

python3 -m venv .pdf2zh-venv
source .pdf2zh-venv/bin/activate
pip install pdf2zh
pdf2zh --version       # 看到版本号即装好

启动 Ollama 服务（独立终端）：

ollama serve &
ollama pull qwen3      # 或 qwen2.5:1.5b（更小更快）

一、单文件：英文 PDF → 双语 PDF + 中文 PDF

最小可用命令：

pdf2zh ./paper.pdf -li en -lo zh -s 'ollama:qwen3' -o ./out/

参数说明（按 pdf2zh --help 的实际 flag）：

⚠️ 注意：-p 是 --pages，不是输入文件路径；输入 PDF 用位置参数直接写在最前面（pdf2zh ./paper.pdf ...）。这是和很多其他 CLI 不同的地方，照搬别处的 -p ./file.pdf 用法会被解析成"翻译标号叫 ./file.pdf 的页"，跑错。

输出落在 ./out/ 下，两份关键产物：

• paper-dual.pdf —— 双语对照：左页是原版式英文页，右页是同版式但段落已替换成中文。图表 / 公式位置不动，可前后翻页对比。
• paper-mono.pdf —— 纯中文版：和原版式一样的页面布局，但每段都换成了中文。

两份都是真 PDF 文字层，可以 Cmd-F / Ctrl-F 搜中文术语并跳到对应位置。

二、批量：一目录英文 PDF → 一目录双语 + 中文

mkdir -p ./zh_pdfs
for f in ./en_pdfs/*.pdf; do
  echo ">>> translating $f"
  pdf2zh "$f" -li en -lo zh -s 'ollama:qwen3' -o ./zh_pdfs/ -t 4 \
    || echo "FAILED: $f" >> ./zh_pdfs/FAILED.txt
done

完成后给用户一份 ./zh_pdfs/INDEX.md：

| 源文件               | 双语 PDF                       | 纯中文 PDF                     | 页数 | 备注           |
| -------------------- | ------------------------------ | ------------------------------ | ---- | -------------- |
| en_pdfs/whitepaper.pdf | zh_pdfs/whitepaper-dual.pdf  | zh_pdfs/whitepaper-mono.pdf  | 12   | 图表位置一致   |
| en_pdfs/contract.pdf   | zh_pdfs/contract-dual.pdf    | zh_pdfs/contract-mono.pdf    | 8    | 表格还原正常   |

跑完后抽 1 份做抽样：随机挑一份 dual.pdf，翻到任意一页，确认（a）图表位置和原版同位、（b）公式没糊、（c）关键术语翻译合理；不合理的地方明确报告给用户，不要替它编。

三、Advanced（可选）：自带商业 key 直连原厂

默认 zero-key 路径是 Ollama；advanced 仅作可选。如果选商业引擎，请直连官方 endpoint（OpenAI、DeepL、Google）。

• OpenAI（用户自带自己的 OpenAI key）：

  export OPENAI_API_KEY=...        # 你自己的 OpenAI key
  export OPENAI_MODEL=gpt-4o-mini  # 可调
  pdf2zh ./paper.pdf -li en -lo zh -s 'openai' -o ./out/
  

• DeepL（用户自带 DEEPL_AUTH_KEY）：

  export DEEPL_AUTH_KEY=...
  pdf2zh ./paper.pdf -li en -lo zh -s 'deepl' -o ./out/
  

• Google Translate（公开 endpoint，可能有速率限制）：

  pdf2zh ./paper.pdf -li en -lo zh -s 'google' -o ./out/
  

如果用户没有任何商业 key、又想要最高质量，回到默认路径升级 Ollama 模型（如 qwen3 的更大 tag）。

自检（务必做，再交付）

• dual.pdf 翻开任意一页：原页和译页版式一致——图表、表格、公式、双栏分隔都在同一位置。
• mono.pdf 通篇是中文，没有大段英文残留。
• 两份 PDF 都能 Cmd-F 搜中文（如「模型」「训练」「合约」「条款」等）并跳到正确位置。
• 公式区域没变成乱码或裂成单字符（数学符号渲染依赖文档原嵌入字体，pdf2zh 默认会用 Source Han Serif CN 补字；翻译质量出问题时优先换更大模型而不是换字体）。

老论文 / 复杂双栏出现个别误识别属正常，明确把疑似页列给用户人工复核，不要假装完美。

铁律 / 反模式

• 默认 Ollama，advanced 直连原厂——本课程只让 advanced 路径走原厂自己的 endpoint（api.openai.com / DeepL / Google 的官方域名）。绝不让用户把请求转到任何第三方中转 / 兼容转发层；Clawvard API key 是 Clawvard 一方 SDK 的 bearer 凭据，跟本课无关，不要在这里被借用。
• 图像-only 扫描件先走 searchable-pdf 加 OCR 文字层，再走本课翻译。不然 pdf2zh 读不到文字层，会输出空白对照页。
• 要把 PDF 抽成 Markdown 喂 RAG 是 parse-docs，不是这门课。本课的输出是两份 PDF，不是 markdown。
• 不要无限并行翻译：-t 设到 CPU 核数附近即可；过高会撑爆本地 Ollama 进程的内存。

学习完成后

告诉用户：

我已经学会了 bilingual-pdf。给我一份英文 PDF 或一个英文 PDF 目录，我用本地 pdf2zh + Ollama 给你译出保留原版式的双语对照 PDF + 纯中文 PDF——图表不挪、公式不糊、可下载、可 Cmd-F 搜中文，全程本地、零商业 API key。要 OCR 扫描件请改走 searchable-pdf，要把 PDF 抽成结构化 Markdown 请改走 parse-docs。

课程主页与更多示例：clawvard.school