企业官网建设流程全解析

PDFMathTranslate 完整使用指南：科学论文 PDF 排版保留翻译的安装、CLI 参数与高级配置详解

【免费下载链接】PDFMathTranslate[EMNLP 2025 Demo] PDF scientific paper translation with preserved formats - 基于 AI 完整保留排版的 PDF 文档全文双语翻译，支持 Google/DeepL/Ollama/OpenAI 等服务，提供 CLI/GUI/MCP/Docker/Zotero项目地址: https://gitcode.com/GitHub_Trending/pd/PDFMathTranslate

本文以 PDFMathTranslate（Python 包名pdf2zh）的 README.md 为主线，系统讲解这款面向科研场景的开源 PDF 翻译工具：如何在本地安装、如何用一条命令把英文论文翻译成保留公式、图表、目录与注释排版的译文，以及如何通过命令行高级参数、翻译服务配置、实验性 OCR 与 fast/precise 双内核等能力进行深度定制。读完本文，你将掌握从零部署到生产级参数调优的完整实操路径，并能直接对照本仓库源码理解每一步背后的实现原理。

一、项目定位：什么是 PDFMathTranslate

PDFMathTranslate 是一个开源的科学文献 PDF 翻译工具，核心目标是「翻译科学文档时完整保留排版」。与普通全文翻译工具不同，它在翻译英文（或其他语言）论文时，会保留：

• 📊公式、图表、目录与批注：公式以{v*}占位符保护，图表区域通过版面检测跳过，保证翻译后数学符号与排版不被破坏；
• 🌐多语言与多翻译服务：默认 Google，另支持 DeepL、Ollama、OpenAI、DeepLX、Bing、Gemini 等数十种服务（详见 docs/ADVANCED.md）；
• 🤖多种使用形态：命令行工具、浏览器交互界面（GUI）、Docker 容器部署，并支持作为 MCP 服务器供 Claude 等 Agent 调用。

该工作已被EMNLP 2025 System Demonstrations（Proceedings of the 2025 Conference on Empirical Methods in Natural Language Processing: System Demonstrations, pp. 918–924）接收，论文题目为PDFMathTranslate: Scientific Document Translation Preserving Layouts，官方 BibTeX 引用信息见 README.md 第 5.1 节。

从源码结构看，翻译管线由 pdf2zh/pdf2zh.py（CLI 入口）→ pdf2zh/high_level.py（translate/translate_stream/translate_patch核心流程）→ pdf2zh/converter.py（PDF 内容级转换）逐层驱动，最终同时产出单语译文与双语对照两份 PDF。

二、快速开始：先试用在线服务

不想在本机装任何东西，可以先通过官方在线服务体验效果（注意 demo 计算资源有限，请勿滥用）：

• 公共免费服务 pdf2zh.com（无需安装，官方推荐）；
• Immersive Translate 的 BabelDOC（提供免费额度）；
• HuggingFace 与 ModelScope 上托管的 Docker Demo。

上述入口的具体链接均维护在 README.md 第 3.1 节中，可自行查阅。在线试用确认效果后，再进入本地安装环节。

三、本地安装：五种方式按需选择

3.1 使用 uv 安装（推荐）

先安装 Python（版本需满足3.11 ≤ version ≤ 3.12，与 pyproject.toml 中requires-python = ">=3.11,<3.13"一致），然后：

pip install uv uv tool install --python 3.12 pdf2zh

执行翻译，输出文件生成在当前工作目录：

pdf2zh document.pdf

3.2 使用 pip 安装

pip install pdf2zh pdf2zh document.pdf

3.3 图形界面（GUI）

安装后以浏览器界面启动：

pdf2zh -i

若浏览器未自动打开，访问：

http://localhost:7860/

GUI 的详细使用说明见 docs/README_GUI.md。从 pdf2zh/pdf2zh.py 的源码可以看到，-i会调用pdf2zh.gui.setup_gui，并支持--serverport指定端口、--share生成公网链接、--authorized设置登录鉴权。

3.4 Windows 桌面版

从项目的 release 页面下载pdf2zh-version-win64.zip，解压后双击pdf2zh.exe即可运行；若下载后无法打开，需要先安装微软 VC++ 运行库vc_redist.x64.exe再重试。

3.5 文献管理插件：Zotero

Zotero 用户可借助 Zotero PDF2zh 插件，在文献管理器中直接触发翻译，详见其独立项目文档。

3.6 Docker 容器化部署

docker pull byaidu/pdf2zh docker run -d -p 7860:7860 byaidu/pdf2zh

浏览器访问http://localhost:7860/。若无法访问 Docker Hub，可改用 GitHub Container Registry 镜像：

docker pull ghcr.io/byaidu/pdfmathtranslate docker run -d -p 7860:7860 ghcr.io/byaidu/pdfmathtranslate

此外，README 还提供 Heroku、Render、Zeabur、Sealos、Koyeb 等云平台的模板化部署按钮。本仓库的 Dockerfile 与 docker-compose.yml 可作为自定义构建的参考。

3.7 安装期网络问题处理

程序依赖版面检测模型wybxc/DocLayout-YOLO-DocStructBench-onnx，部分网络环境下载失败时，可通过镜像端点绕过：

# CMD set HF_ENDPOINT=https://hf-mirror.com # PowerShell $env:HF_ENDPOINT = https://hf-mirror.com

四、命令行高级参数全表

在命令行执行翻译后，当前目录会生成两个文件：

• example-mono.pdf：单语译文 PDF；
• example-dual.pdf：原文与译文对照的双语 PDF。

默认翻译服务为 Google。pdf2zh example.pdf一次调用内部经历「下载字体 → PyMuPDF 打开并复制文档 → DocLayout-YOLO 版面检测 → 逐页提取文本 → 翻译 → 回填 → 生成 mono/dual 两份文件」，对应源码位于 pdf2zh/high_level.py。

下表汇总 README 中列出的全部高级选项，并补充了来自 pdf2zh/pdf2zh.py（create_parser）的默认值与参数细节：

关于-p的页码语法：parse_args中支持1-3,5这种逗号+连字符混用写法，连字符会展开为连续区间，最终转换为 0 起始的内部页索引（见 pdf2zh/pdf2zh.py）。

-f/-c的典型用法（用正则保护公式字体与字符，避免被当作正文翻译）：

# 保护指定字体名与数学符号 pdf2zh example.pdf -f "(CM[^RT].*|MS.*|.*Ital)" -c "(\(|\||\)|\+|=|\d|[\u0080-\ufaff])"

默认已保护Latex、Mono、Code、Italic、Symbol、Math类字体：

pdf2zh example.pdf -f "(CM[^R]|MS.M|XY|MT|BL|RM|EU|LA|RS|LINE|LCIRCLE|TeX-|rsfs|txsy|wasy|stmary|.*Mono|.*Code|.*Ital|.*Sym|.*Math)"

五、翻译服务与语言：环境变量与配置文件

5.1 支持的翻译服务

README 与 docs/ADVANCED.md 维护了完整服务清单及所需环境变量，核心摘录如下：

各翻译器类均在 pdf2zh/translator.py 中继承自BaseTranslator实现（如GoogleTranslator直接请求translate.google.com/m端点，BingTranslator会先解析params_AbusePreventionHelper获取签名）。凡是兼容 OpenAI API 的模型，都可以按 OpenAI 的环境变量方式接入。

指定服务（-s service或-s service:model两种写法）：

pdf2zh example.pdf -s openai:gpt-4o-mini

或用环境变量指定模型（以set与 PowerShell$env:两种语法为例）：

set OPENAI_MODEL=gpt-4o-mini pdf2zh example.pdf -s openai

$env:OPENAI_MODEL = gpt-4o-mini pdf2zh example.pdf -s openai

5.2 源语言与目标语言

pdf2zh example.pdf -li en -lo ja

语言代码以各翻译服务的官方代码为准（Google 语言代码、DeepL 语言代码，链接见 docs/ADVANCED.md）。注意部分服务内置了语言映射，例如 Google 将zh映射为zh-CN、Bing 将zh映射为zh-Hans（见 pdf2zh/translator.py）。

5.3 自定义配置文件

配置文件有两种来源：命令行--config指定，或默认读取~/.config/PDFMathTranslate/config.json。配置读取顺序为：先读配置文件，再叠加环境变量；环境变量存在时优先使用环境变量，并回写更新配置文件（对应 pdf2zh/config.py 中ConfigManager.get的实现逻辑）。

示例配置 config.json：

{ "USE_MODELSCOPE": "0", "PDF2ZH_LANG_FROM": "English", "PDF2ZH_LANG_TO": "Simplified Chinese", "NOTO_FONT_PATH": "/app/SourceHanSerifCN-Regular.ttf", "translators": [ { "name": "deeplx", "envs": { "DEEPLX_ENDPOINT": "http://localhost:1188/translate/", "DEEPLX_ACCESS_TOKEN": null } }, { "name": "ollama", "envs": { "OLLAMA_HOST": "http://127.0.0.1:11434", "OLLAMA_MODEL": "gemma2" } }, { "name": "grok", "envs": { "GROK_BASE_URL": "https://api.x.ai/v1", "GROK_API_KEY": "your-api-key", "GROK_MODEL": "grok-2-1212" } } ] }

⚠️ 重要提醒：使用 OpenAI 兼容 API 或自定义代理时，BASE_URL必须以/v1结尾（如https://api.openai.com/v1、http://your-proxy:8000/v1），否则会返回 404。

使用方式：

pdf2zh example.pdf --config config.json pdf2zh -i --config config.json

5.4 作为公共服务部署

若把 GUI 部署为对外公共翻译服务，可在配置文件中增加两项能力：

• ENABLED_SERVICES：只开放白名单内的翻译服务；
• HIDDEN_GRADIO_DETAILS：在 Web 界面隐藏真实 API Key，防止他人窃取服务端密钥。

组合配置示例（完整 JSON 见 docs/ADVANCED.md）：

{ "USE_MODELSCOPE": "0", "translators": [/* 服务密钥配置 */], "ENABLED_SERVICES": ["OpenAI", "Grok"], "HIDDEN_GRADIO_DETAILS": true, "PDF2ZH_LANG_FROM": "English", "PDF2ZH_LANG_TO": "Simplified Chinese", "NOTO_FONT_PATH": "/app/SourceHanSerifCN-Regular.ttf" }

六、实验性特性：自动 OCR（fast 模式）

README 当前主线版本（1.x）新增了实验性自动 OCR 快速模式，用于处理扫描版/纯图片型 PDF：

• 工作原理：翻译前先对「仅含图片的页面」自动执行本地 OCR；原生文本页、已有 OCR 层、空白页会被跳过，双语输出的原页面保持不变；
• 安装方式：pip install 'pdf2zh[ocr]'（从本仓库源码安装则为pip install -e '.[ocr]'）。该可选依赖仅新增pooch（用于缓存下载），OCR 引擎由 PyMuPDF 内置提供，无需单独安装 Tesseract 可执行文件（见 pyproject.toml 与 pdf2zh/high_level.py）；
• 语言数据：首个扫描页会从 Tesseract 的tessdata_fast4.1.0 release 下载对应语言数据到~/.cache/pdf2zh/tessdata/4.1.0，之后离线复用；原生文本 PDF 不会触发下载；
• 语言选择：默认使用输入语言-li对应的 Tesseract 代码（如en→eng、zh→chi_sim、ja→jpn），可用环境变量PDF2ZH_OCR_LANGUAGE=eng+deu覆盖；设置TESSDATA_PREFIX可改用自有语言数据、跳过自动下载；
• 版面处理：OCR 词元会在检测到的版面区域内重新分组为段落，连接折行与软连字符；译文段落以源文字号的中位数起步并自适应收缩回原文本框；检测到的图、表、独立公式保持原样；
• 已知限制：当前实现面向白底扫描件——已含文本页上的局部扫描会被跳过，手写文字与行内公式可能识别错误；precise 模式不受影响。

七、fast 与 precise：双翻译内核架构

自 2026 年 3 月起，项目引入实验性的v2.0 翻译内核，通过隔离环境运行（--mode precise），与默认 v1 内核（fast）并存：

pdf2zh --mode precise example.pdf

从源码看，模式切换通过 pdf2zh/kernel/registry.py 的线程安全注册表KernelRegistry.switch()完成：precise 内核会先ensure_venv()校验隔离虚拟环境，再检查可用性（对应 pdf2zh/kernel/precise.py）。安装后需运行pdf2zh-setup-precise准备隔离环境（该入口声明于 pyproject.toml）。v2 的正式版已发布在独立仓库 PDFMathTranslate/PDFMathTranslate-next 下；两分支定位差异详见 README.md 第 4.3 节——主分支面向稳定发布与社区贡献，next 分支侧重 Web UI 与边角场景处理、跨栏跨页语义一致性等质量优化，但不保证兼容性、不面向社区贡献。

八、翻译缓存机制

为加速重复翻译并节省 API 调用，pdf2zh 默认启用翻译缓存：以「翻译引擎 + 引擎参数（语言对、模型）+ 原文」三元组为唯一键，命中则直接复用结果；需要强制重译时加--ignore-cache。缓存底层为 SQLite（~/.cache/pdf2zh/cache.v1.db，WAL 模式），实现见 pdf2zh/cache.py，翻译入口的缓存读写封装在BaseTranslator.translate()（pdf2zh/translator.py）。

九、自定义提示词（LLM 服务）

--prompt可传入提示词文件，覆盖内置默认提示词（内置默认内容与自定义格式保持一致，见 pdf2zh/translator.py）：

pdf2zh example.pdf --prompt prompt.txt

提示词模板支持三个变量：${lang_in}（源语言）、${lang_out}（目标语言）、${text}（待翻译文本）。示例：

You are a professional, authentic machine translation engine. Only Output the translated text, do not include any other text. Translate the following markdown source text to ${lang_out}. Keep the formula notation {v*} unchanged. Output translation directly without any additional text. Source Text: ${text} Translated Text:

注意：当前版本不支持 System Prompt（README 明确注明了这一点）。

十、GUI 鉴权与 MCP 集成

10.1 登录鉴权

--authorized可指定 Web UI 用户列表与自定义登录页：

pdf2zh -i --authorized users.txt auth.html

users.txt每行一个用户，格式为用户名,密码：

admin,123456 user1,password1 user2,abc123 guest,guest123 test,test123

auth.html为自定义登录页面 HTML（任意合法 HTML 即可）。

10.2 作为 MCP 服务器

pdf2zh 支持以 MCP（Model Context Protocol）方式供 AI 客户端调用，配置claude_desktop_config.json（需先通过uv pip install pdf2zh安装）：

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/Document"] }, "translate_pdf": { "command": "uv", "args": ["run", "pdf2zh", "--mcp"] } } }

其中filesystem服务器用于定位 PDF 文件（必需），translate_pdf即翻译服务。配置完成后，可直接在 Claude Desktop 中发出自然语言指令，例如「在 Document 文件夹中找到test.pdf并翻译成中文」。MCP 服务器实现位于 pdf2zh/mcp_server.py，STDIO 模式由--mcp触发，SSE 模式加--sse（基于 uvicorn 启动 Starlette 应用）。

十一、下游开发：Python API 与 HTTP API

README 第 4.2 节指向 docs/APIS.md 提供了两类二次开发接口：

• Python API（docs/APIS.md）：在自有 Python 程序中调用pdf2zh.high_level.translate()，直接获得 mono/dual 两份文件路径列表（核心签名见 pdf2zh/high_level.py）；
• HTTP API（docs/APIS.md）：与已部署该服务的服务器进行 HTTP 通信，可用于构建 Web 前端或远程翻译服务。

十二、字体处理与兼容性细节

• 多语言字体：pdf2zh 会根据目标语言自动下载远程字体——非 CJK 语言用GoNotoKurrent-Regular.ttf，中文简/繁、日文、韩文分别映射SourceHanSerifCN/TW/JP/KR-Regular.ttf（映射表见 pdf2zh/high_level.py），并注入到译文的每页字体资源中；
• 字体子集化：默认开启字体子集化以压缩输出体积，遇到兼容性问题可--skip-subset-fonts关闭（代价是输出文件变大）；
• 兼容模式：-cp/--compatible会先将输入转换为 PDF/A-2B 格式再翻译，提高部分阅读器下的兼容性，转换逻辑基于 pikepdf 实现（pdf2zh/high_level.py）。

十三、引用与致谢

如果你在论文或项目中使用了 PDFMathTranslate，请按 README 第 5.1 节给出的 BibTeX 引用（@inproceedings{ouyang-etal-2025-pdfmathtranslate, ...}，完整条目见 README.md）。项目致谢了 PyMuPDF（文档合并）、Pdfminer.six（文档解析）、MinerU（文档抽取）、DocLayout-YOLO（版面解析）、MathTranslate（多线程翻译思路）、Go Noto Universal（多语言字体）等上游项目（README.md 第 5.2 节）。

十四、技术路线小结

本文给出的完整上手路径可以概括为四步：① 按需选择安装方式（uv/pip/GUI/Windows/Zotero/Docker）→ ② 一行命令pdf2zh document.pdf产出 mono/dual 双语 PDF → ③ 用-s、-li/-lo、-p、-t等参数切换到目标服务与翻译范围 → ④ 进阶时通过--config配置文件、--prompt自定义提示词、--mode precise实验内核与 OCR 功能进一步调优。每一步所对应的源码文件（CLI 入口 pdf2zh/pdf2zh.py、核心流程 pdf2zh/high_level.py、翻译服务 pdf2zh/translator.py、缓存 pdf2zh/cache.py、内核注册表 pdf2zh/kernel/registry.py、高级文档 docs/ADVANCED.md）均已在正文中给出，可供进一步研读与二次开发。

【免费下载链接】PDFMathTranslate[EMNLP 2025 Demo] PDF scientific paper translation with preserved formats - 基于 AI 完整保留排版的 PDF 文档全文双语翻译，支持 Google/DeepL/Ollama/OpenAI 等服务，提供 CLI/GUI/MCP/Docker/Zotero项目地址: https://gitcode.com/GitHub_Trending/pd/PDFMathTranslate