企业官网建设流程全解析

PDFMathTranslate 中文使用指南：保留公式与排版的科学 PDF 全文双语翻译

【免费下载链接】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 是一款面向科学文献的 PDF 翻译工具，其核心能力是在翻译过程中完整保留原始排版——公式、图表、目录与注释均不被破坏，最终同时输出单语译文（-mono）与双语对照（-dual）两份 PDF。本文以仓库内中文文档 docs/README_zh-CN.md 为主体，结合源码与高级配置文档，系统讲解从安装、命令行翻译、GUI 与 Docker 部署，到翻译服务选择、自定义配置与翻译内核机制的完整实战方案。读完本文，你将能够独立完成科学 PDF 的本地翻译部署，并根据自己的翻译服务与环境灵活调整参数。

项目概览：科学 PDF 翻译与双语对照

PDFMathTranslate 定位为"科学 PDF 文档翻译及双语对照工具"，面向论文、技术手册等排版复杂的科学文档，解决了传统 PDF 翻译工具"翻译后格式崩坏、公式乱码"的痛点：

• 保留公式、图表、目录和注释；
• 支持多种语言和诸多翻译服务（Google、DeepL、OpenAI、Ollama 等）；
• 提供命令行工具、图形交互界面（GUI）以及容器化部署（Docker）三种使用形态。

从仓库结构看，翻译能力由 pdf2zh/ 包承载，命令行入口定义在 pdf2zh/pdf2zh.py，布局解析依赖 DocLayout-YOLO 的 ONNX 模型（见 pdf2zh/doclayout.py），文档合并与解析则基于 PyMuPDF 与 pdfminer.six（声明于 pyproject.toml 的依赖列表）。

在线演示服务

在本地安装之前，可以通过以下在线服务快速体验翻译效果（注意演示资源有限，请勿滥用）：

• 公共免费服务（在线使用，无需安装）；
• 沉浸式翻译 BabelDOC（每月免费 1000 页）；
• HuggingFace 托管的 Docker 演示；
• ModelScope 托管的演示（无需安装）。

安装与使用：六种方式

中文文档针对不同使用场景提供了六种安装与使用方式。

1. uv 安装（推荐）

uv 提供独立的工具环境，不会污染系统 Python：

pip install uv uv tool install --python 3.12 pdf2zh

安装后执行翻译，译文文件生成在当前工作目录：

pdf2zh document.pdf

需要 Python 版本满足3.11 <= 版本 <= 3.12（该约束与 pyproject.toml 中的requires-python = ">=3.11,<3.13"一致）。

2. Windows exe

从发布页面下载pdf2zh-version-win64.zip，解压后双击pdf2zh.exe即可运行，适合无需 Python 环境的 Windows 用户。

3. 图形用户界面（GUI）

pip install pdf2zh pdf2zh -i

命令执行后会在浏览器中打开 Web 界面；若浏览器未自动启动，访问http://localhost:7860/。GUI 模式下支持拖拽 PDF 上传并点击 Translate 完成翻译，详细交互说明见 docs/README_GUI.md。GUI 中源语言与目标语言也可通过环境变量控制：

• PDF2ZH_LANG_FROM：源语言，默认English；
• PDF2ZH_LANG_TO：目标语言，默认Simplified Chinese。

支持的界面语言包括英文、简体中文、繁体中文、法文、德文、日文、韩文、俄文、西班牙文、意大利文。

从源码看，-i参数在 pdf2zh/pdf2zh.py 中触发setup_gui()，底层基于 Gradio 构建（依赖gradio<5.36），并支持--share生成公网链接、--authorized配置登录鉴权。

4. Docker 容器化部署

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

随后在浏览器打开http://localhost:7860/即可。若无法访问 Docker Hub，可使用 GitHub 容器注册中心的镜像：

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

仓库根目录的 docker-compose.yml 与 Dockerfile 也提供了可参考的自建镜像配置。云服务部署方面，文档提供了 Heroku、Render、Zeabur、Sealos、Koyeb 等平台的部署入口。

5. Zotero 插件

面向文献管理场景，可通过 Zotero 插件在文献库中直接触发翻译，详见 Zotero PDF2zh 插件项目。

6. 命令行

pip install pdf2zh pdf2zh document.pdf

执行后会在当前工作目录生成example-mono.pdf（单语译文）与example-dual.pdf（双语对照），默认使用 Google 翻译服务。

无法安装？模型下载的网络问题

程序运行前需要加载 AI 布局模型wybxc/DocLayout-YOLO-DocStructBench-onnx（用于识别文档中的公式、图表、目录等区域，加载逻辑见 pdf2zh/doclayout.py）。部分用户因网络原因无法从 Hugging Face 下载该模型，可通过设置镜像环境变量解决：

set HF_ENDPOINT=https://hf-mirror.com

PowerShell 用户：

$env:HF_ENDPOINT = https://hf-mirror.com

若仍无法解决，可查阅项目 Wiki 的常见问题解答（FAQ）。此外，Windows 用户若下载后无法打开程序，需先安装vc_redist.x64.exe（Microsoft Visual C++ 运行库）再重试——这与 pdf2zh/doclayout.py 中对 ONNX Runtime DLL 加载失败的显式提示一致。

高级选项：命令行参数全解

pdf2zh的命令行参数在 pdf2zh/pdf2zh.py 中通过 argparse 定义。中文 README 列出了全部高级选项，下表在保留原文基础上补充了各参数的默认值（取自源码）：

完整选项说明可查阅 docs/ADVANCED.md。下面对几个高频参数做源码级展开。

部分翻译（-p）

支持页码范围与列表，例如-p 1-3,5表示翻译第 1 至 3 页与第 5 页。源码 pdf2zh/pdf2zh.py 会将"1-3"展开为页索引列表，注意页码在内部被转换为从 0 开始的索引。

语言与翻译服务（-li/-lo/-s）

默认源语言为英文、目标语言为简体中文、服务为 Google（分别对应源码中的默认值en、zh、google）。Google 翻译器实现在 pdf2zh/translator.py，其单次请求上限为 5000 字符（text[:5000]）。语言代码遵循各服务的规范（如 Google 使用zh-CN，Bing 使用zh-Hans，lang_map映射同样定义在 pdf2zh/translator.py）。

公式异常处理（-f/-c）

科学 PDF 中公式往往使用特殊字体渲染，默认情况下程序会保留 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)"

-c用于按字符正则保留公式中的特殊符号：

pdf2zh example.pdf -f "(CM[^RT].*|MS.*|.*Ital)" -c "(\(|\||\)|\+|=|\d|[\u0080-\ufaff])"

在源码中，这两个正则分别对应--vfont（公式字体名匹配）与--vchar（公式字符匹配），作用于 PDF 解析阶段（见 pdf2zh/pdf2zh.py）。

翻译服务与环境变量

-s指定翻译服务，通用格式为-s service或-s service:model。例如指定 OpenAI 及具体模型：

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

也可通过环境变量指定模型：

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

PowerShell 用户：

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

主要服务及其所需环境变量（来自 docs/ADVANCED.md 的对照表）：

注意事项：

• 凡兼容 OpenAI API 但未列入上表的 LLM 服务，均可按 OpenAI 的方式设置环境变量接入；
• 使用 OpenAI 兼容 API 或自定义代理时，BASE_URL必须以/v1结尾（如https://api.openai.com/v1或http://your-proxy:8000/v1），否则会产生 404 错误；
• Qwen MT 暂不支持繁体中文，繁体会被翻译为简体中文。

配置文件：集中管理服务与密钥

通过--config可指定 JSON 配置文件，同时适用于 CLI 与 GUI：

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

示例配置文件（来自 docs/ADVANCED.md）：

{ "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" } } ] }

配置加载顺序：程序默认读取~/.config/PDFMathTranslate/config.json，随后读取环境变量；当环境变量可用时，环境变量优先生效并写回配置文件。该机制由 pdf2zh/config.py 中的ConfigManager实现，翻译器初始化时也会通过set_envs将环境变量与配置文件中的密钥合并（见 pdf2zh/translator.py）。

面向公开服务的配置

若要将 GUI 部署为公开服务，可通过ENABLED_SERVICES限制可选翻译服务、通过HIDDEN_GRADIO_DETAILS隐藏真实 API Key，防止用户从网页端窃取服务端密钥：

{ "USE_MODELSCOPE": "0", "translators": [ { "name": "grok", "envs": { "GROK_BASE_URL": "https://api.x.ai/v1", "GROK_API_KEY": "your-api-key", "GROK_MODEL": "grok-2-1212" } }, { "name": "openai", "envs": { "OPENAI_BASE_URL": "https://api.openai.com/v1", "OPENAI_API_KEY": "sk-xxxx", "OPENAI_MODEL": "gpt-4o-mini" } } ], "ENABLED_SERVICES": ["OpenAI", "Grok"], "HIDDEN_GRADIO_DETAILS": true, "PDF2ZH_LANG_FROM": "English", "PDF2ZH_LANG_TO": "Simplified Chinese", "NOTO_FONT_PATH": "/app/SourceHanSerifCN-Regular.ttf" }

自定义翻译提示词（--prompt）

针对 LLM 类服务，可通过--prompt传入提示词文件（注意：系统提示词暂不支持）：

pdf2zh example.pdf --prompt prompt.txt

提示词模板示例：

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:

模板支持三个变量：lang_in（输入语言）、lang_out（输出语言）、text（待翻译文本）。在源码 pdf2zh/translator.py 中，默认提示词同样使用这组变量，并要求"保持公式记号{v*}不变"，这正是翻译结果中公式不损坏的关键约定；--prompt文件会被读取为string.Template进行安全替换（见 pdf2zh/pdf2zh.py）。

GUI 授权登录（--authorized）

为 Web UI 配置账号密码与自定义登录页：

pdf2zh example.pdf --authorized users.txt auth.html

users.txt每行包含"用户名,密码"：

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

auth.html为自定义登录页面：

<!DOCTYPE html> <html> <head> <title>Simple HTML</title> </head> <body> <h1>Hello, World!</h1> <p>Welcome to my simple HTML page.</p> </body> </html>

字体子集化与翻译缓存

字体子集化（--skip-subset-fonts）

默认启用字体子集化以减小输出文件体积，但当遇到兼容性问题时，可用--skip-subset-fonts关闭：

pdf2zh example.pdf --skip-subset-fonts

源码注释（pdf2zh/pdf2zh.py）说明该选项会提升兼容性但增大输出文件体积。

翻译缓存（--ignore-cache）

程序会对已翻译文本建立本地缓存以提升重复翻译速度、避免相同的 API 调用。缓存实现在 pdf2zh/cache.py：基于 peewee + SQLite，数据库文件位于~/.cache/pdf2zh/cache.v1.db，以"翻译引擎 + 引擎参数 + 原文"为唯一键；翻译器基类BaseTranslator.translate会先查缓存、未命中才调用do_translate并回写（见 pdf2zh/translator.py）。如需强制重新翻译：

pdf2zh example.pdf --ignore-cache

翻译模式：fast 与 precise

--mode支持两种翻译内核：

• fast（默认，v1）：传统内核，即 pdf2zh 1.x 的完整解析-翻译-重组管线；
• precise（v2，实验性）：调用 PDFMathTranslate-next 内核，在隔离的虚拟环境中以子进程运行，需要先初始化PDFMathTranslate-next.git子模块。

内核切换由 pdf2zh/kernel/registry.py 的KernelRegistry完成（线程安全的热插拔注册表）；precise内核适配器实现在 pdf2zh/kernel/precise.py，它会校验子模块目录与 venv 是否存在，缺失时提示执行git submodule update --init pdf2zh/kernel/PDFMathTranslate-next.git。安装后可运行pdf2zh-setup-precise命令完成隔离环境的初始化（入口声明于 pyproject.toml 的[project.scripts]）。子模块与工作脚本位于 pdf2zh/kernel/PDFMathTranslate-next.git/ 与 pdf2zh/kernel/v2_worker.py。

多线程与批量翻译

• -t指定翻译线程数，默认 4（源码 pdf2zh/pdf2zh.py）。GUI 中同样提供该参数；
• --dir批量翻译：递归扫描目录下全部.pdf、.doc、.docx文件（见find_all_files_in_directory，pdf2zh/pdf2zh.py），Word 文档会先转换为 PDF 再翻译（见 pdf2zh/converter_docx.py）。

二次开发与 API 说明

当前 pdf2zh 的 Python/HTTP API 已暂时弃用：相关代码不会移除，但不再提供技术支持与 bug 修复。API 将在 pdf2zh 2.0 发布后重新提供；需要程序化访问的用户可改用 BabelDOC 的babeldoc.high_level.async_translate函数。仓库中的 docs/APIS.md 保留了对 Python API 与 HTTP API 的历史说明。

若需以 MCP（Model Context Protocol）方式将翻译能力接入 AI 助手，可用--mcp启动 STDIO 模式、--mcp --sse启动 SSE 模式（见 pdf2zh/mcp_server.py），并在客户端配置（如claude_desktop_config.json）中声明translate_pdf服务，示例配置见 docs/ADVANCED.md。

工作原理与实现要点

从源码结构可以梳理出 fast 模式的基本流程：

1. 布局解析：加载 DocLayout-YOLO ONNX 模型（pdf2zh/doclayout.py），通过OnnxModel.predict识别每页的标题、正文、公式、表格、图表等区域；--backend可选择 ONNX Runtime 的 CPU/CUDA/DirectML 执行提供方，GPU 加速需安装cuda（onnxruntime-gpu）或dml（onnxruntime-directml）可选依赖（见 pyproject.toml）；
2. 文本解析：基于 pdfminer.six 解析页面文本流与字体信息（pdf2zh/converter.py、pdf2zh/pdfinterp.py），按-f/-c正则识别公式字体与字符，将其替换为占位符以保护公式；
3. 并行翻译：多线程调用所选翻译服务（pdf2zh/translator.py），LLM 类服务通过自定义/默认提示词保持公式记号{v*}不变，结果写入 SQLite 缓存；
4. 重组输出：基于 PyMuPDF 将译文按原始坐标回填，生成-mono单语与-dual双语 PDF，-cp兼容模式则额外转换 PDF/A 格式提升兼容性。

小结

PDFMathTranslate 通过"布局识别 + 公式保护 + 多服务翻译 + 排版回填"的完整管线，实现了科学 PDF 的保排版全文翻译。本文覆盖了中文 README 中全部安装方式（uv、Windows exe、GUI、Docker、Zotero、CLI）、高级参数、翻译服务配置与网络问题解法，并结合 docs/ADVANCED.md 与 pdf2zh/ 源码补充了配置文件、缓存、字体子集化与 fast/precise 双内核的底层机制。你可以根据实际环境选择最合适的安装方式，并参照服务对照表配置自己的翻译服务后立即投入使用。

【免费下载链接】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