PDF翻译排版保留指南：PDFMathTranslate 从安装到进阶的完整教程

发布时间：2026/10/27 1:50:06
PDF翻译排版保留指南：PDFMathTranslate 从安装到进阶的完整教程

PDF翻译排版保留指南：PDFMathTranslate 从安装到进阶的完整教程

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

PDFMathTranslate 是一款开源 PDF 翻译工具，基于文档布局分析与 AI 翻译服务，在翻译全文的同时保留公式、图表和目录结构，生成中英双语对照文档。适合需要阅读英文论文的研究者、学生和学术爱好者。

快速上手：5 分钟跑通第一份双语翻译

先确认你的电脑装有 Python 3.11 或 3.12 版本，然后用 pip 安装uv工具，再执行安装命令：

pip install uv uv tool install --python 3.12 pdf2zh

安装完成后，在项目目录下执行一条命令即可开始翻译，输出文件会生成在当前目录：

pdf2zh document.pdf

几分钟后，你会得到两份文件：document-mono.pdf（纯译文）和document-dual.pdf（中英双语对照），默认使用 Google 翻译服务，无需额外配置。

能力拆解：它帮你解决了哪些排版难题

公式与图表的原位保留

传统工具把 PDF 当纯文本处理，公式会变成乱码、图表会错位。PDFMathTranslate 使用文档布局模型（DocLayout-YOLO）先识别页面中的文字、公式、表格区域，只对文字区域做翻译，再把译文回填到原有版面中。

什么时候你会用到它：翻译包含 LaTeX 公式的论文、教材、技术报告时，输出结果可以直接用于精读，不需要再手动对公式。

翻译服务可自由切换

工具本身不绑定单一翻译引擎。除了默认的 Google，还内置了 DeepL、OpenAI、Ollama、DeepSeek、Gemini 等二十多种服务，通过-s参数切换。Ollama 可以连接本地模型，翻译数据不出内网。

什么时候你会用到它：公司网络访问不了 Google 时换 DeepL；处理敏感文档时用 Ollama 本地模型；追求长难句翻译质量时用 OpenAI 系列模型。

GUI 界面与 Docker 部署

不想碰命令行，可以启动图形界面，在浏览器里拖拽上传 PDF、选择服务、点击 Translate 按钮完成翻译：

pdf2zh -i

启动后在浏览器访问http://localhost:7860即可使用。

如果要在服务器或团队内网共享，可以用 Docker 一行拉取镜像部署：

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

什么时候你会用到它：给课题组搭一个共用的翻译服务，大家打开网页就能翻译。

进阶用法：常用参数速查表

选项作用最简示例
-s指定翻译服务pdf2zh paper.pdf -s deepl
-lo设置目标语言（如ja、zh）pdf2zh paper.pdf -lo ja
-p只翻译指定页面pdf2zh paper.pdf -p 1-5,8
--ultrafast极速模式，跳过布局模型加速纯文本 PDFpdf2zh paper.pdf --ultrafast
--dir批量翻译整个目录pdf2zh --dir /path/to/docs/
--mode翻译内核：fast（默认）或precise（实验性）pdf2zh paper.pdf --mode precise
--prompt自定义 LLM 翻译提示词pdf2zh --prompt prompt.txt
-o指定输出目录pdf2zh paper.pdf -o output/

完整参数（包括字体例外规则-f、-c、自定义配置文件--config、MCP 服务）见进阶用法文档。

避坑指南：三个高频报错排查

报错现象：首次运行时模型下载失败，卡在wybxc/DocLayout-YOLO-DocStructBench-onnx下载阶段。原因：网络无法直接访问模型托管站点。修复：设置镜像环境变量后重试（Linux/Mac 用export，Windows 命令提示符用set，PowerShell 用$env:）：

export HF_ENDPOINT=https://hf-mirror.com pdf2zh document.pdf

报错现象：使用 OpenAI 兼容 API 或自定义代理时翻译服务返回 404。原因：BASE_URL结尾缺少/v1路径段。修复：确认环境变量以/v1结尾，例如OPENAI_BASE_URL=https://api.openai.com/v1，配置方法见代理配置文档。

报错现象：输出 PDF 在部分阅读器中字体显示异常。原因：默认的字体子集化（Font Subsetting）与个别阅读器不兼容。修复：加参数跳过字体子集化，文件会略大但兼容性更好：

pdf2zh document.pdf --skip-subset-fonts

资源导航

  • README 中文说明：功能总览与安装方式
  • 进阶用法：全部参数、翻译服务与环境变量对照表
  • API 文档：Python API 与 HTTP API，方便接入自己的程序
  • GUI 使用指南：图形界面各选项详解
  • 代理配置：网络环境配置方案
  • 核心翻译逻辑源码：pdf2zh/，布局分析在pdf2zh/doclayout.py，翻译服务在pdf2zh/translator.py

写在最后

PDFMathTranslate 把"翻译"和"排版"拆成两个独立步骤来处理，让你在保留原始版式的前提下拿到一份可读、可检索的双语文档。现在就可以安装pdf2zh，用一份你手头正在读（或啃不动）的论文试试效果。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考