wenyi文译PDF翻译指南：MinerU与BabelDOC双后端对比，含中文输出字体配置

wenyi文译PDF翻译指南：MinerU与BabelDOC双后端对比，含中文输出字体配置

【免费下载链接】wenyi将被语言阻隔的作品，带到读者的语言中。Bringing literature into your language.项目地址: https://gitcode.com/gh_mirrors/we/wenyi

wenyi（文译）是一款面向长文献作品的开源 AI 翻译工具，支持一键把PDF 电子书翻译成中文 EPUB、HTML 或 PDF。它内置MinerU（云端解析）与BabelDOC（本地版式回填）两套 PDF 后端，并针对中文输出提供了完整的字体配置方案，本指南带你从零跑通整个流程。

为什么选 wenyi 做 PDF 翻译？

相比常见的"OCR + 逐段翻译"脚本，wenyi 把 PDF 当作一本完整的书来处理：

PDF 输入与 PDF 导出目前均为实验性支持，详见 docs/zh/usage.md。

双后端怎么选：MinerU vs BabelDOC 对比

wenyi 通过配置项pdf_backend选择解析后端，完整配置说明见 docs/zh/configuration.md。

一句话选择：追求省事和兼容性选 MinerU；追求"翻完还是原来那本书的样子"选 BabelDOC。

一键安装与 MinerU 快速开始

安装只需三步（要求 Python 3.10+ 与 uv）：

git clone https://gitcode.com/gh_mirrors/we/wenyi cd wenyi uv sync

然后设置 API 密钥并发起翻译：

export DEEPSEEK_API_KEY=sk-... export MINERU_API_KEY=... uv run wenyi translate book.pdf

MinerU 后端的工作流程：

1. 首次读取 PDF 时调用 MinerU 把整本书转成 HTML；
2. HTML 按源文件 SHA-256 缓存到state/<书名>/targets/zh/source/<哈希>/converted.html，同一本书续跑、换目标格式都会直接复用，不再重复付费转换；
3. 后续按 EPUB 管线走全书翻译，默认输出output/book.zh.epub。

💡 小技巧：转换后的 HTML 可以直接手工修正再续跑，适合 MinerU 对某些复杂表格解析不理想的情况。PDF 解析逻辑见 pdf_reader.py 与 pdf_to_html.py。

BabelDOC 版式保留后端配置三步走

如果你希望译文回填到原 PDF 版式中，按下面三步配置：

1. 安装并启动 bridge 服务：在独立仓库安装wenyi-babeldoc-bridge（AGPL 协议、独立进程、仅 HTTP 通信），默认监听http://127.0.0.1:8765；
2. 修改config.yaml：

pipeline: pdf_backend: babeldoc babeldoc_bridge_url: http://127.0.0.1:8765 # babeldoc_pages: "6-8" # 可选，只处理第 6–8 页

3. 执行翻译：uv run wenyi translate book.pdf会自动经 bridge 的/fillback接口导出 PDF，译后文件默认命名为book.zh.pdf，无需再指定--format pdf。

BabelDOC 后端的关键特性：

• 按 PDF 内置书签（TOC）断章，没有书签时退回单章处理；
• bridge 会把版面识别结果冻结为持久 session，服务重启后可恢复，不会重跑版面识别；长时间翻译建议用WENYI_BABELDOC_STATE_DIR指定持久目录；
• ⚠️ 若所选页面只有扫描图片而没有文本层，wenyi 会提前停止并提示改用 MinerU 或先 OCR。

bridge 客户端实现位于 pdf_bridge/client.py，PDF 状态解析逻辑见 pdf_babeldoc.py。

PDF 导出与中文字体配置详解

翻译完成后，若想把译本导出为 PDF，wenyi 提供两个排版引擎：

引擎一：WeasyPrint（默认，推荐）

uv sync --extra pdf-output uv run wenyi assemble book.html --format pdf

基于系统排版库渲染，支持Noto CJK等 OpenType/CFF 中文字体，中文显示效果最好。

引擎二：fpdf2（轻量跨平台）

不想依赖 Pango 等系统库时，可换用轻量引擎：

uv sync --extra pdf-output-lite uv run wenyi assemble book.html --format pdf --pdf-engine fpdf2

⚠️重点来了：fpdf2 只认带 TrueType 轮廓（glyf表）的字体，Noto CJK 的 OpenType/CFF 版本会被跳过。它会按顺序自动查找系统中的中文字体（macOS 的苹方/黑体、Linux 的文泉驿正黑、Windows 的微软雅黑msyh.ttc/ 宋体simsun.ttc）。

找不到合适字体时，用环境变量显式指定：

export TRANS_NOVEL_PDF_FONT=/path/to/字体.ttc

字体配置要求：

• 文件必须是TTF / OTF / TTC格式；
• 必须是 TrueType 轮廓（文泉驿正黑、微软雅黑均可，Noto CJK OpenType 版不行）；
• 显式指定了不兼容字体时会直接报错，而不是产出损坏的 PDF。

字体探测逻辑可以查看 pdf_writer.py。

常见问题速查

总结

• 大多数用户：设置好两个 API 密钥，一条wenyi translate book.pdf走 MinerU 后端，稳定省事；
• 版式控：部署 BabelDOC bridge，把pdf_backend改为babeldoc，获得原版式 PDF 回填；
• 导出中文 PDF：优先 WeasyPrint；轻量场景用 fpdf2，并记得用TRANS_NOVEL_PDF_FONT指定 TrueType 中文字体。

更多用法（SRT 字幕、DOCX、双语版）请阅读 docs/zh/usage.md，项目架构与状态目录说明见 docs/zh/architecture.md。

【免费下载链接】wenyi将被语言阻隔的作品，带到读者的语言中。Bringing literature into your language.项目地址: https://gitcode.com/gh_mirrors/we/wenyi