v0.7.12026-11-07
BabelDOC v0.7.1
Bug Fixes
- Fixed a regression in 0.7.0 where constructing TranslationConfig without an inputfile (for example, a configuration used only to drive a progress display) raised TypeError. This broke the pdf2zhnext command line with BabelDOC 0.7.0.\
修复 0.7.0 引入的回归:不传 inputfile 构造 TranslationConfig(例如只用于驱动进度显示的配置)时会抛出 TypeError,导致 pdf2zhnext 命令行在 BabelDOC 0.7.0 下无法使用。
---
Changes
* No changes
Contributors
@awwaawwa
v0.7.02026-11-07
BabelDOC v0.7.0
Highlights
- PDF parsing and the processing stages that follow it, that is scanned-file detection, layout handling, paragraph and style processing, translation orchestration, typesetting, and PDF writing, now run in Rust and ship as a compiled extension inside the package. Python remains the entry point and still provides the layout model and translation service integrations. The implementation follows the 0.6.4 behavior for documents on the default path; the intentional differences are the watermark change and the new default resource limits, both listed below.\
PDF 解析及其后的各处理阶段,即扫描件检测、版面处理、段落与样式处理、翻译编排、排版和 PDF 写出,现在在 Rust 中运行,并以编译好的扩展随包发布。Python 仍是入口,并继续提供版面模型和翻译服务的集成。对默认路径上的文档,实现按 0.6.4 的行为保持;有意的差异是下面列出的水印变更和新增的默认资源上限。
- Performance has improved; parsing in particular is faster and uses less memory than in 0.6.4.\
性能有所提升;尤其是解析阶段,比 0.6.4 更快、占用内存更少。
- Prebuilt abi3 wheels are published for five platforms: Linux x86-64 and ARM64 (manylinux228), Windows x86-64, macOS Intel, and macOS Apple Silicon. One wheel per platform covers Python 3.10 through 3.13. Other platforms install from the source distribution, which compiles the extension and therefore needs a Rust toolchain. Both wheels and source installs require Python 3.10–3.13.\
提供五个平台的预编译 abi3 wheel:Linux x86-64 和 ARM64(manylinux228)、Windows x86-64、macOS Intel、macOS Apple Silicon。每个平台一份 wheel,覆盖 Python 3.10 到 3.13。其他平台从源码包安装,安装时会编译扩展,因此需要 Rust 工具链。无论 wheel 还是源码安装,都要求 Python 3.10–3.13。
- The Python implementations that the Rust code replaces were removed, including the bundled babeldoc.pdfminer package and the old Python parser, stage and generator modules. Code outside BabelDOC that imports those internal modules directly will no longer work; the public entry points (highlevel.translate, highlevel.async_translate, TranslationConfig, TranslateResult, WatermarkOutputMode, Glossary) are kept.\
被 Rust 取代的 Python 实现已删除,包括随包的 babeldoc.pdfminer,以及旧的 Python parser、各处理阶段和生成器模块。在 BabelDOC 之外直接导入这些内部模块的代码将不再可用;公开入口(highlevel.translate、highlevel.async_translate、TranslationConfig、TranslateResult、WatermarkOutputMode、Glossary)保留。
- The first-page watermark is no longer added. WatermarkOutputMode and its options are still accepted and still control output file names and how many files are written, but they no longer change the content of the PDF, and TranslationConfig logs a deprecation warning when it is constructed.\
不再添加首页水印。WatermarkOutputMode 及相关选项仍然被接受,仍然决定输出文件的名称和数量,但不再改变 PDF 的内容;构造 TranslationConfig 时会打印一条弃用警告。
- Added resource safety limits for parsing the input PDF. They are on by default. A document that would exceed a limit stops the run with babeldoc.format.pdf.parserresource.ParserResourceLimitError (a RuntimeError subclass that carries the name of the limit, its value, and where it was hit). The limits can be turned off as a whole with TranslationConfig(disableparserresourcelimits=True); BabelDOC then logs a warning.\
新增对输入 PDF 解析阶段的资源安全上限,默认开启。文档一旦会超出某个上限,运行就会中止,并抛出 babeldoc.format.pdf.parserresource.ParserResourceLimitError(RuntimeError 的子类,带有上限名称、上限值和触发位置)。可以用 TranslationConfig(disableparserresourcelimits=True) 整体关闭;关闭时 BabelDOC 会打印一条警告。
- PDFs are complex, and there may be cases that these limits and this implementation do not handle well. We recommend that anyone running BabelDOC on untrusted files also set limits outside the process, for example a timeout on the subprocess that runs the translation and a memory limit on the container.\
PDF 本身很复杂,这些上限和这套实现可能有考虑不周的地方。凡是用 BabelDOC 处理不可信文件的部署,建议同时在进程外设置限制,例如给运行翻译的子进程设超时,给容器设内存上限。
Security
This release includes security hardening for PDF parsing, reported via coordinated disclosure: GHSA-h972-phhq-7368 and GHSA-wrv8-h9rp-6fqq, both affecting BabelDOC <= 0.6.4; see the published advisories for details.\
本版本包含 PDF 解析方面的安全加固,相关问题通过协调披露上报:GHSA-h972-phhq-7368 与 GHSA-wrv8-h9rp-6fqq,均影响 BabelDOC <= 0.6.4;完整细节见上述通告。
We thank @tinyb0y and @zachariah-mithani for reporting these issues privately and cooperating with coordinated disclosure.\
感谢 @tinyb0y 与 @zachariah-mithani 私下上报这些问题并配合协调披露。
Dependency Updates
- BabelDOC no longer depends on bitstring, which fixes the import failure on fresh installs that resolved to bitstring 5.0 (see issue #626).\
BabelDOC 不再依赖 bitstring,新装时解析到 bitstring 5.0 导致导入失败的问题随之解决(见 issue #626)。
- pymupdf is now constrained to >=1.26.7,<2. PyMuPDF 2.x is not supported by this release.\
pymupdf 的约束改为 >=1.26.7,<2。本版本不支持 PyMuPDF 2.x。
- The package is now built with maturin instead of hatchling.\
打包后端由 hatchling 换成 maturin。
- pdf2zh_next 2.10.2 is the matching release for BabelDOC 0.7.x.\
pdf2zh_next 2.10.2 是与 BabelDOC 0.7.x 配套的版本。
Compatibility Notes
- This release replaces the implementation of the whole pipeline. Output for documents on the default path is intended to match 0.6.4, apart from the watermark change and the resource limits above, but please check results on your own documents before upgrading production deployments.\
本版本替换了整条流水线的实现。对默认路径上的文档,输出预期与 0.6.4 一致(上面的水印变更和资源上限除外),但在升级生产部署之前,请先用自己的文档核对结果。
- A document that legitimately exceeds one of the default resource limits is now rejected with ParserResourceLimitError. If you need to process such a document, disable the limits as described above and apply limits from the outside.\
确实超出某个默认资源上限的文档,现在会被 ParserResourceLimitError 拒绝。如果必须处理这样的文档,可按上文关闭上限,并在进程外另设限制。
- Installing from the source distribution, or building from a checkout, now requires a Rust toolchain. Wheels for the five platforms above do not.\
从源码包安装,或从源码检出构建,现在需要 Rust 工具链。上述五个平台的 wheel 不需要。
Maintenance Policy
BabelDOC publishes security fixes only in the latest release. We do not publish maintainer-supported backports for older minor, patch, or release lines. For the security fixes shipped in 0.7.0, the maintainer-supported fixed version is 0.7.0 or later; downstream distributors may carry their own patches, but older BabelDOC releases will not receive a separate upstream backport.\
BabelDOC 只在最新发布版本中发布安全修复。我们不向更早的 minor、patch 或 release 线发布维护者支持的回移版本。对于 0.7.0 中的安全修复,维护者支持的修复版本为 0.7.0 及以后;下游发行方可自行打补丁维护更旧版本,但上游不会为更早的 BabelDOC 版本提供独立的回移发布。
---
Changes
* No changes
Contributors
@awwaawwa
v0.6.42026-07-16
BabelDOC v0.6.4
Highlights
- Added a unified per-page raster pixel budget for layout detection, improving
memory use and stability on PDFs whose declared page size is far larger than
the real physical size (for example, scanned documents whose pixel dimensions
were written into the page box as points). Such pages previously forced very
large layout-detection renders that could exhaust memory; BabelDOC now caps the
render at a fixed pixel budget and lowers the render DPI when needed, while
preserving layout coordinate semantics. The budget is applied to local layout
detection and scanned-file detection.
为布局识别引入统一的单页光栅像素预算,改善“声明页面尺寸远大于真实物理尺寸”的
PDF(例如把扫描像素数当作 pt 写进页面框的扫描件)的内存占用与稳定性。这类页面
此前会迫使布局识别渲染出极大的位图、可能耗尽内存;现在 BabelDOC 会把渲染限制在
固定像素预算内,必要时降低渲染 DPI,同时保持布局坐标语义不变。该预算应用于本地
布局识别与扫描件检测。
- Fixed line spacing for mixed Latin/CJK translated text. On lines whose glyph
bounding boxes were unusually short (common in all-Latin lines), the following
CJK line could overlap the previous line; BabelDOC now enforces a font-size
based minimum line advance so translated paragraphs no longer collide.
修复了混合 Latin/CJK 译文的行距。此前在字形包围盒异常偏矮的行(常见于全 Latin
行)上,下一行 CJK 可能与上一行重叠;现在 BabelDOC 按字号施加行进距离的下限,
译文段落不再互相重叠。
Compatibility Notes
- This release is primarily a stability and layout-robustness update for the
v0.6 line. The mixed Latin/CJK line-spacing fix changes the vertical layout of
affected translated pages; those documents will produce different (corrected)
output after upgrading. Layout coordinate semantics are otherwise unchanged.
本版本主要是针对 v0.6 线的稳定性与布局健壮性更新。混合 Latin/CJK 行距修复会
改变受影响译文页的纵向排版,这类文档升级后会生成不同(修正后)的输出;除此之外
布局坐标语义保持不变。
---
Changes
* No changes
Contributors
@awwaawwa
v0.6.32026-06-03
BabelDOC v0.6.3
Highlights
- Fixed translated output for PDFs that use Type3 fonts with a non-default
FontMatrix, a pattern seen in some CJK and scanned-print documents.
Previously, BabelDOC derived text size directly from the raw Type3 Tf value,
which could be orders of magnitude smaller than the intended visual scale;
on affected pages the translated text was near-invisible and could look
blank. After this fix, BabelDOC normalizes Type3 font metrics against the
font's FontMatrix and FontBBox so affected translated text uses the
intended visual scale.
修复了使用非默认 FontMatrix 的 Type3 字体 PDF 的翻译输出(在部分 CJK 及
扫描印刷文档中可见)。此前 BabelDOC 直接从 Type3 的原始 Tf 值推算文字大小,
导致实际字号比视觉尺寸小数个量级,受影响页面中的译文几乎不可见,看起来
可能像空白。修复后,BabelDOC 根据字体的 FontMatrix 和 FontBBox 对 Type3
字号指标归一化,让受影响译文以预期视觉大小排版。
- Hardened the bundled CMap loader against deserialization of attacker-controlled
pickle files. The loader now only deserializes CMap files that match a pinned
manifest of bundled artifacts (allowlist + SHA-256 + size); names referenced
from PDF content can no longer redirect the loader to an external file.
收紧了内置 CMap 加载器,使其只反序列化与固定 manifest(allowlist + SHA-256 + 字节大小)
匹配的内置 CMap 文件。PDF 内容里的名字不能再把加载器指向外部文件。
- Sanitized PDF-controlled image names before writing through the optional
ImageWriter, so an attacker-controlled XObject name can no longer cause a
write outside the intended output directory.
在可选的 ImageWriter 写文件前清理 PDF 控制的图像名,使攻击者可控的 XObject 名不能
再写到目标目录之外。
Security
This release includes a CMap loader fix reported via coordinated
disclosure (GHSA-m8gf-v64p-gfmg,
affecting BabelDOC <= 0.6.2; see the published advisory for details
and exploit prerequisites), together with one additional
defense-in-depth hardening shipped alongside it (the ImageWriter path
sanitization listed above). Also tracked as
CVE-2026-54071.
本版本包含一处通过协调披露收到的 CMap 加载器安全修复(GHSA-m8gf-v64p-gfmg,
影响 BabelDOC <= 0.6.2;完整细节与利用前提见上述链接),并同时附带上文
Highlights 里列出的一项纵深防御加固(ImageWriter 路径清理)。亦记录为
CVE-2026-54071。
Dependency Updates
- Raised the minimum versions of onnx, cryptography, and pymupdf for
dependency hygiene and downstream SCA compatibility. We have not
identified a BabelDOC-specific call path that reaches the corresponding
upstream CVEs.
抬升了 onnx、cryptography 和 pymupdf 的最低版本,用于依赖卫生与下游
SCA 兼容性。我们尚未发现这几个上游 CVE 通过 BabelDOC 可触达的具体调用路径。
Compatibility Notes
- The CMap loader no longer honors the legacy CMAP_PATH environment variable.
Deployments that relied on CMAP_PATH to ship additional CMap files outside
the BabelDOC package will need to vendor those CMaps into the packaged
runtime data or wait for a documented extension point; arbitrary external
CMap search paths are no longer supported.
CMap 加载器不再读取旧的 CMAPPATH 环境变量。曾用 CMAPPATH 注入额外 CMap 文件的
部署需要把所需 CMap 数据合入打包的运行时资源中,或等待后续记录在文档中的扩展点;
本版本之后,不再支持任意的外部 CMap 搜索路径。
- This release is primarily a security and dependency hardening update for the
v0.6 line. It also fixes translated output for PDFs with non-default Type3
FontMatrix fonts; those documents will produce different (corrected)
translation output after upgrading.
本版本主要是针对 v0.6 线的安全与依赖加固版本,同时修复了具有非默认
Type3 FontMatrix 字体的 PDF 的翻译输出;升级后,这类文档会生成不同(修正后)
的翻译结果。
Maintenance Policy
BabelDOC publishes security fixes only in the latest release. We do not
publish maintainer-supported backports for older minor, patch, or release
lines. For security fixes shipped in 0.6.3, the maintainer-supported fixed
version is 0.6.3 or later; downstream distributors may carry their own
patches, but older BabelDOC releases will not receive a separate upstream
backport.
BabelDOC 只在最新发布版本中发布安全修复。我们不向更早的 minor、patch 或
release 线发布维护者支持的回移版本。对于本次 0.6.3 中的安全修复,维护者支持
的修复版本为 0.6.3 及以后;下游发行方可自行打补丁维护更旧版本,但上游不会
为更早的 BabelDOC 版本提供独立的回移发布。
v0.6.22026-05-08
BabelDOC v0.6.2
Highlights
- Fixed a CI lint issue in the public source package.
修复公开源码包中的 CI lint 检查问题。
- Restored Python 3.10 installation compatibility by constraining
onnxruntime to versions that still provide Python 3.10 wheels.
通过约束 onnxruntime 版本,恢复 Python 3.10 环境下的安装兼容性。
Compatibility Notes
- This release is a focused packaging and CI compatibility follow-up to
v0.6.1. It does not change the recursion hardening behavior introduced in
v0.6.1.
本版本是 v0.6.1 之后的打包与 CI 兼容性修复版本,不改变 v0.6.1 引入的递归防护行为。
---
Changes
* No changes
Contributors
@awwaawwa
v0.6.12026-05-08
BabelDOC v0.6.1
Highlights
- Fixed recursion-depth failures that could occur while translating PDFs with
deeply linked paragraph context.
修复了翻译某些 PDF 时,由深层段落上下文触发的递归深度失败。
- Added defensive depth and cycle guards for several PDF parsing paths,
including Form XObject execution, font resource projection, token parsing,
object parsing, and token serialization.
为多个 PDF 解析路径增加了深度与环检测保护,包括 Form XObject 执行、字体资源投影、
token 解析、object 解析和 token 序列化。
- Reduced risky deep-copy behavior in translation context handling and formula
relocation, improving robustness on complex PDF object graphs.
减少了翻译上下文和公式重排中的高风险深拷贝行为,提升复杂 PDF 对象图上的稳健性。
Reliability
- Title context used by the translator now stores a compact immutable snapshot
instead of copying the full paragraph object graph.
译文上下文中的标题信息现在保存紧凑的不可变快照,而不是复制完整段落对象图。
- Form XObject expansion now stops on recursive or excessively deep structures
instead of exhausting the Python call stack.
Form XObject 展开遇到递归或过深结构时会停止,而不是耗尽 Python 调用栈。
- Deeply nested PDF token and object structures now fail with controlled parser
errors instead of uncaught recursion errors.
深层嵌套的 PDF token 与 object 结构现在会以受控解析错误失败,而不是抛出未控制的递归错误。
- Formula relocation now rebuilds the small objects it needs to move instead of
deep-copying full rendering state.
公式重排现在只重建需要移动的小对象,不再深拷贝完整渲染状态。
Compatibility Notes
- This release is intended as a focused reliability update for the v0.6 parser
rewrite line.
本版本是针对 v0.6 解析器重写线的可靠性修复版本。
- Extremely recursive or malformed PDF structures may now have only the unsafe
nested portion skipped or reported as a parser error.
对极端递归或损坏的 PDF 结构,BabelDOC 现在可能跳过不安全的嵌套部分,或报告解析错误。
---
Changes
* No changes
Contributors
@awwaawwa
v0.6.02026-05-07
BabelDOC v0.6.0
Highlights
- BabelDOC's translation pipeline now uses a substantially rewritten PDF parser.
This is a large internal change aimed at making PDF translation more reliable
across complex real-world files.
BabelDOC 的翻译主链路现在使用了大幅重写后的 PDF 解析器。这是一次较大的内部改造,
目标是在复杂真实 PDF 上提升翻译可靠性。
- PDF reconstruction is more robust for documents that rely on advanced PDF
drawing features such as graphics state, Form XObjects, clipping paths, soft
masks, shadings, and inline images.
对依赖复杂 PDF 绘制特性的文档,PDF 重建现在更加稳健,包括图形状态、Form XObject、
裁剪路径、软蒙版、渐变填充和内联图片等场景。
- Several fixes in this release reduce invalid generated PDF streams and missing
resource references in intermediate and final outputs.
本版本修复了若干会导致中间或最终输出 PDF 流无效、资源引用缺失的问题。
PDF Reliability
- Replaced the parser used by the main translation flow with the rewritten
parser implementation.
翻译主流程使用的 PDF 解析器已切换到重写后的实现。
- Improved serialization of PDF tokens when BabelDOC regenerates content
streams, including PDF names, keywords, strings, arrays, dictionaries,
indirect references, booleans, and inline-image parameters.
BabelDOC 重新生成 PDF 内容流时,对 PDF token 的序列化更稳健,包括名称、关键字、
字符串、数组、字典、间接引用、布尔值和内联图片参数。
- Improved resource handling when rewriting page and Form XObject streams,
especially for ExtGState and shading resources.
重写页面和 Form XObject 内容流时,资源处理更加完整,尤其是 ExtGState 和 Shading
资源。
- Improved preservation of clipping and graphics-state behavior around images,
Form XObjects, shading paints, and soft masks.
对图片、Form XObject、渐变绘制和软蒙版周围的裁剪与图形状态行为保留得更好。
Compatibility Notes
- The previous parser remains available for explicit compatibility tooling, but
normal translation now uses the rewritten parser.
旧解析器仍保留给显式兼容工具使用;普通翻译流程现在使用重写后的解析器。
- table_model is deprecated and ignored with a warning; BabelDOC no longer
loads RapidOCR table-text detection resources at runtime.
table_model 已废弃,传入时会被忽略并给出警告;BabelDOC 运行时不再加载 RapidOCR
表格文本检测资源。
---
Changes
* No changes
Contributors
@awwaawwa
v0.5.242026-03-26
Changes
- feat: re-enable CoreML acceleration on macOS with static input shapes @garetneda-gif (#573)
- fix: add UTF-8 BOM to CSV for Excel compatibility @MoshiLL (#575)
Contributors
@MoshiLL, @awwaawwa and @garetneda-gif
v0.5.232026-01-16
Changes
- Initial support for Type 3 fonts \& improved PDF compatibility @awwaawwa (#559)
- Add a (off-by-default) option to disable same input output fallback, update logging format @qazxcdswe123 (#555)
- Revert "fix(layout): use "relative font size" instead of "absolute 1pt"." @awwaawwa (#550)
- fix(layout): use "relative font size" instead of "absolute 1pt". @xiaobeicn (#549)
- change issue template @awwaawwa (#546)
- chore: rename deps python-levenshtein to Levenshtein @ryota2357 (#542)
Contributors
@awwaawwa, @qazxcdswe123, @ryota2357, @xiaobeicn and chenyuning.neil
v0.5.222025-12-01
Changes
- chore: rename deps python-levenshtein to Levenshtein @ryota2357 (#542)
- Refactor argument parsing in PDF document creator @awwaawwa (#545)
- Update README and contributor reward documentation for clarity and consistency @awwaawwa (#533)
Contributors
@awwaawwa and @ryota2357