PDFMathTranslate 实用操作指南

快速上手：三种主流使用方式

1. 在线免安装（最推荐，小白首选）

• 公共免费服务：访问 https://pdf2zh.com/ 直接上传翻译
• 沉浸式翻译 - BabelDOC：每月有 1000 页免费额度，访问 https://app.immersivetranslate.com/babel-doc/
• HuggingFace/ModelScope 演示：搜索相关空间即可使用

2. Windows 一键运行（无需编程基础）

1. 前往 GitHub 的 Releases 页面下载 pdf2zh-版本-win64.zip
2. 解压压缩包
3. 双击运行 pdf2zh.exe 即可

• 注意：如果提示无法打开，请先安装 vc_redist.x64.exe

3. 命令行/Python 安装（适合开发者或高级用户）

# 1. 安装依赖 (需 Python 3.11 或 3.12)
pip install pdf2zh

# 2. 翻译单个文件 (生成译文和双语对照版)
pdf2zh example.pdf

# 3. 启动图形界面 (GUI)
pdf2zh -i

🛠️ 核心参数与进阶技巧常用参数列表

• **-i**：启动图形化界面 (GUI)
• **-s**：指定翻译服务（支持 deepl, openai 等）
• **-li**：指定源语言（如 -li en，默认自动检测）
• **-lo**：指定目标语言（如 -lo zh，默认中文）
• **-p**：仅翻译指定页码（如 -p 1-10 只翻前10页）
• **-t**：设置线程数（如 -t 2 加快处理速度）
• **--dir**：批量翻译文件夹
• **--mode**：切换翻译内核（如 --mode precise 使用高精度模式）

实用组合案例

• 高精度翻译：pdf2zh example.pdf --mode precise
• 使用 DeepL 翻译：pdf2zh example.pdf -s deepl
• 生成双语对照 PDF：直接运行 pdf2zh example.pdf，默认生成 example-dual.pdf

🐳 Docker 部署（适合长期本地化使用） 

# 拉取镜像
docker pull byaidu/pdf2zh

# 启动容器 (映射端口 7860)
docker run -d -p 7860:7860 byaidu/pdf2zh

启动后，在浏览器访问 http://localhost:7860/ 即可看到操作界面。

⚠️ 常见问题与避坑指南1. 模型下载失败（报错 DocLayout-YOLO）

• 问题原因：通常是网络无法访问 HuggingFace
• 解决方法：设置环境变量使用镜像站
• Windows 命令行：set HF_ENDPOINT=https://hf-mirror.com
• PowerShell：$env:HF_ENDPOINT = "https://hf-mirror.com"

2. 翻译效果不佳

• 尝试使用 --mode precise 参数，该模式使用 v2.0 内核，对公式和布局的保留更完善（但速度较慢）

3. API 调用

• 注意：当前版本的内部 API 已弃用
• 如需二次开发，请直接调用底层库 BabelDOC 的 babeldoc.high_level.async_translate 函数