PDF翻译失败、被限流或只剩一半?VI-Translate错误码速查清单与6个常见坑的解决方案

原创2026-11-01 11:33:211,357 阅读

PDF翻译失败、被限流或只剩一半?VI-Translate错误码速查清单与6个常见坑的解决方案

PDF翻译工具 VI-Translate(应用名 PDF Translate)可以把 PDF 文档翻译成越南语等 36 种语言,并保留版式、公式和表格。但在实际使用中,不少新手会碰到三种典型状况:翻译失败、被 Google 限流(Rate Limit)、结果只剩一半没有生成。好消息是:这套工具的每个失败都有一个稳定的错误码(如 E-NET-08、E-PDF-03),看懂错误码基本就能自助排错。本文整理一份完整的PDF翻译错误码速查清单,并针对 6 个最常见的坑给出可操作的解决方案。


错误码是怎么来的:先看一眼队列里的那行提示

应用内每个失败都会在任务队列里显示一行「简短摘要 + 错误码」,例如 Google hiện từ chối yêu cầu từ kết nối này <a href="https://link.gitcode.com/i/108de8406077a1719d22ce73ca896063" target="_blank">E-NET-08]。这个设计来自 [app/errors.py:

  • E-XX-NN 稳定错误码:同一类问题永远对应同一个码,方便搜索和反馈;
  • 一句人话摘要:告诉你出了什么事;
  • 一条具体建议:告诉你下一步该做什么;
  • 完整技术细节:保留原始异常链,用于生成报错文本。

分类逻辑会把整条异常链压平后按规则匹配(实现见 describe_failure()),未识别的问题会落到兜底码 E-UNK-99。相关回归测试在 tests/test_app_errors.py,可以看到每种错误码都锁定了「摘要 + 可操作建议」两要素。


PDF翻译错误码速查清单(全量)

按前缀记忆最省力:E-PDF = 文件问题,E-NET = 网络问题,E-OCR = 扫描识别问题,其余为浏览器、内存、输出等。

错误码 场景 一句话处理
E-PDF-01 文件不是合法 PDF(不存在 / 无 .pdf 扩展名 / 缺少 PDF 头) 确认文件还在原位,且是真 PDF
E-PDF-02 PDF 结构损坏(FzErrorSyntax 等) 用阅读器打开后「打印为 PDF」得到干净副本,再翻译该副本
E-PDF-03 PDF 只有扫描件图片、无文字层 开启 OCR:「扫描页 → 自动」后重新翻译
E-OCR-07 OCR 无法安全处理该扫描页 改用 OCR「标准」模式;仍失败则使用带文字层的 PDF 或提交报告
E-NET-04 连不上翻译服务(超时、SSL、重试耗尽) 检查网络或 VPN;已译段落有缓存,重跑更快
E-NET-08 Google 限流(HTTP 429,RateLimitedError) 暂停等待再点「继续翻译」;不要反复重发请求
E-NET-09 翻译服务无响应 / 拒绝访问 检查连接后点「继续翻译」
E-BROWSER-01 无法打开 Google 验证浏览器窗口 完整解压应用,关闭上次的 Google 窗口再试;已译内容已缓存
E-VERIFY-01 你选择了「稍后再验证」 想验证时点「继续翻译」即可恢复
E-CORE-01 缺少内部库(DLL load failed、ImportError) 完整解压整个目录再运行,别在 zip 里直接跑;给杀毒软件加白名单
E-OUT-05 输出文件已存在 勾选「覆盖已翻译文件」或删除 translated/ 里的旧文件
E-MEM-06 内存不足(MemoryError) 关闭其他程序,或把大文件拆分分批翻译
E-UNK-99 未识别错误 直接复制报错报告提交给开发者

完整规则表见 app/errors.py 的 _RULES。


6个常见坑及对应解决方案

坑1:被限流(E-NET-08)——别反复点重试,先等满冷却期

这是新手问得最多的「为什么翻译到一半就停了」。Google 会拒绝来自同一连接的请求,工具的处理策略是整批暂停而不是死磕:

  • 已翻译成功的段落全部缓存在本地,不会丢;
  • 暂停后点击「继续翻译」(gui.py 中该按钮在 E-NET-08/E-NET-09/E-BROWSER-01/E-VERIFY-01 场景下都会出现)即可续跑;
  • 被拦截后应用会至少静默 10 分钟再尝试重发;如果 Google 通过 Retry-After 要求更久,连重启应用后也会遵守该时长;
  • 每个请求之间至少间隔 5 秒以降低压力,但这不保证不被限流;
  • 换 DNS 无法解除 HTTP 429 或 CAPTCHA。

💡 正确姿势:看到 E-NET-08 就把应用放着,去做别的事,冷却结束后点一次「继续翻译」即可,已译部分会直接复用。

坑2:在 zip 包内直接双击 exe(E-CORE-01)——必须先完整解压

E-CORE-01 的典型症状是启动或翻译时报 DLL load failed / ImportError / ModuleNotFoundError。绝大多数情况是没有把压缩包完整解压,或者杀毒软件误删了内部依赖文件。

✅ 正确操作:

  1. 把整个 zip 全部解压到本地目录(约 336 MB,解压后体积更大,先确认磁盘空间);
  2. 从解压后的目录里运行 PDFTranslate.exe,不要从 zip 内直接运行;
  3. 给杀毒软件添加例外,避免依赖被静默清除。

坑3:扫描件翻译「只剩一半」或不翻译(E-PDF-03 / E-OCR-07)——先开 OCR

如果你发现输出文档里有页是原样未动的,或者干脆提示「无文字层」,先检查你的 PDF 是不是纯扫描图片。OCR 默认是关闭的,应用只处理已有的文字层:

  • 在选项里把「扫描页」设为自动,再点翻译;
  • 含表格、公式、复杂图片的页面会被主动保留原样,队列标记为「部分翻译」——这是安全策略,不是 bug(安全优先的设计思路见 research/ocr-spike/FINDINGS.md);
  • OCR「高级」模式明显更慢,主要用于实验;日常用「标准」即可。

坑4:输出已存在被跳过(E-OUT-05)——其实不是失败

E-OUT-05 的场景是 translated/ 目录里已经有同名结果文件。应用默认不覆盖旧翻译,这行提示更像「跳过」而非错误:

  • 想重新翻译:勾选「覆盖已翻译文件」再跑;
  • 或者手动删除 translated/ 里的旧文件。

结果目录结构参考 README.md:

TaiLieu/
├── document.pdf
└── translated/
    └── document-vi.pdf

坑5:PDF 本身损坏(E-PDF-02)——打印为 PDF 得到干净副本

FzErrorSyntax、damaged beyond repair 这类报错说明文件在结构层面已经损坏,工具修不了也不该硬修。最省事的自救:

  1. 用任意 PDF 阅读器打开该文件(能打开就说明内容层基本可用);
  2. 打印 → 目标选「打印为 PDF」,另存一个新文件;
  3. 翻译这个新生成的干净副本。

坑6:大文件内存不足(E-MEM-06)——分批处理

长书翻译到后面突然报 MemoryError,通常是内存被耗光(长文档在收尾阶段会整体压缩重排)。对策很直接:

  • 关闭浏览器等吃内存的程序;
  • 把 PDF 拆成几个部分(可以按章节另存),分批翻译再合并。

限流暂停后:缓存与「继续翻译」机制说明

很多新手担心「停了会不会从头再来」。答案是不会:

  • 成功段落缓存在本地,续跑时直接复用,重跑会越来越快;
  • 队列是多文件不阻塞设计——一个文件报错不会卡住其余文件(见 app/ 队列实现与 gui.py);
  • 「正在做」的文件在被限流中断时不会导出半截 PDF,避免你误拿到不完整的成品;
  • 浏览器验证模式(Google 经浏览器 + 手动过 CAPTCHA)失败或选择「稍后」时对应 E-BROWSER-01 / E-VERIFY-01,处理方式同样是等待后点「继续翻译」。

关于限流与 CAPTCHA 的更多行为细节,见 README.md「Agent Skill」一节。


报错看不懂?一键复制报错报告

每个失败都能生成一段自包含的报错文本(由 report_text() 生成),自动包含:

PDF Translate - báo cáo lỗi
Thời điểm : 2026-11-01 01:30:12
Phiên bản : 0.2.2
Hệ điều hành: Windows 11 (AMD64)
Python    : 3.11.x
File      : Skin.pdf
Mã lỗi    : E-CORE-01  Ứng dụng thiếu thư viện nội bộ

Chi tiết kỹ thuật:
ImportError: ...

你不需要自己拼环境信息——直接复制这段文本提交给开发者即可,维护者凭「错误码 + 异常链 + 版本号」就能复现问题。日志文件路径若存在也会一并附上。


小结:一份口袋版排错流程

  1. 看队列里的错误码(本文速查表直接对号入座);
  2. E-NET-* → 停一停、等冷却、点「继续翻译」,缓存不会丢;
  3. E-PDF-* → 检查文件本身:重新下载、打印为 PDF、或开 OCR;
  4. E-CORE-01 → 完整解压 + 杀软加白名单;
  5. E-UNK-99 → 复制报错报告提交;
  6. 长文档卡死/内存不足 → 拆分分批。

掌握这套错误码 + 缓存续跑机制后,PDF 翻译失败、限流、「只剩一半」这几类新手高频问题基本都能在三分钟内定位并恢复。更多排错与回归案例可参考 agent-knowledge/regressions.md 与 agent-knowledge/validation.md。

登录后查看全文
VI-Translate