PDFMathTranslate preserves page structure while translating text
PDFMathTranslate tackles a specific failure of ordinary copy-and-paste translation: scientific PDFs mix prose with formulas, charts, annotations, columns, and positioned text. The tool produces translated and bilingual PDFs while trying to keep that structure recognizable. Its README offers a CLI, browser interface, Docker image, Python API, HTTP API, Zotero connection, and MCP modes. Translation can be delegated to multiple services rather than tied to one model vendor.
The measured repository is modest beside a full office suite: 494 files, about 16,711 lines of source, and a 24.8 MB checkout at commit 3835ce9. Installation tells a different story, expanding to 1,147 MB after 141 packages. The extra weight supports layout detection, PDF parsing, fonts, model clients, and a web interface. Anyone embedding the library should decide whether the whole application belongs inside their process or behind its HTTP service.
The basic workflow is clear. Python 3.11 or 3.12 users install pdf2zh, run it against a document, and receive mono-language and bilingual outputs. A browser UI listens on port 7860, and container images remove much of the local Python setup. The layout model may need to download on first use; the README even documents a mirror environment variable for regions where that download fails.
Translation quality still requires page-by-page review
Preserved layout is valuable only when the output remains correct. Scientific papers punish small mistakes: a missing minus sign, changed variable, broken subscript, or reversed sentence direction can alter the argument. An open issue reports formula symbols becoming disordered, while another asks for correct Persian and Arabic shaping and direction. A separate report says Chinese-to-English translation failed most of the time for that user's documents. These are concrete reasons to retain the source page beside every translated page.
Provider choice adds another review layer. Google is the documented default, while advanced configuration covers other services and custom prompts. Hosted APIs can send document text outside your infrastructure and create usage charges. Local providers change that privacy boundary but require model hosting and enough compute. PDFMathTranslate provides the routing; your team still owns vendor terms, credentials, cost limits, retention policy, and evaluation of the chosen model's language pair.
For casual reading, imperfect output may still save time by exposing the structure and rough argument of a paper. For a citation, contract, clinical instruction, or publishable translation, the PDF should be treated as a draft. The project's format preservation does not certify terminology, equations, names, or conclusions.
What happened when we ran it
Our sandbox install succeeded in 66 seconds, pulling 141 packages and using 1,147 MB on disk. The build completed in 13 seconds. We used a fresh unprivileged Debian container with 3 CPUs, 8 GB of RAM, Python 3.12, no secrets, and commit 3835ce9. The repository included a Dockerfile, a Compose file, 7 CI workflow files, and a tests directory.
The test command failed after 24 seconds. pytest reported 58 passes, 3 failures, 1 skipped test, and 5 collection or setup errors out of 66. All 3 failures were legacy-kernel translation tests raising AttributeError because the pdf2zh module had no high_level attribute. Five files failed during collection or setup. The log tail named those files but did not show one cause shared by them, so we will not invent one.
pip-audit found 45 known vulnerabilities in the installed environment. That count does not say each finding is reachable during PDF translation, but it is too large to ignore in a service that accepts uploaded documents and can expose a web or HTTP interface. Pinning, scanning, network isolation, upload limits, and timely dependency updates belong in any deployment review.
The legacy and v2 paths are still intertwined
The README says the 2.0 implementation moved to PDFMathTranslate-next, while this project remains the stable original. It also added an experimental --mode precise path that uses the v2 translation kernel through a submodule and isolated environment. The document calls that newer fork better at marginal cases, cross-column and cross-page consistency, and scaling, but also says it is for development and is not designed for community contributions.
That split explains why the simple product choice has become less simple. A user can stay on the legacy path, enable an experimental bridge, or work directly with the newer BabelDOC-related engine. Our 3 failed tests specifically touched legacy-kernel translation, so the boundary is not merely organizational. Evaluate the exact mode and version you intend to run, then keep it pinned until your document set passes visual comparison.
Active code does not erase the security backlog
GitHub recorded the last push on 2026-08-26, and recent issues and pull requests covered translation providers, documentation sync, right-to-left text, editor setup, and model defaults. The repository showed 147 open issues and PRs. Its latest GitHub release was v1.9.11 from 2025-07-11, but source work continued afterward, so the tag date alone does not support an abandonment claim.
PDFMathTranslate earns a trial because it addresses the part generic translators discard: the page. Our run also gives buyers hard limits. A 1,147 MB install, 45 audit findings, and 8 unsuccessful test entries call for isolation and human checking. The right use is assisted reading and supervised document production, with the original PDF always available for comparison.