^{Special thanks to:}

Warp, built for coding with multiple AI agents
^{Available for macOS, Linux and Windows}

English | [简体中文](https://github.com/PDFMathTranslate/PDFMathTranslate/blob/HEAD/docs/README_zh-CN.md) | [繁體中文](https://github.com/PDFMathTranslate/PDFMathTranslate/blob/HEAD/docs/README_zh-TW.md) | [日本語](https://github.com/PDFMathTranslate/PDFMathTranslate/blob/HEAD/docs/README_ja-JP.md) | [한국어](https://github.com/PDFMathTranslate/PDFMathTranslate/blob/HEAD/docs/README_ko-KR.md)

PDFMathTranslate

1. What does this do?

Scientific PDF document translation preserving layouts.

• 📊 Preserve formulas, charts, table of contents, and annotations.
• 🌐 Support multiple languages, and diverse translation services.
• 🤖 Provides commandline tool, interactive user interface, and Docker

2. Recent Updates

• [October 3, 2026] Translated PDFs automatically add spaces between adjacent CJK and Latin letters, including accented letters, in normal and --ultrafast modes.

• [October 2, 2026] Added the --ultrafast CLI mode for native-text PDFs. It uses pdf-inspector text positions for heuristic layout and skips ONNX layout and OCR. (by @reycn)

• [September 8, 2026] Experimental OCR support, with paragraph regrouping and adaptive typesetting. (by @reycn)
• [March 23, 2026] Experimental support for v2.0 translation kernel using isolated environment (--mode precise). (by @reycn)
• [March 22, 2026] Supporting MiniMax (PR by @octo-patch)
• [March 22, 2026] Fixing OpenAI-related issues (PR by @samqin123)
• [March 22, 2026] Fixing HTTP-related issues (PR by @soukouki)
• [March 22, 2026] Faster model loading on mac and OONX platforms, GUI starting-up, version printing, and continuous integration.(by @reycn)
• [May 9, 2025] pdf2zh 2.0 Preview Version #586: The Windows ZIP file and Docker image are now available.

[!NOTE]

2.0 Moved to a new repository under the organization: PDFMathTranslate/PDFMathTranslate-next

Version 2.0 official release has been published.

3. Use 🌟

3.1 Online Service 🌟

You can try our application out using either of the following demos:

• Public free service online without installation (recommended).
• Immersive Translate - BabelDOC Free usage quota is available; please refer to the FAQ section on the page for details. (recommended)
• Demo hosted on HuggingFace
• Demo hosted on ModelScope without installation.

Note that the computing resources of the demo are limited, so please avoid abusing them.

3.2 Local Installation

For different use cases, we provide distinct methods to use our program:

3.3.3 Python: Graphic user interface

1. Python installed (3.11 <= version <= 3.12) 2. Install our package: ```bash pip install pdf2zh ``` 3. Start using in browser: ```bash pdf2zh -i ``` 4. If your browser has not been started automatically, goto ```bash http://localhost:7860/ ``` See [documentation for GUI](https://github.com/PDFMathTranslate/PDFMathTranslate/blob/HEAD/./docs/README_GUI.md) for more details.

3.2.6 Docker: Containerized Deployment

1. Pull and run: ```bash docker pull byaidu/pdf2zh docker run -d -p 7860:7860 byaidu/pdf2zh ``` 2. Open in browser: ``` http://localhost:7860/ ``` For docker deployment on cloud service:

> [!TIP] > > - If you cannot access Docker Hub, please try the image on [GitHub Container Registry](https://github.com/Byaidu/PDFMathTranslate/pkgs/container/pdfmathtranslate). > ```bash > docker pull ghcr.io/byaidu/pdfmathtranslate > docker run -d -p 7860:7860 ghcr.io/byaidu/pdfmathtranslate > ```

4. Technical Details

Experimental automatic OCR (fast mode)

Fast mode automatically runs local OCR on selected image-only pages before translation. Native text, existing OCR layers, and blank pages are skipped; the original pages in dual output remain unchanged. Install with pip install 'pdf2zh[ocr]' (or pip install -e '.[ocr]' from this checkout). The first scanned page downloads the requested language data from Tesseract's tessdata_fast 4.1.0 release into ~/.cache/pdf2zh/tessdata/4.1.0; subsequent runs reuse it offline. Native-text PDFs do not trigger downloads. OCR uses the input language; PDF2ZH_OCR_LANGUAGE=eng+deu overrides it with Tesseract language codes. Set TESSDATA_PREFIX to use your own data without automatic downloads.

PyMuPDF supplies the OCR engine; the optional extra adds Pooch for cached downloads. No separate Tesseract executable is required. OCR words are regrouped into paragraphs within detected layout regions before translation, with wrapped lines and soft hyphens joined. Translated paragraphs start at the median source font size and shrink to fit their original boxes; detected figures, tables, and standalone formulas remain untouched. The initial implementation targets white-background scans: partial scans on pages that already contain text are skipped, and handwritten text or inline equations may be recognized incorrectly. Precise mode is unchanged.

Ultrafast mode

Install the optional pdf-inspector>=1.25.2,<2 dependency with pip install 'pdf2zh[ultrafast]', then run:

pdf2zh example.pdf --ultrafast

--ultrafast uses native PDF text positions from pdf-inspector for heuristic layout. It skips ONNX layout and OCR; pages without native text are preserved without OCR. Its heuristic text grouping retains the usual font and character formula safeguards. It is best suited to PDFs that already contain native text; use normal mode for complex tables or formulas. It is available only in fast CLI mode and cannot be combined with --mode precise, --babeldoc, server or GUI modes, or --onnx. It automatically skips font subsetting, so its output PDFs are larger, while still using BabelDOC font assets as needed. With --ignore-cache, it bypasses both translation-cache reads and writes; normal mode keeps its existing --ignore-cache behavior. Ultrafast uses a shared whole-document paragraph worker pool with 16 workers by default and submits individual paragraph requests; -t overrides this value, while normal mode keeps its default of 4. [ultrafast perf] INFO logs report stage and per-page timings. page_scan is the paragraph-submission scan; translation is the elapsed wait for the whole-document pool to drain, including API retries, so it is not a sum of per-page waits. paragraph_parse covers both passes, typesetting runs after translation completes, and layout_extract is reported separately before font setup. page_processing includes nested layout_mask, paragraph_parse, translation, and typesetting timings, so do not sum the nested values again. This path does not import ONNX or OpenCV.

4.1 Advanced options

Execute the translation command in the command line to generate the translated document example-mono.pdf and the bilingual document example-dual.pdf in the current working directory. Use Google as the default translation service. More support translation services can find HERE.

In the following table, we list all advanced options for reference:

For detailed explanations, please refer to our document about Advanced Usage for a full list of each option.

4.2 Downstream Development

For downstream applications, please refer to our document about API Details for further information about:

• Python API, how to use the program in other Python programs
• HTTP API, how to communicate with a server with the program installed

4.3 Differences between two major forks

• Byaidu/PDFMathTranslate: The present and the original project for stable release.

• PDFMathTranslate/PDFMathTranslate-next: A fork with web-ui and additional features. This fork handles a large number of marginal cases, improves PDF compatibility, and optimizes cross-column and cross-page semantic consistency, dynamic scaling, and dynamic scaling consistency, among many other translation quality improvements. However, this fork is intended solely for development and does not address compatibility issues and is not designed for community-contributions.

5. Project Information

5.1 Citation

This work has been accepted by the Proceedings of the 2025 Conference on Empirical Methods in Natural Language Processing: System Demonstrations (EMNLP 2025).

Citation:

@inproceedings{ouyang-etal-2025-pdfmathtranslate,
        title = "{PDFM}ath{T}ranslate: Scientific Document Translation Preserving Layouts",
        author = "Ouyang, Rongxin  and
          Chu, Chang  and
          Xin, Zhikuang  and
          Ma, Xiangyao",
        editor = {Habernal, Ivan  and
          Schulam, Peter  and
          Tiedemann, J{\"o}rg},
        booktitle = "Proceedings of the 2025 Conference on Empirical Methods in Natural Language Processing: System Demonstrations",
        month = nov,
        year = "2025",
        address = "Suzhou, China",
        publisher = "Association for Computational Linguistics",
        url = "https://aclanthology.org/2025.emnlp-demos.71/",
        pages = "918--924",
        ISBN = "979-8-89176-334-0",
        abstract = "Language barriers in scientific documents hinder the diffusion and development of science and technologies. However, prior efforts in translating such documents largely overlooked the information in layouts. To bridge the gap, we introduce PDFMathTranslate, the world{'}s first open-source software for translating scientific documents while preserving layouts. Leveraging the most recent advances in large language models and precise layout detection, we contribute to the community with key improvements in precision, flexibility, and efficiency. The work is open-sourced at https://github.com/byaidu/pdfmathtranslate with more than 222k downloads."
    }

5.2 Acknowledgement

• Immersive Translation sponsors monthly Pro membership redemption codes for active contributors to this project, see details at: CONTRIBUTOR_REWARD.md

• New backend: BabelDOC

• Document merging: PyMuPDF

• Document parsing: Pdfminer.six

• Document extraction: MinerU

• Document Preview: Gradio PDF

• Multi-threaded translation: MathTranslate

• Layout parsing: DocLayout-YOLO

• Document standard: PDF Explained, PDF Cheat Sheets

• Multilingual Font: Go Noto Universal

5.3 Contributors

For details on how to contribute, please consult the Contribution Guide.

5.4 Star History