PDFMathTranslate 完整使用指南保留排版的中英对照 PDF 论文翻译工具CLI / GUI / Docker / API 全解析【免费下载链接】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 项目的韩文官方文档docs/README_ko-KR.md为骨架系统讲解这一「保留格式的科学 PDF 双语翻译工具」的四种使用方式命令行、便携版、GUI、Docker、全部高级 CLI 选项、翻译服务接入与缓存/配置机制。读完本文你将掌握如何把一篇 PDF 论文翻译为单语版-mono.pdf与双语对照版-dual.pdf并能通过环境变量接入 Google、DeepL、Ollama、OpenAI 等十余种翻译服务以及通过 Python 或 HTTP API 将翻译能力集成进自己的流程。一、项目定位与核心能力PDFMathTranslate包名pdf2zh是一款面向科学论文的 PDF 翻译工具核心诉求是在翻译的同时完整保留排版包括 保留公式、图表、目录与注释预览见 docs/images/preview.gif 支持多种源语言/目标语言以及多种翻译服务 提供命令行工具、交互式 GUI基于 Gradio与 Docker 三种入口当前仓库源码版本为1.9.12见 pdf2zh/init.py。从韩文文档的更新记录看项目在 2024 年 11–12 月间快速迭代先后加入了免费公共服务与防火墙、在线文件URL翻译、ONNX 依赖优化、Tencent 翻译、GUI 双语文档下载与多语言支持以及基于 Xinference 的本地 LLM 支持等能力。翻译完成后工具会在当前工作目录或-o指定的输出目录生成两个文件输出文件说明example-mono.pdf仅包含译文单语的 PDFexample-dual.pdf原文与译文对照双语的 PDF二、安装前提与模型下载说明项目提供了四种使用方式命令行工具、便携版Portable、GUI、Docker读者可按需选择。其中 CLI、GUI 与 API 方式均要求本机已安装 Python版本需满足 3.11 版本 3.12。运行pdf2zh时还需要一个额外的文档版面分析模型wybxc/DocLayout-YOLO-DocStructBench-onnx该模型也可从 ModelScope 获取。如果在启动时该模型下载失败可以通过设置 HuggingFace 镜像源环境变量解决Windows CMDset HF_ENDPOINThttps://hf-mirror.comPowerShell 用户则使用$env:HF_ENDPOINT https://hf-mirror.com从源码看该模型通过 pdf2zh/doclayout.py 中的OnnxModel加载用于版面解析layout parsing并且命令行--onnx参数允许替换为自定义的 DocLayout-YOLO ONNX 模型--backend参数可切换 ONNX Runtime 的执行后端auto/cpu/cuda/dml见 pdf2zh/pdf2zh.py。三、四种使用方式详解方法一命令行工具CLI确认已安装 Python3.11 版本 3.12安装软件包pip install pdf2zh执行翻译产物生成在当前工作目录pdf2zh document.pdf默认使用 Google 翻译服务将英文翻译为中文-li en -lo zh为源码中定义的默认值见 pdf2zh/pdf2zh.py。方法二便携版Portable无需预先安装 Python 环境。下载 script/setup.bat 并双击运行即可适合在未配置 Python 的 Windows 机器上快速体验。方法三GUI交互式界面确认已安装 Python3.11 版本 3.12安装软件包pip install pdf2zh启动 GUIpdf2zh -i若浏览器未自动打开手动访问http://localhost:7860/GUI 模式下还支持两个环境变量控制语言方向详见 docs/README_GUI.mdPDF2ZH_LANG_FROM源语言默认EnglishPDF2ZH_LANG_TO目标语言默认Simplified Chinese界面支持语言包括 English、Simplified Chinese、Traditional Chinese、French、German、Japanese、Korean、Russian、Spanish、Italian 等。GUI 模式下可通过--share获取 Gradio 公网分享链接通过--authorized users.txt [auth.html]增加 Web 认证与自定义登录页通过--serverport 7860指定 WebUI 端口对应源码 pdf2zh/pdf2zh.py。方法四Docker拉取镜像并运行docker pull byaidu/pdf2zh docker run -d -p 7860:7860 byaidu/pdf2zh浏览器打开http://localhost:7860/即可使用。此外仓库根目录还提供了 Dockerfile 与 docker-compose.yml可自行构建与编排部署。四、高级 CLI 选项全表韩文文档列出了全部高级选项以下表格完整复刻并补充默认值信息默认值来自 pdf2zh/pdf2zh.py 的参数解析选项功能示例files本地文件pdf2zh ~/local.pdflinks在线文件URLpdf2zh http://arxiv.org/paper.pdf-i进入 GUIpdf2zh -i-p部分文档翻译pdf2zh example.pdf -p 1-li源语言pdf2zh example.pdf -li en-lo目标语言pdf2zh example.pdf -lo zh-s翻译服务pdf2zh example.pdf -s deepl-t多线程数默认 4pdf2zh example.pdf -t 1-o输出目录pdf2zh example.pdf -o output-f,-c公式字体/字符例外正则pdf2zh example.pdf -f (MS.*)--share获取 Gradio 公网分享链接pdf2zh -i --share--authorized增加 Web 认证与自定义认证页pdf2zh -i --authorized users.txt [auth.html]--prompt使用自定义大模型提示词pdf2zh --prompt [prompt.txt]--onnx使用自定义 DocLayout-YOLO ONNX 模型pdf2zh --onnx [onnx/model/path]--serverport使用自定义 WebUI 端口pdf2zh --serverport 7860--dir批量翻译目录pdf2zh --dir /path/to/translate/--config配置文件pdf2zh --config /path/to/config/config.json命令行参数示意图片来自韩文文档其中--dir批量翻译在源码中会递归扫描目录下所有.pdf、.doc、.docx文件见 pdf2zh/pdf2zh.py说明pdf2zh不仅支持 PDF也支持 Word 文档doc/docx 会先转换为 PDF 再翻译见 pdf2zh/converter_docx.py。4.1 全文翻译与部分翻译全文翻译pdf2zh example.pdf部分翻译指定页范围支持逗号与连字符组合pdf2zh example.pdf -p 1-3,5-p的解析逻辑在源码中会先把1-3这类范围展开为页列表基于 0 的索引再交给内核处理见 pdf2zh/pdf2zh.py。4.2 指定源语言与目标语言语言代码可参考 Google Languages Codes 与 DeepL Languages Codes按-li/-lo传入pdf2zh example.pdf -li en -lo ko4.3 切换翻译服务韩文文档给出了一张完整的服务与环境变量对照表。使用对应服务前请先设置好相关环境变量翻译器服务名环境变量默认值备注Google默认google无N/A无Bingbing无N/A无DeepLdeeplDEEPL_AUTH_KEY[Your Key]参考 DeepL API Key 文档DeepLXdeeplxDEEPLX_ENDPOINThttps://api.deepl.com/translate参考 DeepLX 项目OllamaollamaOLLAMA_HOST,OLLAMA_MODELhttp://127.0.0.1:11434,gemma2参考 Ollama 项目OpenAIopenaiOPENAI_BASE_URL,OPENAI_API_KEY,OPENAI_MODEL,OPENAI_STOP_TOKENS,OPENAI_MAX_TOKENShttps://api.openai.com/v1,[Your Key],gpt-4o-mini, ,-1参考 OpenAI 官方文档AzureOpenAIazure-openaiAZURE_OPENAI_BASE_URL,AZURE_OPENAI_API_KEY,AZURE_OPENAI_MODEL[Your Endpoint],[Your Key],gpt-4o-mini参考 Azure OpenAI 文档ZhipuzhipuZHIPU_API_KEY,ZHIPU_MODEL[Your Key],glm-4-flash参考智谱开放平台ModelScopemodelscopeMODELSCOPE_API_KEY,MODELSCOPE_MODEL[Your Key],Qwen/Qwen2.5-Coder-32B-Instruct参考 ModelScope 文档SiliconsiliconSILICON_API_KEY,SILICON_MODEL[Your Key],Qwen/Qwen2.5-7B-Instruct参考 SiliconCloud 文档GeminigeminiGEMINI_API_KEY,GEMINI_MODEL[Your Key],gemini-1.5-flash参考 Gemini API 文档AzureazureAZURE_ENDPOINT,AZURE_API_KEYhttps://api.translator.azure.cn,[Your Key]参考 Azure 文本翻译文档TencenttencentTENCENTCLOUD_SECRET_ID,TENCENTCLOUD_SECRET_KEY[Your ID],[Your Key]参考腾讯机器翻译文档DifydifyDIFY_API_URL,DIFY_API_KEY[Your DIFY URL],[Your Key]参考 Dify 项目需在 Dify 工作流输入中定义lang_out、lang_in、text三个变量AnythingLLManythingllmAnythingLLM_URL,AnythingLLM_APIKEY[Your AnythingLLM URL],[Your Key]参考 anything-llm 项目Argos Translateargos无N/A参考 argos-translate 项目GrokgrokGORK_API_KEY,GORK_MODEL[Your GORK_API_KEY],grok-2-1212参考 Grok 文档DeepSeekdeepseekDEEPSEEK_API_KEY,DEEPSEEK_MODEL[Your DEEPSEEK_API_KEY],deepseek-chat参考 DeepSeek 文档MiniMaxminimaxMINIMAX_API_KEY,MINIMAX_MODEL[Your MINIMAX_API_KEY],MiniMax-M2.7参考 MiniMax 平台OpenAI-LikedopenailikedOPENAILIKED_BASE_URL,OPENAILIKED_API_KEY,OPENAILIKED_MODELurl,[Your Key],model name无OpenAI-LikedopenailikedOPENAILIKED_BASE_URL,OPENAILIKED_API_KEY,OPENAILIKED_MODEL,OPENAILIKED_STOP_TOKENS,OPENAILIKED_MAX_TOKENSurl,[Your Key],model name, ,-1无对于上表中未列出但兼容 OpenAI API 的大语言模型可以按表中 OpenAI 的方式设置环境变量接入。指定翻译服务有两种方式。其一通过-s service或-s service:model直接指定pdf2zh example.pdf -s openai:gpt-4o-mini其二通过环境变量指定模型set OPENAI_MODELgpt-4o-mini pdf2zh example.pdf -s openaiPowerShell 用户$env:OPENAI_MODEL gpt-4o-mini pdf2zh example.pdf -s openai从源码看每个服务对应 pdf2zh/translator.py 中的一个 Translator 子类如GoogleTranslator、BingTranslator、DeepLTranslator、OllamaTranslator、OpenAITranslator等统一继承自BaseTranslator通过name属性注册并在启动时由-s指定的服务名匹配加载。默认的 Google 服务走https://translate.google.com/m端点单次请求文本长度上限为 5000 字符见 pdf2zh/translator.pyBing 单次上限为 1000 字符。4.4 公式与字符例外保留公式排版使用正则表达式指定需要保留的公式字体与字符避免它们被翻译或改写pdf2zh example.pdf -f (CM[^RT].*|MS.*|.*Ital) -c (\(|\||\)|\||\d|[\u0080-\ufaff])其中-f即--vfont匹配需要保留的公式字体名-c即--vchar匹配需要保留的公式字符。默认情况下pdf2zh会保留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)4.5 指定线程数使用-t指定翻译并发线程数源码默认值为 4pdf2zh example.pdf -t 14.6 自定义 LLM 提示词使用--prompt指定传给大语言模型的提示词文件pdf2zh example.pdf -pr prompt.txtprompt.txt示例JSON 消息数组格式[ { role: system, content: You are a professional,authentic machine translation engine., }, { role: user, content: Translate the following markdown source text to ${lang_out}. Keep the formula notation {{v*}} unchanged. Output translation directly without any additional text.\nSource Text: ${text}\nTranslated Text:, }, ]自定义提示词文件中可以使用以下三个变量由源码中Template.safe_substitute机制替换见 pdf2zh/translator.py变量内容lang_in源语言lang_out目标语言text待翻译文本未指定自定义提示词时默认提示词要求模型「仅输出译文、不做任何额外解释」并要求保留公式记号{v*}不变。4.7 翻译缓存与配置文件源码级补充韩文文档在选项表中提到了--config这里结合源码补充其底层机制翻译缓存pdf2zh会对已翻译文本建立缓存加速重复翻译并避免相同内容重复调用 API。缓存实现位于 pdf2zh/cache.py使用 SQLite 存储数据库文件位于~/.cache/pdf2zh/cache.v1.db以「翻译引擎 引擎参数 原文」三元组作为唯一键。可以通过--ignore-cache忽略缓存、强制重新翻译。配置文件默认配置文件位于~/.config/PDFMathTranslate/config.json见 pdf2zh/config.py。程序启动时先读取 config.json再读取环境变量当环境变量可用时优先使用环境变量并回写更新配置文件。--config /path/to/config.json可指定自定义配置文件路径。配置文件中通过translators数组为各服务预置环境变量如DEEPLX_ENDPOINT、OLLAMA_HOST、GROK_API_KEY等并支持USE_MODELSCOPE、PDF2ZH_LANG_FROM、PDF2ZH_LANG_TO、NOTO_FONT_PATH等全局键。五、API 集成Python 与 HTTP韩文文档提供了两套编程接口适合将 PDF 翻译能力集成到自己的脚本或服务中。5.1 Python APIfrom pdf2zh import translate, translate_stream params {lang_in: en, lang_out: ko, service: google, thread: 4} file_mono, file_dual translate(files[example.pdf], **params)[0] with open(example.pdf, rb) as f: stream_mono, stream_dual translate_stream(streamf.read(), **params)其中translate接收文件路径列表translate_stream接收 PDF 二进制流两者均返回(单语文件, 双语文件)二元组见 pdf2zh/high_level.py。这两个函数在 pdf2zh/init.py 的__all__中导出translate也支持传入 http/https 开头的在线文件链接自动下载后翻译对应韩文文档更新记录中的「CLI 支持在线文件」。5.2 HTTP API后端服务模式安装带后端依赖的版本并启动 Flask 服务与 Celery 任务队列pip install pdf2zh[backend] pdf2zh --flask pdf2zh --celery worker然后通过 REST 接口提交翻译任务、查询进度并下载结果curl http://localhost:11008/v1/translate -F fileexample.pdf -F data{\lang_in\:\en\,\lang_out\:\ko\,\service\:\google\,\thread\:4} {id:d9894125-2f4e-45ea-9d93-1a9068d2045a} curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a {info:{n:13,total:506},state:PROGRESS} curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a {state:SUCCESS} curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a/mono --output example-mono.pdf curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a/dual --output example-dual.pdf curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a -X DELETE接口流程为提交文件获得任务id→ 轮询任务状态PROGRESS/SUCCESS→ 下载mono/dual结果 →DELETE清理任务。Flask 服务默认监听11008端口见 pdf2zh/pdf2zh.py。六、工作流程与源码结构速览一次典型翻译的调用链大致为CLI 参数解析pdf2zh/pdf2zh.py→ 内核路由fast/precise 模式见 pdf2zh/kernel/→ 版面分析DocLayout-YOLO ONNX 模型pdf2zh/doclayout.py→ PDF 解析与文本提取pdf2zh/pdfinterp.py、pdf2zh/converter.py→ 翻译服务调用pdf2zh/translator.py→ 字体子集化与 PDF 合并输出借助 PyMuPDF。项目对上游开源组件的依赖也值得了解对应韩文文档「감사의 말」致谢部分环节依赖组件文档合并PyMuPDF文档解析Pdfminer.six文档抽取MinerU文档预览Gradio PDF多线程翻译MathTranslate版面解析DocLayout-YOLO文档规范PDF Explained、PDF Cheat Sheets多语言字体Go Noto Universal七、总结PDFMathTranslate 的价值在于把「科学 PDF 排版」与「机器翻译」打通通过 DocLayout-YOLO 版面分析理解文档结构通过公式字体/字符正则例外保留公式通过-mono/-dual双产物满足单语阅读与双语对照两种需求同时提供 CLI、GUI、Docker、Python API、HTTP API 五条接入路径。本文所述操作与参数均可在当前仓库复现验证命令行参数定义在 pdf2zh/pdf2zh.py翻译服务实现与默认提示词在 pdf2zh/translator.py缓存与配置机制分别在 pdf2zh/cache.py 与 pdf2zh/config.py更深入的服务接入、认证、字体子集化、MCP 等进阶用法可继续阅读 docs/ADVANCED.md 与 docs/README_GUI.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
PDFMathTranslate 完整使用指南：保留排版的中英对照 PDF 论文翻译工具（CLI / GUI / Docker / API 全解析）
PDFMathTranslate 完整使用指南保留排版的中英对照 PDF 论文翻译工具CLI / GUI / Docker / API 全解析【免费下载链接】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 项目的韩文官方文档docs/README_ko-KR.md为骨架系统讲解这一「保留格式的科学 PDF 双语翻译工具」的四种使用方式命令行、便携版、GUI、Docker、全部高级 CLI 选项、翻译服务接入与缓存/配置机制。读完本文你将掌握如何把一篇 PDF 论文翻译为单语版-mono.pdf与双语对照版-dual.pdf并能通过环境变量接入 Google、DeepL、Ollama、OpenAI 等十余种翻译服务以及通过 Python 或 HTTP API 将翻译能力集成进自己的流程。一、项目定位与核心能力PDFMathTranslate包名pdf2zh是一款面向科学论文的 PDF 翻译工具核心诉求是在翻译的同时完整保留排版包括 保留公式、图表、目录与注释预览见 docs/images/preview.gif 支持多种源语言/目标语言以及多种翻译服务 提供命令行工具、交互式 GUI基于 Gradio与 Docker 三种入口当前仓库源码版本为1.9.12见 pdf2zh/init.py。从韩文文档的更新记录看项目在 2024 年 11–12 月间快速迭代先后加入了免费公共服务与防火墙、在线文件URL翻译、ONNX 依赖优化、Tencent 翻译、GUI 双语文档下载与多语言支持以及基于 Xinference 的本地 LLM 支持等能力。翻译完成后工具会在当前工作目录或-o指定的输出目录生成两个文件输出文件说明example-mono.pdf仅包含译文单语的 PDFexample-dual.pdf原文与译文对照双语的 PDF二、安装前提与模型下载说明项目提供了四种使用方式命令行工具、便携版Portable、GUI、Docker读者可按需选择。其中 CLI、GUI 与 API 方式均要求本机已安装 Python版本需满足 3.11 版本 3.12。运行pdf2zh时还需要一个额外的文档版面分析模型wybxc/DocLayout-YOLO-DocStructBench-onnx该模型也可从 ModelScope 获取。如果在启动时该模型下载失败可以通过设置 HuggingFace 镜像源环境变量解决Windows CMDset HF_ENDPOINThttps://hf-mirror.comPowerShell 用户则使用$env:HF_ENDPOINT https://hf-mirror.com从源码看该模型通过 pdf2zh/doclayout.py 中的OnnxModel加载用于版面解析layout parsing并且命令行--onnx参数允许替换为自定义的 DocLayout-YOLO ONNX 模型--backend参数可切换 ONNX Runtime 的执行后端auto/cpu/cuda/dml见 pdf2zh/pdf2zh.py。三、四种使用方式详解方法一命令行工具CLI确认已安装 Python3.11 版本 3.12安装软件包pip install pdf2zh执行翻译产物生成在当前工作目录pdf2zh document.pdf默认使用 Google 翻译服务将英文翻译为中文-li en -lo zh为源码中定义的默认值见 pdf2zh/pdf2zh.py。方法二便携版Portable无需预先安装 Python 环境。下载 script/setup.bat 并双击运行即可适合在未配置 Python 的 Windows 机器上快速体验。方法三GUI交互式界面确认已安装 Python3.11 版本 3.12安装软件包pip install pdf2zh启动 GUIpdf2zh -i若浏览器未自动打开手动访问http://localhost:7860/GUI 模式下还支持两个环境变量控制语言方向详见 docs/README_GUI.mdPDF2ZH_LANG_FROM源语言默认EnglishPDF2ZH_LANG_TO目标语言默认Simplified Chinese界面支持语言包括 English、Simplified Chinese、Traditional Chinese、French、German、Japanese、Korean、Russian、Spanish、Italian 等。GUI 模式下可通过--share获取 Gradio 公网分享链接通过--authorized users.txt [auth.html]增加 Web 认证与自定义登录页通过--serverport 7860指定 WebUI 端口对应源码 pdf2zh/pdf2zh.py。方法四Docker拉取镜像并运行docker pull byaidu/pdf2zh docker run -d -p 7860:7860 byaidu/pdf2zh浏览器打开http://localhost:7860/即可使用。此外仓库根目录还提供了 Dockerfile 与 docker-compose.yml可自行构建与编排部署。四、高级 CLI 选项全表韩文文档列出了全部高级选项以下表格完整复刻并补充默认值信息默认值来自 pdf2zh/pdf2zh.py 的参数解析选项功能示例files本地文件pdf2zh ~/local.pdflinks在线文件URLpdf2zh http://arxiv.org/paper.pdf-i进入 GUIpdf2zh -i-p部分文档翻译pdf2zh example.pdf -p 1-li源语言pdf2zh example.pdf -li en-lo目标语言pdf2zh example.pdf -lo zh-s翻译服务pdf2zh example.pdf -s deepl-t多线程数默认 4pdf2zh example.pdf -t 1-o输出目录pdf2zh example.pdf -o output-f,-c公式字体/字符例外正则pdf2zh example.pdf -f (MS.*)--share获取 Gradio 公网分享链接pdf2zh -i --share--authorized增加 Web 认证与自定义认证页pdf2zh -i --authorized users.txt [auth.html]--prompt使用自定义大模型提示词pdf2zh --prompt [prompt.txt]--onnx使用自定义 DocLayout-YOLO ONNX 模型pdf2zh --onnx [onnx/model/path]--serverport使用自定义 WebUI 端口pdf2zh --serverport 7860--dir批量翻译目录pdf2zh --dir /path/to/translate/--config配置文件pdf2zh --config /path/to/config/config.json命令行参数示意图片来自韩文文档其中--dir批量翻译在源码中会递归扫描目录下所有.pdf、.doc、.docx文件见 pdf2zh/pdf2zh.py说明pdf2zh不仅支持 PDF也支持 Word 文档doc/docx 会先转换为 PDF 再翻译见 pdf2zh/converter_docx.py。4.1 全文翻译与部分翻译全文翻译pdf2zh example.pdf部分翻译指定页范围支持逗号与连字符组合pdf2zh example.pdf -p 1-3,5-p的解析逻辑在源码中会先把1-3这类范围展开为页列表基于 0 的索引再交给内核处理见 pdf2zh/pdf2zh.py。4.2 指定源语言与目标语言语言代码可参考 Google Languages Codes 与 DeepL Languages Codes按-li/-lo传入pdf2zh example.pdf -li en -lo ko4.3 切换翻译服务韩文文档给出了一张完整的服务与环境变量对照表。使用对应服务前请先设置好相关环境变量翻译器服务名环境变量默认值备注Google默认google无N/A无Bingbing无N/A无DeepLdeeplDEEPL_AUTH_KEY[Your Key]参考 DeepL API Key 文档DeepLXdeeplxDEEPLX_ENDPOINThttps://api.deepl.com/translate参考 DeepLX 项目OllamaollamaOLLAMA_HOST,OLLAMA_MODELhttp://127.0.0.1:11434,gemma2参考 Ollama 项目OpenAIopenaiOPENAI_BASE_URL,OPENAI_API_KEY,OPENAI_MODEL,OPENAI_STOP_TOKENS,OPENAI_MAX_TOKENShttps://api.openai.com/v1,[Your Key],gpt-4o-mini, ,-1参考 OpenAI 官方文档AzureOpenAIazure-openaiAZURE_OPENAI_BASE_URL,AZURE_OPENAI_API_KEY,AZURE_OPENAI_MODEL[Your Endpoint],[Your Key],gpt-4o-mini参考 Azure OpenAI 文档ZhipuzhipuZHIPU_API_KEY,ZHIPU_MODEL[Your Key],glm-4-flash参考智谱开放平台ModelScopemodelscopeMODELSCOPE_API_KEY,MODELSCOPE_MODEL[Your Key],Qwen/Qwen2.5-Coder-32B-Instruct参考 ModelScope 文档SiliconsiliconSILICON_API_KEY,SILICON_MODEL[Your Key],Qwen/Qwen2.5-7B-Instruct参考 SiliconCloud 文档GeminigeminiGEMINI_API_KEY,GEMINI_MODEL[Your Key],gemini-1.5-flash参考 Gemini API 文档AzureazureAZURE_ENDPOINT,AZURE_API_KEYhttps://api.translator.azure.cn,[Your Key]参考 Azure 文本翻译文档TencenttencentTENCENTCLOUD_SECRET_ID,TENCENTCLOUD_SECRET_KEY[Your ID],[Your Key]参考腾讯机器翻译文档DifydifyDIFY_API_URL,DIFY_API_KEY[Your DIFY URL],[Your Key]参考 Dify 项目需在 Dify 工作流输入中定义lang_out、lang_in、text三个变量AnythingLLManythingllmAnythingLLM_URL,AnythingLLM_APIKEY[Your AnythingLLM URL],[Your Key]参考 anything-llm 项目Argos Translateargos无N/A参考 argos-translate 项目GrokgrokGORK_API_KEY,GORK_MODEL[Your GORK_API_KEY],grok-2-1212参考 Grok 文档DeepSeekdeepseekDEEPSEEK_API_KEY,DEEPSEEK_MODEL[Your DEEPSEEK_API_KEY],deepseek-chat参考 DeepSeek 文档MiniMaxminimaxMINIMAX_API_KEY,MINIMAX_MODEL[Your MINIMAX_API_KEY],MiniMax-M2.7参考 MiniMax 平台OpenAI-LikedopenailikedOPENAILIKED_BASE_URL,OPENAILIKED_API_KEY,OPENAILIKED_MODELurl,[Your Key],model name无OpenAI-LikedopenailikedOPENAILIKED_BASE_URL,OPENAILIKED_API_KEY,OPENAILIKED_MODEL,OPENAILIKED_STOP_TOKENS,OPENAILIKED_MAX_TOKENSurl,[Your Key],model name, ,-1无对于上表中未列出但兼容 OpenAI API 的大语言模型可以按表中 OpenAI 的方式设置环境变量接入。指定翻译服务有两种方式。其一通过-s service或-s service:model直接指定pdf2zh example.pdf -s openai:gpt-4o-mini其二通过环境变量指定模型set OPENAI_MODELgpt-4o-mini pdf2zh example.pdf -s openaiPowerShell 用户$env:OPENAI_MODEL gpt-4o-mini pdf2zh example.pdf -s openai从源码看每个服务对应 pdf2zh/translator.py 中的一个 Translator 子类如GoogleTranslator、BingTranslator、DeepLTranslator、OllamaTranslator、OpenAITranslator等统一继承自BaseTranslator通过name属性注册并在启动时由-s指定的服务名匹配加载。默认的 Google 服务走https://translate.google.com/m端点单次请求文本长度上限为 5000 字符见 pdf2zh/translator.pyBing 单次上限为 1000 字符。4.4 公式与字符例外保留公式排版使用正则表达式指定需要保留的公式字体与字符避免它们被翻译或改写pdf2zh example.pdf -f (CM[^RT].*|MS.*|.*Ital) -c (\(|\||\)|\||\d|[\u0080-\ufaff])其中-f即--vfont匹配需要保留的公式字体名-c即--vchar匹配需要保留的公式字符。默认情况下pdf2zh会保留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)4.5 指定线程数使用-t指定翻译并发线程数源码默认值为 4pdf2zh example.pdf -t 14.6 自定义 LLM 提示词使用--prompt指定传给大语言模型的提示词文件pdf2zh example.pdf -pr prompt.txtprompt.txt示例JSON 消息数组格式[ { role: system, content: You are a professional,authentic machine translation engine., }, { role: user, content: Translate the following markdown source text to ${lang_out}. Keep the formula notation {{v*}} unchanged. Output translation directly without any additional text.\nSource Text: ${text}\nTranslated Text:, }, ]自定义提示词文件中可以使用以下三个变量由源码中Template.safe_substitute机制替换见 pdf2zh/translator.py变量内容lang_in源语言lang_out目标语言text待翻译文本未指定自定义提示词时默认提示词要求模型「仅输出译文、不做任何额外解释」并要求保留公式记号{v*}不变。4.7 翻译缓存与配置文件源码级补充韩文文档在选项表中提到了--config这里结合源码补充其底层机制翻译缓存pdf2zh会对已翻译文本建立缓存加速重复翻译并避免相同内容重复调用 API。缓存实现位于 pdf2zh/cache.py使用 SQLite 存储数据库文件位于~/.cache/pdf2zh/cache.v1.db以「翻译引擎 引擎参数 原文」三元组作为唯一键。可以通过--ignore-cache忽略缓存、强制重新翻译。配置文件默认配置文件位于~/.config/PDFMathTranslate/config.json见 pdf2zh/config.py。程序启动时先读取 config.json再读取环境变量当环境变量可用时优先使用环境变量并回写更新配置文件。--config /path/to/config.json可指定自定义配置文件路径。配置文件中通过translators数组为各服务预置环境变量如DEEPLX_ENDPOINT、OLLAMA_HOST、GROK_API_KEY等并支持USE_MODELSCOPE、PDF2ZH_LANG_FROM、PDF2ZH_LANG_TO、NOTO_FONT_PATH等全局键。五、API 集成Python 与 HTTP韩文文档提供了两套编程接口适合将 PDF 翻译能力集成到自己的脚本或服务中。5.1 Python APIfrom pdf2zh import translate, translate_stream params {lang_in: en, lang_out: ko, service: google, thread: 4} file_mono, file_dual translate(files[example.pdf], **params)[0] with open(example.pdf, rb) as f: stream_mono, stream_dual translate_stream(streamf.read(), **params)其中translate接收文件路径列表translate_stream接收 PDF 二进制流两者均返回(单语文件, 双语文件)二元组见 pdf2zh/high_level.py。这两个函数在 pdf2zh/init.py 的__all__中导出translate也支持传入 http/https 开头的在线文件链接自动下载后翻译对应韩文文档更新记录中的「CLI 支持在线文件」。5.2 HTTP API后端服务模式安装带后端依赖的版本并启动 Flask 服务与 Celery 任务队列pip install pdf2zh[backend] pdf2zh --flask pdf2zh --celery worker然后通过 REST 接口提交翻译任务、查询进度并下载结果curl http://localhost:11008/v1/translate -F fileexample.pdf -F data{\lang_in\:\en\,\lang_out\:\ko\,\service\:\google\,\thread\:4} {id:d9894125-2f4e-45ea-9d93-1a9068d2045a} curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a {info:{n:13,total:506},state:PROGRESS} curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a {state:SUCCESS} curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a/mono --output example-mono.pdf curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a/dual --output example-dual.pdf curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a -X DELETE接口流程为提交文件获得任务id→ 轮询任务状态PROGRESS/SUCCESS→ 下载mono/dual结果 →DELETE清理任务。Flask 服务默认监听11008端口见 pdf2zh/pdf2zh.py。六、工作流程与源码结构速览一次典型翻译的调用链大致为CLI 参数解析pdf2zh/pdf2zh.py→ 内核路由fast/precise 模式见 pdf2zh/kernel/→ 版面分析DocLayout-YOLO ONNX 模型pdf2zh/doclayout.py→ PDF 解析与文本提取pdf2zh/pdfinterp.py、pdf2zh/converter.py→ 翻译服务调用pdf2zh/translator.py→ 字体子集化与 PDF 合并输出借助 PyMuPDF。项目对上游开源组件的依赖也值得了解对应韩文文档「감사의 말」致谢部分环节依赖组件文档合并PyMuPDF文档解析Pdfminer.six文档抽取MinerU文档预览Gradio PDF多线程翻译MathTranslate版面解析DocLayout-YOLO文档规范PDF Explained、PDF Cheat Sheets多语言字体Go Noto Universal七、总结PDFMathTranslate 的价值在于把「科学 PDF 排版」与「机器翻译」打通通过 DocLayout-YOLO 版面分析理解文档结构通过公式字体/字符正则例外保留公式通过-mono/-dual双产物满足单语阅读与双语对照两种需求同时提供 CLI、GUI、Docker、Python API、HTTP API 五条接入路径。本文所述操作与参数均可在当前仓库复现验证命令行参数定义在 pdf2zh/pdf2zh.py翻译服务实现与默认提示词在 pdf2zh/translator.py缓存与配置机制分别在 pdf2zh/cache.py 与 pdf2zh/config.py更深入的服务接入、认证、字体子集化、MCP 等进阶用法可继续阅读 docs/ADVANCED.md 与 docs/README_GUI.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
