📖 pdf2zh-desktop · pdf2zh 桌面版 v2.3.9

开箱即用的 PDF 学术翻译神器 🚀

🎉 无需安装 Python · 无需配置环境 · 下载解压双击就能用！

🖥️ 支持 Windows + macOS 双平台

📘 强烈推荐先看 → 完整图文使用教程（macOS） 真实截图 · 每一步带红圈编号 · 配 API · 扫描件处理 · 常见问题 第一次使用？看完这一份就够了，省下你折腾两小时的时间。 💬 页面右下角有 AI 客服「小黑猫」在线答疑，问任何使用问题都能秒回

👀 效果一览

① 主界面 · 拖入 PDF · 选语言 · 一键开始

② 阅读页 · 中外对照 · AI 助手自动解读论文

快速开始 ·  功能特性 ·  翻译服务 ·  Zotero 联动 ·  更新日志 ·  English

_{💬 用户交流群（QQ）：1094195179（pdf2zh桌面版交流群）}

基于 PDFMathTranslate（EMNLP 2025）打造，在原项目基础上大幅增强桌面体验。

让学术 PDF 翻译变得像复制粘贴一样简单——公式、图表、排版全部完美保留 ✨

还在为翻译一篇论文折腾 Python 环境？还在对着黑窗口敲命令行？

桌面版帮你把这些烦恼统统打包带走 👋

• 📦 完全独立打包：Python 3.12 运行时 + 所有依赖全部内置，不污染你的系统
• 🖱️ 告别命令行：全图形化操作，拖拽文件就能翻译
• 🔧 智能错误诊断：出问题？程序自动弹窗告诉你怎么修
• 💼 真·便携版：拷贝到 U 盘带着走，换台电脑照样用

• 📄 1000+ 页的大部头轻松拿下
• 🧩 分块翻译：自动分块逐段翻译，超过 50 页自动开启
• 🧠 智能内存管理：逐页释放布局数组，即使上千页也不会内存溢出
• ⏯️ 断点续传——中途退出也不怕，下次自动接着翻
• 📜 扫描版 PDF 支持：自动覆盖底图原文
• 📊 独立表格翻译管线：专利、检测报告等表格密集文件
• 🔍 OCR 识别：内置 RapidOCR，纯图片扫描件自动识别并翻译

• 🧩 20+ 预设模型：DeepSeek V3/R1、GPT-4o、GLM-4、Gemini、Mistral、Ollama 等，下拉框直接选
• 🔧 OpenAI 兼容格式：17 个快捷预设一键配置任何兼容接口
• 🔗 一键测试连接：填完配置立即验证，通过后自动保存
• 📝 自定义提示词：内置风格模板 + 自定义保存/导入/导出
• 📚 术语库：5 个学科内置（计算机/医学/金融/法律/电气），支持 txt/csv/json 导入
• 🚫 译文更干净：所有 OpenAI 兼容服务（含硅基流动等自定义接口）都会自动挡掉模型夹带的「（注：…）」译者注/前言废话
• 🧠 DeepSeek V4 默认直出：自动关闭 V4 的思考模式，翻译更快更稳，不会把推理过程混进译文

• 🌐 自动识别源语言：打开 PDF 自动检测，自动设置翻译方向
• 📄 自动检测扫描件：纯图片 PDF 自动开启 OCR
• ✅ 翻译前预检：API Key / 加密 / 语言检查
• ⏱️ 预估剩余时间：窗口标题显示进度百分比
• 💾 崩溃恢复：异常退出后下次启动自动恢复
• 🔔 自动检查更新：启动后台静默检测新版本，只提示不自动下载替换文件

• 🔗 自动检测：从 Zotero 拖入 PDF 或条目，自动识别来源
• 📎 自动关联：翻译完成后译文自动添加为 Zotero 附件，不留冗余副本
• 🔌 一键安装插件：设置页一键安装 pdf2zh Connector，开箱即用
• 📐 格式多选：左右并排 / 双语对照 / 仅译文，任意组合放回 Zotero
• 🖱️ 右键直接翻译：Zotero 里对 PDF 右键 → 「用 pdf2zh-desktop 翻译」，格式跟随右键菜单选择
• 🌙 后台静默翻译：右键菜单勾选后不弹窗、不抢焦点，翻完自动关窗

• 👀 连续滚动预览：懒加载，大文档不卡
• 📐 自适应显示：适应宽度 / 适应高度 / 最佳适配
• 🗂️ 完整翻译历史，右键菜单打开目录/复制路径
• 🔍 预览首页：先翻一页看效果，满意再翻全文
• 📝 翻译完成后自动打开输出文件

• 🖱️ 拖放支持：文件、文件夹、Zotero 条目直接拖入窗口
• 📂 统一文件管理：浏览文件（多选）、浏览文件夹、一键清空
• 🔄 批量翻译失败项标红，支持一键重试

👉 前往最新版下载页（此链接始终指向最新版本，请在页面底部 Assets 里按平台下载）

• Windows：解压后看到多个文件，多种方式并存，按需选——
  • 🟢 推荐 / 最省心：直接双击 pdf2zh.exe，不需要任何安装步骤，解压即用，首次使用和日常使用都是这一个
  • 🟢 等价备选：pdf2zh.vbs（无控制台窗口）/ pdf2zh.bat（保留控制台便于看输出），效果和 pdf2zh.exe完全一样，个人喜好选一个
  • 🟡 想要桌面图标 / 开始菜单，建议做一次：双击 install.bat（顺带自动检查/安装 VC++ 运行库；跑完就没用了，不做也完全不影响用 pdf2zh.exe 正常使用，只是桌面上不会有图标）
  • 🟡 遇到问题：双击 debug_start.bat（看启动日志）或 diagnostic.bat（系统诊断）；改设置用 config_manager.bat
  • 🔴 卸载：双击 uninstall.bat
  • ⚠️ 首次双击提示「Windows 已保护你的电脑」（Microsoft Defender SmartScreen）：不是病毒，是软件没有购买微软商业签名证书，Windows 对从网上下载的新程序都会先拦一下。点窗口里的「更多信息」→「仍要运行」即可；若每次都弹，右键下载的 zip →「属性」→ 勾选「解除锁定」→ 确定，再重新解压
  • ⚠️ install.bat/uninstall.bat/debug_start.bat/diagnostic.bat/config_manager.bat 这几个是批处理脚本，v2.3.9 起已修复中文 Windows 上的编码乱码问题；pdf2zh.exe/pdf2zh.vbs 不受此类问题影响，追求最稳就选它们
• macOS：双击 pdf2zh.app；首次启动若提示「已损坏，无法打开」，终端跑一行：xattr -cr /Applications/pdf2zh.app，或 Finder 里右键 → 打开

拖入 PDF → 选翻译服务 → 点「开始翻译」→ 搞定！🎉

💡 小贴士：Google / Bing 翻译免费无需配置，打开就能用！

⚠️ 请从 Releases 页面 下载，不要点 Source code。

支持语言：中文（简繁）、英、日、韩、法、德、俄、西、意、葡、荷、波兰、土耳其、阿拉伯、泰、越南、印尼、马来、印地、孟加拉、乌克兰、捷克、瑞典、丹麦、芬兰、希腊、希伯来、匈牙利、罗马尼亚、老挝、高棉、缅甸、格鲁吉亚 等

• 📝 文件名-mono.pdf — 纯译文版
• 📖 文件名-dual.pdf — 双语对照版
• ↔️ 文件名-side_by_side.pdf — 左原文右译文（推荐）

从 Zotero 拖论文到 pdf2zh → 翻译 → 译文自动出现在 Zotero 附件栏

1. 设置页 → Zotero 联动 → 「一键安装 Zotero 插件」→ Zotero 重启
2. 从 Zotero 拖条目或 PDF 附件到 pdf2zh 窗口
3. 翻译 → 译文自动关联为 Zotero 附件，标题带格式标签（如 side by side - 论文名）

不需要每次操作，插件只装一次。没装 Zotero 的用户完全不受影响。

更快的方式：Zotero 里右键直接翻译

不用打开 pdf2zh，在 Zotero 里对着 PDF 右键 → 「📖 用 pdf2zh-desktop 翻译」即可，格式跟随右键菜单选择。右键菜单还能勾选「后台静默翻译」——不弹窗、不抢焦点，翻完自动关窗，适合批量挂后台处理。

• ✨ 一键更新，不用再去 GitHub 下载（Mac/Win）：软件启动后自动检查新版本，有新版本就在后台只下载改动的部分（Windows 通常几百 KB，macOS 约 40 MB，不用再下 300 MB 的完整包），下好后窗口顶部提示「新版本已准备好 · 重启更新」：
  • 点「重启更新」：软件关掉再打开，几秒后就是新版本；
  • 不点也没关系：下次退出软件时自动换上，再打开就是新版本；
  • 设置、API Key、翻译记录、Zotero 设置全部保留；正在翻译时不会重启，等翻译完再更新；
  • 更新过程中任何一步出错都会自动还原，软件照常能用，并提示可以到 GitHub 手动下载；
  • 不想自动下载可以关掉「自动更新」（macOS 在「设置 → 偏好设置」，Windows 在「使用说明」页），之后有新版本只提示、点了才下载；关于页（Windows 在「使用说明」页）可以随时「检查更新」。
  • macOS 由软件自己下载的新版本不会再弹「无法验证开发者」。
• 注意：自动更新从这个版本开始生效，这一次还需要手动下载安装 v2.3.42，之后的版本都会自动更新。

• 🐛 源语言选「自动检测」时用 Bing 翻译，整篇不翻、保持原文（macOS 默认设置就会遇到；Windows 在添加文件后没能识别出语言时才会遇到）：Bing 接口只认它自己的「自动检测」写法，之前传过去的写法会被拒绝，每一段都翻译失败、保留原文。现在两端都改成 Bing 认的写法；其它翻译服务不受影响。
• 🐛 AI 助手选的模型不再被冲回默认（仅 macOS）：在「设置 → AI 助手 → 自定义」里选好模型后，只要在翻译页点一次「开始翻译」，翻译页就会把软件启动时读到的旧配置整个写回去，AI 助手的设置随之丢失，阅读页又变回翻译服务的默认模型（例如 glm-4）。现在翻译页只保存它自己的选项，不再动设置页的内容（Zotero 输出方式等在本次启动后改过的设置也一样不会再被冲掉）。
• 🐛 阅读页 AI 助手右上角显示的模型会及时更新（仅 macOS）：之前只在打开论文时刷新一次，在设置里改完模型回到阅读页，还显示旧模型。现在每次显示 AI 助手面板时都按最新设置刷新。
• 🐛 AI 助手「默认与翻译服务相同」现在真的跟随翻译页当前选的服务（仅 macOS）：之前如果同时填了几家的 API Key，会固定先用 DeepSeek，而不是你在翻译页选的服务（比如智谱）。现在先用翻译页当前选的服务；选的是 Google、Bing、DeepL 这类不能对话的服务时，才按原来的顺序找一个已配置好的。

• 🐛 选项不再每次启动都回到默认（Mac/Win 同修）：
  • Windows：「翻译完自动打开」「分块翻译」及其大小、间隔之前根本不保存，重启就复原；另外每改一个选项都会把整个配置文件重写一遍，顺带冲掉字号、最近打开的文件等设置。现在这几项都会记住，改选项也不再冲掉别的设置。
  • macOS：翻译页的服务、输出格式、线程数、自动提取术语、分块翻译之前只在点「开始翻译」时才保存，改完没翻译就关掉，下次又是原样。现在一改就保存。
  • 「扫描版 PDF」「OCR 识别」「翻译表格」「翻译图注」是针对单篇文档的选项，仍然每次按需勾选、不记住（避免下一篇普通论文被误当成扫描件处理；扫描件在添加文件时会自动识别）。
• ✨ 输出格式选哪种就只保留哪种（Mac/Win 同改）：之前不管选哪种，单语、双语、并排三个文件都会生成。现在只保留选中的那一种；下拉里新增「全部格式（单语+双语+并排）」，想要三种都留就选它。翻译只做一次，费用和速度都不变（单语和双语本来就是同一次翻译一起产出的）。文献来自 Zotero 时，Zotero 回写要用的格式会一并保留；万一所选格式没生成出来，其它格式不会被删。
• 智谱 GLM 的模型框本来就可以直接手填任意模型名（下拉里只是几个常用建议）；macOS 的建议列表里去掉了已下线的 glm-3-turbo 和不能用于翻译的画图模型 cogview-3。

• 🐛 修复个别 PDF 一开始翻译就报错「code=7: cannot parse object (2 0 R)」（Mac/Win 同修，issue #35 后续）：这类 PDF 内部有个别数据损坏（编号 2 之类的对象解析不了），能正常打开、预览，但软件翻译前要先把原文另存一份，一另存就失败，整篇都翻不了。现在翻译前会先检查，发现这种情况就自动修复后继续翻译（优先用 qpdf 修复，保留书签和链接；不行再只保留页面内容重建），状态栏提示「已自动修复」；不会改动你的原文件。实在修不好时，会说明可以用浏览器「打印 → 另存为 PDF」后再翻译。这个检查很快（500 MB 的文件约 0.3 秒）。
• 🐛 macOS 版改为直接使用 App 自带的中文字体（仅 macOS）：之前 Mac 版每次在系统临时目录里找不到字体时（首次使用，或 macOS 清理了临时目录后），都要先从 GitHub 下载 14 MB 的思源宋体再开始翻译——实测一篇 2 页的文档因此要等 84 秒；网络连不上 GitHub 时翻译会直接失败（报 urlopen error）。现在直接用 App 里自带的字体，同一篇 12 秒完成，也不再依赖 GitHub。

• 🐛 修复 Windows 下多个文件一起翻译完成后「不自动打开、单语版/双语版/并排版按钮是灰的」（仅 Windows，issue #36）：文件列表里有两个及以上文件时会走批量翻译，之前批量结束后只弹一句「输出目录: pdf2zh_files」，三个打开按钮一直是灰的，也不预览、不自动打开，只能去文件夹里找。更麻烦的是，翻译成功的文件会一直留在列表里，之后只加一个文件也还会走批量、把旧文件再翻一遍——于是看起来就像「新版翻完不再自动打开」。现在批量结束时和单个文件一致：
  • 三个按钮点亮（对应最后一个翻译完成的文件），并在右侧预览；
  • 勾了「翻译完自动打开」就自动打开译文（3 个以内逐个打开，更多时打开输出文件夹）；
  • 翻译成功的文件自动移出列表，失败的保留标红、可以重试。
• macOS 端行为不变（一直是单篇/多篇同一流程），本版仅版本号跟进。

• 🐛 修复部分 Windows 电脑上 v2.3.36 仍提示「AI 版面检测模型没有加载成功」、无法翻译（仅 Windows，issue #35 后续）：AI 版面检测依赖的 onnxruntime 需要较新的 Microsoft VC++ 运行库（14.40 以上）；电脑上只有几年前的旧版运行库时就会加载失败（报错「DLL 初始化例程失败」）。而 install.bat 之前只看「装没装过」、不看版本，旧版也当成已安装直接跳过，所以按提示运行 install.bat 也修不好。现在：
  • 软件直接使用安装包里自带的运行库，不再依赖电脑上装的是哪个版本，旧电脑也能直接用；
  • install.bat 改为按版本判断，低于 14.40 会自动安装包里自带的新版运行库；并修正了它判断安装结果的错误。
• 窗口标题、使用说明里的版本号之前有几处写死成 v2.3.34（上传文件后左上角会显示成 2.3.34），现已统一显示实际版本。
• 修正几个 .bat 脚本里「[!]」提示前缀显示不出来的问题。
• macOS 端行为不变，本版仅版本号跟进。

• 🐛 修复 Windows 下双栏论文译文「左右栏拼成一段、文字压到图上、页眉页脚也被翻译」（仅 Windows，issue #35）：这是 AI 版面检测模型没加载上时的典型样子。Windows 版之前只认 用户目录\.cache\babeldoc 里的模型缓存，没有就联网下载；国内网络下载失败时，软件不报错、不带版面检测照样翻译，就翻出了上面那种没法读的结果。现在直接使用安装包里自带的模型（assets\doclayout_yolo.onnx，与原来要下载的是同一个文件），不再需要联网下载。万一模型仍然加载不了（例如电脑缺少 VC++ 运行库），软件会停下并说明怎么修，不再输出不可读的译文。
• 🐛 修复 Windows 下「一键安装 Zotero 插件」装上的是旧版、在 Zotero 10 里被禁用（仅 Windows，issue #34）：Windows 安装包里用于一键安装的插件文件一直停在 1.0.19（只兼容到 Zotero 9），现已换成兼容 Zotero 10 的 1.0.21。已经装了旧版的用户：更新到本版后，在「设置」页再点一次「一键安装」即可。
• Windows 安装包里的支持者名单同步到最新。
• macOS 端行为不变（一直使用自带模型和 1.0.21 插件），本版仅版本号跟进。

• 🐛 修复 Windows 下 Zotero 自定义数据目录的译文「没写回、跑到软件目录」（仅 Windows）：当 Zotero Connector 插件没响应时（最常见是把 Zotero 升级到 9/10 后旧插件被禁用，或翻译时 Zotero 没开着），译文不会再孤零零留在软件目录的 pdf2zh_files 文件夹，而是兜底存回该文献在 Zotero 里所在的文件夹（含你自定义的数据目录），和原文献放在一起、方便找到。根因是 Windows 端在「插件没响应」时提前返回、跳过了这个兜底拷贝（macOS 端一直没这个问题，本次把 Windows 行为对齐到 macOS）。
  想让译文真正自动挂进 Zotero 成为子附件：请到软件「设置」页点「一键安装」把 Connector 插件更新到最新版，并在翻译时保持 Zotero 开着，然后重新翻译。
• macOS 端行为不变，本版仅版本号跟进。

• 🐛 修复 Windows 的 .bat 脚本一跑就满屏「不是内部或外部命令」（仅 Windows）：双击 install.bat（或其它 .bat）会刷出一屏报错、中间还夹着乱码。根因是这些脚本的行尾是 Unix 的 LF，而 Windows 的 cmd.exe 跑批处理必须用 CRLF——LF 会让 cmd 乱切行，把本该显示的提示文字当成命令执行。7 个 .bat（install / uninstall / config_manager / diagnostic / debug_start / module_manager / pdf2zh.bat）全部转成 CRLF，并在开头加 chcp 936（让非中文 Windows 也能正确显示中文）。真机 A/B 验证：旧版 16 处报错 → 新版 0 处。
  说明：这个只影响 .bat 脚本；pdf2zh.exe（编译启动器）和 pdf2zh.vbs 不受影响，一直能正常启动翻译——所以即便撞到这个问题，双击 pdf2zh.exe 就能用。
• macOS 端无 .bat，本版仅版本号跟进，无功能变化。

• 🐛 免费 Google 翻译被限流时的报错说清楚了（Mac/Win 同修）：之前用免费 Google 翻译遇到 429 限流，报错提示「可以把线程数调小一些」——但这条对免费 Google 是误导。实测证明：免费 Google 走的是蹭谷歌公开网页的接口，谷歌按出口 IP 限流，翻墙时大家挤在同一批公共出口 IP 上很容易被限，此时单线程、每 10 秒发 1 次照样 429，调线程数、重试、换节点通常都没用。现在报错会按服务区分：付费 API 的 429 仍提示调线程数（那确实是并发太高）；免费 Google/Bing 的 429 则明确说明是出口 IP 被限、与线程数无关、国内建议改用 DeepSeek（无需翻墙、按账号计额度）。

• 🐛 DeepSeek「关闭思考模式」覆盖到新模型名（Mac/Win 同修，issue #32 相关）：DeepSeek 官方把 flash 系模型改名为 deepseek-flash（旧名 deepseek-v4-flash 仍是可用别名）。我们「翻译时自动关思考模式」的判断原来只认名字里带 v4/chat，deepseek-flash 两个都不含会被漏掉——实测它默认走思考模式（裸调吐 429 字推理），导致翻译又慢又可能漏译。现改为除 deepseek-reasoner（纯推理模型，尊重用户显式选择）外，DeepSeek 一律自动关思考，以后不管官方怎么改名都不会再漏。（实测 flash / v4-flash / v4-pro / chat / coder 关思考后都能正常直出译文。）

• 🐛 修复选了「仅首页/前N页」却输出整篇的问题（Mac/Win 同修）：pdf2zh 的页码范围语义是「只翻这些页，但输出整个文档」，所以选「仅首页」翻 24 页的文件，你会拿到一份 24 页的 PDF——第 1 页是中文，其余 23 页还是英文原文。翻到后面看到英文就以为「没翻译」，看到 24 页就以为「把全部都翻了」。现在选了页码范围后，产物会裁成只含这些页（mono/并排每页对应 1 页，dual 对应原文+译文 2 页）。

• 🐛 修复「连不上翻译服务却显示翻译成功」（Mac/Win 同修）：最典型的场景是用 Google 翻译但没有科学上网——每一段请求都超时、保留英文原文，但软件把整件事记成「翻译完成」，给你一份一个字没翻的英文 PDF，你完全不知道发生了什么。现在当大部分段落都因网络问题保留原文（失败占比 ≥ 60%）时，会明确报错并说明原因，还会提示「Google 翻译需要科学上网，国内建议改用 DeepSeek」。偶发的少量段落失败仍按正常完成处理，只在状态栏提示失败段数，不误伤。

• 🚨 修复 v2.3.30 Windows 版翻译必崩（Mac 版不受影响）：v2.3.30 在 converter.py 里加的行号识别用了内置函数 id()，但同一个函数下方原本就有 for id, v in enumerate(var)——Python 的作用域规则会把 id 当成整个函数的局部变量，于是行号识别那行一执行就 UnboundLocalError，Windows 版 v2.3.30 一个字都翻不出来。macOS 版走的是另一份镜像代码，当时已经用 _objid 别名避开了这个坑，所以只有 Windows 中招。

  排查时用 symtable 做了静态验证：v2.3.30 发布包里 receive_layout 的 id 判定为「局部变量」，修复后判定为「内置」。Windows 用户请务必升级。

• 🔌 Zotero 插件 v1.0.21：兼容 Zotero 10：有用户反映 Zotero 10.0.2 提示插件不兼容。v1.0.19 及更早的上限写死 9.*；v1.0.20 改成了 *（无上限），但 Zotero 官方 2026-07-29 明确要求插件作者不要把上限声明到 10.* 以上——每个大版本都要作者确认兼容才放行，所以"一劳永逸"的写法从规则上就行不通。现按官方指引改为 10.*。

  逐项对照 Zotero 10 的破坏性变更清单（单数选择器、collectionTreeRow、addCondition 的 required 参数、CookieSandbox、fulltextWord…），插件代码一处都没用到，无需改动。同时把 updates.json 里 v1.0.20 的上限也改成 10.*——按官方说法，只改更新清单就能让已装用户的插件重新启用，不必等他们手动换版本。

• 🐛 修复带行号的论文被逐行翻译、译文出现残缺句（Mac/Win 同修）：投稿稿/录用稿常在左边距逐行标行号（249 250 251…，字号和正文一样）。版面模型会把行号栏识别成 abandon（即"保留不翻译"，类别 0），而正文是类别 2~6；两者在字符流里逐行交替出现，段落判断里的"类别变了就另起一段"于是每行都成立，整页退化成逐行翻译。

  每段只剩半句话，模型拿到 …exhibit the appropriate amount of 这种残缺输入只能自己编，译文里就出现「另一个关键方面是预报是否表现出适当的______。」「与……相比」这类句子。

  实测一篇 3 页的录用稿：130 段 → 37 段，中位段长 83 字符 → 整段，句子被切断的比例 17% → 0%。不含行号的文档（普通期刊排版）分段结果逐字节不变，无影响。

  排查时走了弯路，记录下来：只跳过数字本身不够（130→99，改进有限），数字与正文之间那个空格同样落在行号栏的"保留"区，不一起跳过的话段落照样每行断一次。

  代价是译文页不再渲染边距行号（双语对照的原文页仍保留）。实测正文数字留存 100%，无内容丢失。需要时可设环境变量 P2Z_DISABLE_LINENUM_SKIP=1 关掉这个识别。

• 🐛 修复「翻译极慢 / 进度条卡住不动」（issue #30，Mac/Win 同修）：有用户反映「二十分钟翻译了一面」。实测正常基准是 5~30 秒/页（解析+版面分析只占 0.5 秒/页，每页平均只需 3.6 次翻译请求），二十分钟一页慢了 40~240 倍——不是「API 有点慢」，是三个问题叠在一起：

  • 永久性错误被无限重试。converter.py 里翻译 worker 的重试装饰器是 @retry(wait=wait_fixed(1))，没有给 stop=，tenacity 默认就是永不放弃。API Key 失效返回 401 这种错误，重试一万次也不可能成功，于是任务永远不结束。实测：Key 失效时 60 秒内重试 34 次，进度条一动不动，界面上不显示任何报错。
  • 全链路没有超时。openai.OpenAI(...) 没设 timeout/max_retries，吃 SDK 默认值（读超时 600 秒、自动重试 2 次）→ 单个段落一次调用最坏 1800 秒 = 30 分钟。而一页要等它所有段落都完成，一个段落卡住整页就卡住。translator.py 里 6 处 requests 调用同样都没有 timeout=。
  • 出错了用户看不见。所有失败都被静默吞掉，只表现成「慢」。

  现在新增 pdf2zh/net_policy.py 统一处理：永久性错误（401 Key 失效 / 402 余额不足 / 403 无权限 / 404 地址或模型错）立刻停止并弹出中文说明；暂时性错误（超时、限流、5xx）有限次退避重试，仍失败则该段保留原文、结束后提示失败段数，不拖垮整篇。超时统一收到 60 秒。

  实测同一个失效 Key：从无限卡死 → 2.8 秒报出「API Key 无效或已过期（401）。请到「设置」里检查该服务的 Key。」

• ✨ 新增「自动提取术语」（issue #31，Mac/Win 同加）：勾选后，翻译前先通读全文采样，让模型整理出一张专业术语对照表，再注入后续每一段翻译，保证同一个术语在全文里译法统一。实测 144 页专著抽出 30 条术语只要 4 秒，全程只多一次模型调用。手工术语库优先级更高，会覆盖自动提取的结果；提取失败只是少一张表，不影响翻译。仅对大模型服务有效（Google / Bing 等会自动跳过）。

• 🐛 修复 macOS 端术语库完全不生效（issue #31 同源）：macOS 版界面上能编辑、导入、切换预置术语库，但那些词条一个字都不会影响翻译结果——Mac 版 high_level.py 里根本没有 glossary 参数，Worker 也不往下传（Windows 版是通的）。同时修掉 macOS 版 BaseTranslator.prompt 用 eval() 执行提示词模板的问题：它要求模板替换后必须是一段合法的 Python 字面量，写进自然语言就是 SyntaxError，配合上面那个无限重试正好变成永久卡死。现与 Windows 版对齐，按纯文本模板处理。

• 🐛 修复 macOS 端「翻译表格内容」一直静默失败：构造表格翻译器时把 ignore_cache 当成构造参数传了进去，但在 macOS 打包的 pdf2zh 1.8.9 里它是类属性（BaseTranslator.__init__ 只收 lang_in/lang_out/model），每次都抛 TypeError 被 except 吞掉，界面上只闪一句「表格翻译跳过」。

• 🐛 修复翻译「大页面」PDF 时内存暴涨、机器卡死（issue #29 续，Mac/Win 同修）：上一版修掉了闪退，但同一个 issue 里还藏着第二个问题——有用户反映翻译过程中软件内存涨到几十 GB。原因是版面分析的开销跟着页面尺寸无限放大，具体两处：

  • 版面模型的推理尺寸没有上限。代码直接把页面高度当作推理尺寸喂给模型。普通 A4（842pt）、Letter（792pt）、Legal（1008pt）算出来都很小，没问题；但有些扫描版电子书的页面盒子是按扫描像素记的（比如 2550×3300 而不是 612×792），推理尺寸就变成 3296——实测单次推理要 3.10GB / 20.8 秒，而封顶到 2048 只要 0.49GB / 2.9 秒。现已封顶 2048。
  • 每页的版面结果数组一直堆着不释放。每页会生成一张「页宽×页高」的数组（Letter 页 3.7MB，2550×3300 的扫描页 64MB），整本书翻完才统一释放。现改为每页用完立刻释放。

  实测同一份 10 页大页面 PDF（2550×3300pt，文件仅 14KB）：峰值内存 8.40GB → 1.80GB（降到 1/4.7）。

  为什么以前翻 1GB 的大书都没事：这条路径只看页面盒子的尺寸，跟文件多大、内嵌图片多清晰完全无关——1GB 的高清扫描书只要页面是正常 A4，开销就和普通文档一样。另外「分块翻译」会让数组每块释放一次，勾了的话累积量只到一块的页数。所以要同时满足「页面盒子异常大」+「没勾分块」才会触发。

  封顶到 2048 而不是模型默认的 1024：实测 5 页真实杂志版面（2160×2945pt），2048 与封顶前的检出结果框匹配率 95.4%、类别一致率 90.8%，1024 则只有 88.5% / 82.8%。目的是止住内存暴涨，不是改变既有排版行为，所以选更保守的 2048。

• 🔧 构建可复现性：macOS 版打包用的 pdf2zh/high_level.py 此前只存在于系统 Python 的 site-packages 里、没有进版本库（它和 Windows 版不是同一份），换台机器或重装 Python 就会丢掉历年手工补丁。现已纳入 mac/site-packages/，并提供 mac/site-packages/sync_to_system_python.sh 在打包前同步。

• 🐛 修复翻译大文档时程序意外退出（issue #29，macOS）：翻译几百页的大 PDF 时程序会直接闪退，连错误提示都没有。原因是翻译工作线程的栈空间用的是系统默认值（约 512KB，而主程序有 8MB），解析大文档时层层嵌套一深就把线程栈撑爆、撞上系统保护页，进程被直接终止——连 Python 自己的「递归过深」错误都来不及抛出来，所以表现为毫无征兆的闪退。现在给工作线程显式留足栈空间（64MB，只是地址预留、不占实际内存）。
  • Windows 端实测未受此问题影响（系统默认栈更大），但余量同样不厚，本版一并加上同样的保护。

• ✨ 目录页排版还原（macOS + Windows）：带点线的目录页（「标题 ……… 页码」）之前会被当成流水正文翻译，结果分级缩进全丢、页码被塞进正文行里、条目跨行断开甚至漏条，整页糊成一团。现在翻译完成后会自动还原目录排版：
  • 从原文页抽出每个条目的缩进层级、编号、标题、页码，按原样式重排——分级缩进、点线、右对齐页码都回来了。
  • 条目开头的编号（3.1.1 这类）原样保留，不会被翻译器改写。
  • 不影响速度：整页目录的标题打包成一次翻译请求（不是一条一条发），检测本身每页只需几十毫秒；判定很保守，普通正文页不会误命中。

• ✨ Windows 版终于支持扫描件翻译：此前 Windows 版的「OCR 识别（纯图片扫描件）」勾选框实际上不起任何作用——程序把这个开关传给了翻译核心，但核心并不认识它，参数被静默丢弃，等于勾了个寂寞，扫描件照样翻不出东西。这一版把 macOS 版已经打磨好的整套扫描件管线接了过来，两端共用同一份实现：
  • OCR 识别整页文字 → 认出表格/插图/正文 → 表格和插图整块保留原扫描图、正文分栏分段翻译 → 思源宋体白底渲染，横排（旋转 90°）内容按原方向还原。
  • 同样产出纯译文、原文译文交替、左右对照三种格式。
• 🔧 扫描件管线抽成独立模块（pdf2zh/ocr_pipeline.py），macOS 与 Windows 共用一套代码，后续改进两端同步生效，不会再出现「一端修好另一端还是老样子」。

• ✨ 扫描件里的表格、插图不再被翻烂（macOS）：之前扫描件是整页当作流水正文重排，表格被拆成一段一段的文字，行列错位、数字和表头对不上；整页横排的大表（要把纸转 90° 才能看的那种）更是直接排成乱码。这一版给扫描件接入了程序里本来就有的版面识别能力——先认出页面上哪块是表格、哪块是插图公式、哪块是正文：
  • 表格 / 插图 / 公式：整块保留原扫描图，结构完好可读，不再被重排打散；表格标题、表下注释照常翻译。（顺带解决了此前扫描件会丢失插图的问题。）
  • 正文、标题、图表标题：照常翻译排版。
  • 横排（旋转 90°）的内容：正确识别并竖排还原，表号、页眉等跟着原方向翻译，不再糊成一团。

• 🔧 扫描件译文字体更好看、字号行距更统一（macOS）：
  • 改用思源宋体：扫描件译文之前用的是系统默认的无衬线字体，偏细偏扁不好看；现在换成和普通 PDF 翻译一致的思源宋体（已随程序打包，离线也能用）。
  • 同页字号、行距统一：上一版为了让每段译文填满原段落框，按每段单独算行距，导致同样大小的段落译出来字号、行距却不一样。现在整页正文用统一字号、统一行距，长译文靠"裁剪到下一段顶部"避免重叠，读起来整齐一致。

• ✨ 扫描件译文版式贴合原文（macOS）：上一版扫描件独立翻译管线已把内容翻干净，但版面还原不够——多栏页容易分栏错、段落切分位置不对、译文只占段落上半截导致段间大片空白。这一版重做了版面还原：
  • 按栏间白槽分栏：统计每一横向位置的文字覆盖，找出栏与栏之间的竖直空白缝来分栏，能正确处理「整宽摘要 + 双栏正文 + 脚注」这类混排页，不再把跨栏的标题/摘要硬塞进某一栏。
  • 按首行缩进分段：学术论文靠首行缩进标示新段落，改成识别缩进（配合段间空隙）来切分，段落边界更准。
  • 填满原段落框：按译文实际行数把行距撑到填满原段落在页面上的位置，消除段间大空白，整页版式贴合原扫描页。

• ✨ 扫描件翻译改用独立管线，效果大幅提升（macOS）：之前扫描件（纯图片）勾选「OCR 识别」翻译后，常出现中英文糊叠、大片原文英文没被遮住、排版错乱。根因是扫描件套用了普通 PDF 的翻译流程——版面模型会把扫描页的部分正文误判成图/公式而漏翻，且整张原始扫描图一直垫在下面、没翻到的地方英文就透出来。这一版给扫描件单独做了一条翻译管线：先 OCR 识别整页文字，自动分栏、合并段落，把每一段都送去翻译（不再有"当成公式跳过"这回事），再渲染到干净的白底页上。译文因此几乎全中文、版式清爽，连页眉页脚都翻译，人名和文献年份按惯例保留原文。
  • 三种输出格式都优化了：mono = 纯译文白底页；side_by_side = 左边原始扫描图、右边干净译文，方便对照；dual = 原文页与译文页交替。
  • 🐛 顺带修复 OCR 无视页码选择：之前勾了 OCR 就算只选「仅首页」也把整本每页都识别一遍（每页数秒、纯属白等），现在只处理选中的页码。
  • ⚠️ 说明：扫描件会丢弃原图里的插图/表格（换取纯文字的清爽排版），且识别质量取决于扫描清晰度。有数字版（可直接选中文字）时仍建议优先用数字版。

• 🐛 修复扫描件勾选「OCR 识别」后不翻译（macOS）：纯图片扫描件勾了 OCR、识别也跑完，结果输出还是原文。排查出三层叠加的原因，逐层修复——
  • OCR 引擎没打包进 app：rapidocr 只装在源码目录、系统环境没有，打包时被静默跳过，发布版里一个 OCR 文件都没有 → 勾了 OCR 也只是「模块缺失、跳过」。现在把 OCR 引擎和它的 3 个模型一起打包进去。
  • OCR 中间文件被误删：识别后的带文字层文件写在系统临时目录，翻译管线有一步会主动清理临时目录里的文件，大文档分块翻译时它在两趟之间被删掉，第二趟就报「文件不存在」。改成写到输出目录下的专用子目录。
  • 识别出的文字没能写进文字层：旧写法在文字框放不下时会把整行丢弃，实测一页 111 行文字最后一个字都没留下。改用定点落字，识别结果完整进入（隐藏）文字层，翻译管线才拿得到文字。
• 🔧 扫描件翻译自动启用白底覆盖：译文落在干净背景上，不再和原始扫描图糊叠在一起。
• 🐛 （随本版一并发布 v2.3.19 的 Zotero 回写修复，此前只提交未打包发布）：自定义名称数据目录、C/D 双库、Attanger 链接文件三种情况下的不回写问题。

• 🐛 修复自定义名称的 Zotero 数据目录不回写：之前抠条目号的正则把数据目录名写死成"Zotero"，用户把数据目录改名(如 E:\Zotero文档\storage、D:\我的文献\storage)后就匹配失败、被当成非 Zotero 文件跳过。改成不认目录名、只认 storage\<条目号>\ 这个 Zotero 真正特征
• 🐛 修复"C 盘 D 盘各有一个 Zotero 库"时查错库导致不回写：把数据目录搬到别处(如 D 盘)、默认位置(C 盘)还残留旧库时，之前是"按哪个库条目多用哪个"来猜，会挑错到残留的旧库 → 链接文件/Attanger 附件在活动库里查得到、在旧库里查不到 → 不回写。现在改成认准 Zotero 配置文件(prefs.js)里指定的活动数据目录
• 🔧 回写失败提示改清晰：插件没响应时明确提示"多半是插件旧版被 Zotero 禁用，请到设置页更新插件"，不再显示过时的 xpi 文件名

• 🐛 修复"链接文件"型 Zotero 附件翻译后不回写：之前整套回写只认"导入存储"型附件（文件被 Zotero 复制进 Zotero/storage/<条目号>/ 里，靠路径抠出条目号）。但用了 ZotFile / Attanger、或选了"链接到文件"、或设了附件基目录的用户，PDF 是"链接文件"型——留在自己的目录里、不在 storage 下，路径抠不到条目号，于是界面显示不出条目名、回写被直接跳过（同学反馈"有的能回写、有的显示不了条目就不能回写"）。现在加了数据库反查兜底：路径抠不到时，去 Zotero 库里按文件真实路径反查它的条目号（覆盖 storage / 绝对路径 / 附件基目录相对路径三种），存储型附件走原逻辑不变。已在真实 Windows + Attanger 环境验证

• 🐛 修复 Zotero 升级到 10 后回写失效：Connector 插件（pdf2zh-connector-v1.0.19 及更早）的 manifest 里把兼容上限写死成 strict_max_version: "9.*"，Zotero 升级到 10 后会被判定为不兼容，直接整个禁用插件——用户端表现是"翻译完不回写到 Zotero"，且没有任何报错（因为插件从一开始就没启动，HTTP 端点根本没注册）。现在改成不设兼容上限（"*"），并把版本升到 v1.0.20；已装旧版插件的用户下次 Zotero 自动检查更新时会自动升级，不需要手动重装。受影响的用户如果等不及自动更新，可以去 Zotero「工具→附加组件」手动禁用/删除旧版 pdf2zh Connector 后，到 pdf2zh-desktop「设置」页重新一键安装

• ✨ PDF 预览右键菜单新增旋转：新增"顺时针旋转"/"逆时针旋转"，方便核对表格等内容的排版方向是否正确；只影响预览显示，不修改 PDF 文件本身；切到新文件会自动重置旋转角度；旋转状态下暂不支持高亮框选（屏幕坐标到 PDF 坐标的换算目前只按缩放算，没考虑旋转，避免高亮位置算错）

• 🔧 表格翻译改用 PyMuPDF insert_htmlbox 插入译文：一次性解决三个长期存在的表格排版问题——① 之前手写的字号估算和实际排版有偏差，同一张表里长短不一的译文字号此起彼伏，现在用 scale_low=0 让 PyMuPDF 按真实字体度量自动缩放；② 之前整段文字只能整体选中文或西文字体，中英混排内容要么中文变问号、要么英文字母间距被拉得很宽，现在按字符自动做中西文字体回退；③ 旋转方向经过与原表格未改动内容逐字比对校准，不再出现"有的顺时针有的逆时针"
• 🐛 修复表格翻译导致输出文件暴涨到几百 MB：insert_htmlbox 每次调用都会给中文内容独立内嵌一份完整字体子集、不会跨单元格复用，一张表几十上百个格子就是几十上百份几乎重复的字体数据；加上原来用增量保存（saveIncr）不做垃圾回收，实测 166 个单元格能把 5.85MB 的文件撑到 313MB。现在改成完整重写并加 garbage=4 垃圾回收合并重复对象，同样的内容文件只多出几 MB
• 🔧 修复部分学术论文里 "≥" 等数学符号因源 PDF 字体编码缺陷被提取成 "$"、进而被翻译成"⋯美元"这种莫名其妙的措辞（原理与已知的 "45°" 提取成 "�" 是同一类源文件缺陷，通过识别"整份文档里只产出这一个可疑字符"的嵌入符号字体来定位并修正，不会误伤表格里真实的美元金额）

• 🔧 表格翻译支持整表旋转排版：部分学术论文的表格整体旋转 90°（不只是列标题，连数据单元格都是转向的），之前译文一律横排插入，方向和原表格对不上，还会跟相邻格子重叠成一团。现在会识别每个单元格的真实排版方向，译文按相同方向旋转插入
• 🔧 修复统计区间数值（如 "87.2 (81.8–91.2)"）被翻译服务做无意义换行重排，触发没必要的重新插入、和相邻单元格挤在一起
• 🔧 修复译文字号忽大忽小：改成以单元格原文字号封顶，不再各自独立按译文长度反推字号
• 🔧 新增 --tables=<页码> 命令行参数，供自动化测试/脚本化调用（例如 Zotero 联动）勾选表格翻译并指定页码

• 🔧 表格翻译结果改为持久弹窗提示：之前不管表格翻译成功还是失败，都只往状态栏发一条一闪而过的文字，很快被"翻译完成"覆盖掉，用户基本看不到——这正是 v2.3.11 那个"勾了却悄无声息失败"问题真正没堵上的部分。现在翻译完成后，如果表格翻译遇到问题、没检测到表格、或检测到表格但没有单元格被翻译，都会弹出一个不会自动消失的提示，说明具体原因（--auto/Zotero 无人值守唤起时改为写入调试日志，不弹窗阻塞）

• ✨ 表格翻译支持单独指定页码：正文可以整篇正常翻译（页码范围不受限），同时单独框出"只对第几页做表格单元格翻译"，两者互不影响。留空则跟随主翻译的页码范围（v2.3.11 行为不变）

• 🔧 修复"翻译表格内容"选项勾了也不生效：Mac 端表格翻译走的是一套独立实现，固定调用需要单独配置 API Key 的"AI 助手"服务，和主界面选的翻译服务（哪怕是完全不需要 Key 的 Google/Bing）是两回事；没配这个额外 Key 时每个单元格都会静默失败、界面上毫无提示。现已改成直接复用主翻译服务，不再需要额外配置
• 🔧 同时修复：纯数字/日期单元格（如"893"、"2021"）不再被误翻译；译文字号改成按文本量自适应，减少挤成一堆换行的情况；表格翻译现在会遵守主翻译设定的页码范围，不再无视页码限制扫全篇

• 🔧 修复竖排表格翻译后文字乱序堆叠（issue #28）：论文里常见的旋转 90° 的竖排表头，此前会被版面检测误判成"同一个公式"整体拼接，导致相距很远的多个旋转单词挤在一起、文字被拆散；同时旋转角度本身也没有被保留，画出来是正立字母摞成一列。现已分别修复：按字符间距强制断段 + 保留原始旋转矩阵，竖排表格恢复正常显示

• 🔧 修复 Windows 安装脚本乱码崩溃：install.bat 等批处理脚本在部分中文 Windows 上会因编码问题乱码崩溃（详见下方「启动」章节说明）；同时调整首次启动的推荐方式，pdf2zh.exe 现在是首选，install.bat 降级为可选的快捷方式创建工具

• 🔧 修复某些 PDF 翻译到一半崩溃：论文附录里常见的小尺寸图表页，会因版面检测分辨率过低导致底层 ONNX 报错（TopK k argument...），使整个翻译任务崩溃；现已修复，正常页面不受影响

• 🔧 Zotero 写回不再留冗余文件：之前译文会先复制进原文献的 Zotero storage 文件夹再关联附件，关联成功后那份复制品就成了没人引用的孤儿文件。现在直接从本地输出路径关联，只有关联失败时才会保留一份本地兜底副本，绝不误删翻译产物
• 🔧 修复 xpi 自动更新地址配置错误（之前一直指向别的项目，形同虚设），Connector 插件升到 v1.0.19
• ✨ 新增桌面 App 检查更新：启动后台静默检测新版本，只提示不自动下载替换任何文件

• 🔧 修复自定义 / OpenAI 兼容 API（含硅基流动等）译文混入译者注：给所有 OpenAI 兼容服务加上强约束提示词 + 输出兜底清洗，不再冒出「（注：…）」这类多余解释（#27）

• 🔧 修复 DeepSeek V4 翻译问题：V4 系列裸调默认走「思考模式」导致翻译慢/偶发漏译/费用上涨，现自动关闭思考模式退回直出；默认模型换成 deepseek-v4-flash

• 🔧 Zotero 右键翻译格式选择修复：之前无论选哪种格式，回写 Zotero 的都只有中外并排，现在严格跟随右键菜单选择
• ✨ 新增后台静默翻译：Zotero 右键菜单可勾选，翻译时不弹窗不抢焦点，完成后自动关窗

• ✨ 新增 Zotero 右键翻译：不用打开 pdf2zh，Zotero 里对 PDF 右键直接翻译，自动作为子附件加回原文献
• ✨ 支持单文件输出格式选择（仅并排 / 仅双语 / 仅译文）

• Zotero 条目/PDF 附件拖拽识别（解析 x-moz-custom-clipdata MIME）
• 翻译完成自动回写 + 通过插件自动关联附件
• 一键安装 pdf2zh Connector 插件（自动写 extensions.json + 重启 Zotero）
• 附件标题带格式标签（side by side - 论文名）
• 智能数据目录检测（读 prefs.js 自定义路径 + 多磁盘扫描 + 选最大库）
• 支持内置存储 / 绝对链接 / 相对链接三种附件格式

• 全新 UI（克莱因蓝配色 + 圆角卡片 + 微软雅黑）
• API 配置改为悬浮弹窗，切换服务零跳动
• 提示词 / 术语库改为弹窗编辑
• 连续滚动 PDF 预览（懒加载）
• 标签页三等分 + 使用说明标签页
• 字号切换（小/中/大）
• 缩略图面板自适应 + 页码标注
• 历史记录防抖 + 右键菜单（打开目录/复制路径）
• 翻译完成自动清空文件列表
• 窗口自适应屏幕分辨率

• 独立表格翻译管线（按单元格翻译 + 自适应字号）
• 独立图注翻译管线
• 35 种语言支持 + 源语言自动识别
• 自动检测扫描件 + 翻译前预检
• 预估剩余时间 + 崩溃恢复 + 批量失败重试

• 修复取消翻译闪退
• 修复 ollama 导入阻塞（延迟导入）
• OnnxRuntime 8 秒超时机制
• PDF 预览快速切换 150ms 防抖
• 历史记录 200ms 防抖
• 删除/清空历史不再闪退

• 首个功能完整版本
• 20+ 翻译服务 + AI 配置面板
• OCR / 表格翻译 / 扫描版支持
• 术语库 + 自定义提示词
• 连续滚动预览 + 拖放 + 批量翻译

• 首个公开发布版本

桌面版作者：@AaronGIG (CAS)

桌面版的独立打包、GUI 增强、便携化改造、Zotero 联动等功能由 AaronGIG (CAS) 与 Claude (Anthropic AI) 协作开发完成 🤖✨

核心翻译引擎：PDFMathTranslate（EMNLP 2025），感谢原项目的贡献 🤝