PDF翻译失败、被限流或只剩一半?VI-Translate错误码速查清单与6个常见坑的解决方案
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。绝大多数情况是没有把压缩包完整解压,或者杀毒软件误删了内部依赖文件。
✅ 正确操作:
- 把整个 zip 全部解压到本地目录(约 336 MB,解压后体积更大,先确认磁盘空间);
- 从解压后的目录里运行
PDFTranslate.exe,不要从 zip 内直接运行; - 给杀毒软件添加例外,避免依赖被静默清除。
坑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 这类报错说明文件在结构层面已经损坏,工具修不了也不该硬修。最省事的自救:
- 用任意 PDF 阅读器打开该文件(能打开就说明内容层基本可用);
- 打印 → 目标选「打印为 PDF」,另存一个新文件;
- 翻译这个新生成的干净副本。
坑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: ...
你不需要自己拼环境信息——直接复制这段文本提交给开发者即可,维护者凭「错误码 + 异常链 + 版本号」就能复现问题。日志文件路径若存在也会一并附上。
小结:一份口袋版排错流程
- 看队列里的错误码(本文速查表直接对号入座);
E-NET-*→ 停一停、等冷却、点「继续翻译」,缓存不会丢;E-PDF-*→ 检查文件本身:重新下载、打印为 PDF、或开 OCR;E-CORE-01→ 完整解压 + 杀软加白名单;E-UNK-99→ 复制报错报告提交;- 长文档卡死/内存不足 → 拆分分批。
掌握这套错误码 + 缓存续跑机制后,PDF 翻译失败、限流、「只剩一半」这几类新手高频问题基本都能在三分钟内定位并恢复。更多排错与回归案例可参考 agent-knowledge/regressions.md 与 agent-knowledge/validation.md。