BabelDOC: a PDF translation library for scientific papers, not a document converter

The problem BabelDOC solves: translated PDFs that still look like papers

Machine translation of a PDF is easy until the output has to remain a PDF. Plain text extraction throws away columns, figures, formulas and tables, so a translated paper stops being readable as a paper. BabelDOC is described in its README as a "PDF scientific paper translation and bilingual comparison library", which names both halves of the job: translating the text and producing a bilingual document where the original and the translation can be compared.

The intended audience is narrow and stated plainly. The README says the project is "mainly designed to be embedded into other programs, but can also be used directly for simple translation tasks". The examples directory reinforces this: examples/basic.xml, examples/code-figure.xml, examples/complex.xml, examples/formular.xml and examples/table.xml are test inputs for specific layout problems, not tutorials for end users. If you are building a tool that ingests papers, BabelDOC is a component. If you want a translated PDF today, it is the wrong layer.

How BabelDOC processes a PDF: parsing, layout, then an OpenAI-compatible model

The dependency list in pyproject.toml is the clearest description of the pipeline. PyMuPDF handles PDF reading and writing, pdfminer-six is present (commented out but listed as a dependency line), and the layout side pulls in opencv-python-headless, scikit-image, scipy, scikit-learn and rtree. Text and font handling need freetype-py, uharfbuzz, Levenshtein and tiktoken. Translation goes through the openai package, while huggingface-hub and onnxruntime suggest local model assets are downloaded and run through ONNX.

That mix tells you what kind of program this is. It is not a thin wrapper around a translation API. A large part of the code exists to decide which text belongs to which paragraph, to keep formulas and tables intact, and to re-render translated glyphs into the original font metrics. The README exposes a few of these decisions as flags: --skip-clean skips a PDF cleaning step, --disable-rich-text-translate turns off rich text translation, and --enhance-compatibility is documented as equivalent to --skip-clean --dual-translate-first --disable-rich-text-translate. The existence of that combined flag is an admission that the default path does not handle every PDF.

Language coverage is the other constraint. The CLI defaults are --lang-in en and --lang-out zh, and the README states that the project "mainly focuses on English-to-Chinese translation, and other scenarios have not been tested yet". A 2025.3.1 update added basic English target language support, described as mainly minimizing line breaks within words matching [0-9A-Za-z]+. The project also links an issue asking for help collecting word regular expressions for more languages, which is a direct signal that non-English, non-Chinese targets are unfinished.

Installing BabelDOC from PyPI and translating a first PDF

The README recommends installing through the tool feature of uv rather than pip. After installing uv and putting it on PATH, this installs the CLI and prints its help output:

uv tool install --python 3.12 BabelDOC

babeldoc --help

Translation is driven by OpenAI-compatible flags. The README example passes a model, a base URL and an API key, then one or more PDFs:

babeldoc --openai --openai-model "gpt-4o-mini" --openai-base-url "https://api.openai.com/v1" --openai-api-key "your-api-key-here"  --files example.pdf

Because the base URL is configurable, the same flags can point at any endpoint that speaks the OpenAI API. Repeat --files for more than one document. Output goes to the working directory; the README does not document an output path flag, so run it somewhere you are happy to have files written.

If you want to modify the code, the source install uses uv for the virtual environment as well:

git clone https://github.com/funstory-ai/BabelDOC

cd BabelDOC

uv run babeldoc --help

After that, prefix the same command with uv run. The README notes that absolute paths are recommended for input files. Two options are worth knowing before you translate anything long: --pages accepts a page range such as "1,2,1-,-3,3-5", and --use-alternating-pages-dual switches the dual PDF from grouped pages to alternating original and translated pages. The README does not document resume behaviour, so a failed long job is a restart.

The CLI is a debugging tool, and the README says so

This is the most important limitation and it comes from the project itself. Under Advanced Options the README states: "This CLI is mainly for debugging purposes. Although end users can use this CLI to translate files, we do not provide any technical support for this purpose." It then directs end users to the hosted Immersive Translate BabelDOC service, which the README describes as a beta with 1000 free pages per month, and directs self-deployment users to PDFMathTranslate-next.

Read that as a support boundary rather than a technical one. The command works, but if a particular paper produces broken typesetting, the maintainers have pre-declared that the CLI path is not a supported product surface. The README also warns that options not listed in the documentation are "debugging option[s] for maintainers" and asks users not to touch them. Combined with the admission that the project "mainly focuses on English-to-Chinese translation", the realistic failure modes are non-English target languages, unusual PDF structures, and anything that needs an option the documentation does not list.

There is a second boundary: pyproject.toml sets requires-python to ">=3.10,<3.14". The upper bound is real. If your environment is on a newer Python, the package metadata will refuse the install, and the README does not discuss workarounds.

BabelDOC compared with PDFMathTranslate-next and the hosted service

The difference between BabelDOC and PDFMathTranslate-next is packaging, not purpose. The same project points self-deployment users at PDFMathTranslate-next for a WebUI and more translation services, and there is a related search phrase, "babeldoc pdfmathtranslate", that reflects exactly this confusion. BabelDOC is the library; PDFMathTranslate-next is the application built around it. If your goal is a web interface where someone uploads a paper and downloads a translation, the README's own recommendation is PDFMathTranslate-next, not BabelDOC.

The hosted Immersive Translate BabelDOC service is the third option, and it is the one the README recommends for people who are not writing code. It is described as a beta with a free quota, and the README defers quota details to the FAQ on that page. The trade-off is the usual one: no API key management and no local install, but your documents leave your machine and you depend on someone else's uptime and model choice.

BabelDOC's own argument for existing is embeddability. If you need translation inside a Python pipeline, with your own model endpoint and your own storage, neither the hosted service nor a WebUI gives you that.

Licence and maintenance: AGPL-3.0 with a recent release cadence

pyproject.toml declares license = "AGPL-3.0" and the repository carries a LICENSE file. AGPL-3.0 is a strong copyleft licence with a network clause, which matters for a library explicitly designed to be embedded into other programs. If you run a modified BabelDOC as part of a service that users interact with over a network, the licence's source-availability obligation is the question to take to your own legal review. This is a description of the licence text, not legal advice.

The maintenance picture from the repository metadata is current. The last push was on 2026-08-05, and the most recent tagged release is v0.6.4 from 2026-07-16, following v0.6.3 on 2026-06-03 and v0.6.2 on 2026-05-08. That is a release roughly every one to two months across that window. The repository is not archived. The version in pyproject.toml matches the latest tag, which suggests releases are cut from the main branch rather than maintained on separate branches.

Upgrade cost is dominated by the Python version window and the dependency set. The pinned range of onnxruntime differs by Python version, and optional extras exist for GPU acceleration: directml, cuda and memray. Upgrading means re-resolving a dependency tree that includes PyMuPDF, opencv-python-headless and hyperscan, any of which can break a build on a new platform.

Editorial conclusion

BabelDOC fits teams that need PDF translation inside a Python program and are willing to read the source when the CLI documentation runs out; it does not fit readers who just want a translated paper, since the README sends them to the hosted service or to PDFMathTranslate-next. Before adopting it, check three things in the repository: the AGPL-3.0 LICENSE, the requires-python range of >=3.10,<3.14 in pyproject.toml, and whether the language pair you need is covered by the supported languages page.

Frequently asked questions

Official sources

1. funstory-ai/BabelDOC on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases