English | 简体中文 | 繁體中文 | 日本語 | 한국어

PDFMathTranslate

1. What is PDFMathTranslate?

Scientific PDF translation that preserves formulas, charts, tables of contents and annotations.

This repository is the unified entry point of the PDFMathTranslate ecosystem: one package with a command line tool, a Python API and an MCP server, running either of two translation kernels. Apps and plugins build on it instead of forking it.

2. Pick the right tool

I want to…	Use
Read and translate papers in a desktop or mobile app	PDFMathReader — the official client for macOS, Windows, Linux and iOS
Translate online or in the browser, without installing anything	Immersive Translate · BabelDOC — free monthly quota
Translate inside Zotero	zotero-pdf2zh
Let an AI agent (Claude, DeepSeek Harness, …) translate PDFs	pdf2zh --mcp from this repository — see MCP
Use the command line, call it from Python, or self-host	This repository — read on

How the projects fit together

BabelDOC (layout engine, by funstory.ai)         pdf2zh v1 pipeline
                 \                               /
          babeldoc kernel (optional)        legacy kernel (default)
                          \                   /
         PDFMathTranslate: pdf2zh CLI · Python API · MCP   <- this repository
                 |                 |                  |
          PDFMathReader      zotero-pdf2zh     AI agents / dsh plugins

3. Install and use

Requires Python 3.11 to 3.14; the BabelDOC kernel needs 3.11 to 3.13.

pip install pdf2zh                # everything below
pdf2zh document.pdf               # writes document-mono.pdf and document-dual.pdf

One install has the command line, the Python API, the web UI (pdf2zh -i), the MCP server (pdf2zh --mcp), the plugin worker (pdf2zh --worker), both kernels (BabelDOC on Python 3.11 to 3.13), ultrafast mode and automatic OCR. The one extra is pdf2zh[argostranslate], for offline translation. For an HTTP service, see the example server.

Docker images with the web UI: docker run -d -p 7860:7860 byaidu/pdf2zh, also on GitHub Container Registry.

Network issues when downloading models

Both kernels download a layout model from Hugging Face on first use. If that fails in your region, set a mirror:

export HF_ENDPOINT=https://hf-mirror.com

See the FAQ for other problems.

3.1 Kernels

Kernel	Install	Best for
legacy (default)	included	The pdf2zh v1 pipeline: lighter, runs on Python 3.14; ultrafast mode, OCR and custom ONNX models
babeldoc	included	Higher layout fidelity, powered by BabelDOC; Python 3.11 to 3.13

--kernel auto (the default) uses legacy, and BabelDOC only when legacy is unavailable; pass --kernel babeldoc to use BabelDOC. --mode fast / --mode precise and --babeldoc still work as aliases. See Choose a kernel.

3.2 Command line

pdf2zh paper.pdf -li en -lo ja -s deepl          # source/target language and service
pdf2zh paper.pdf -s openai:gpt-4o-mini -p 1-3    # service:model, partial translation
pdf2zh paper.pdf --kernel legacy --ultrafast     # legacy kernel, native-text fast path
pdf2zh --dir ./papers -o ./out                   # batch translate a folder

Option	Function
files	Local files or URLs
-k, --kernel	auto, babeldoc or legacy
-li, -lo	Source and target language
-s	Translation service, optionally service:model
-p	Pages, e.g. 1,3-5
-o	Output directory
-t	Threads
-f, -c	Formula font / character regex
--prompt	Custom prompt
--config	Configuration file
--ignore-cache	Bypass the translation cache
--ultrafast, --onnx, --skip-subset-fonts	Legacy kernel options
-i	Web UI (legacy kernel)
--mcp, --sse	MCP server
--json	Print one JSON line with the output paths on stdout, for programs that run pdf2zh
--worker	Stay running and take JSON translation requests on stdin, for plugins (protocol)

All options are described in Advanced Usage.

3.3 Python API

from pdf2zh import TranslateRequest, get_kernel

kernel = get_kernel()                     # "auto", "babeldoc" or "legacy"
request = TranslateRequest(files=["paper.pdf"], lang_in="en", lang_out="zh", service="google")
for result in kernel.translate(request):  # or: await kernel.translate_async(request)
    print(result.mono_pdf, result.dual_pdf)

pdf2zh.translate and pdf2zh.translate_stream remain available for the legacy kernel; see API Details.

3.4 MCP

Register pdf2zh in any MCP host. The host starts it on demand; nothing has to be kept running:

{
  "mcpServers": {
    "pdf2zh": {
      "command": "uvx",
      "args": ["pdf2zh", "--mcp"]
    }
  }
}

Tools: translate_pdf(file, lang_in, lang_out, service, kernel, pages, output_dir), list_kernels() and open_pdf_reader(file, ...). In hosts that support MCP Apps (Claude, ChatGPT), open_pdf_reader shows the PDF in the conversation and translates pages as you scroll. Details in MCP.

3.5 Build on pdf2zh

examples/ has working starting points: a web frontend and server with REST, live progress and remote MCP, and integrations for Claude, ChatGPT, Zotero and DeepSeek Harness.

4. Recent updates

• [October 2026] PDFMathTranslate becomes the unified entry point: BabelDOC runs in-process as an optional kernel next to the default legacy kernel (the v1 pipeline), the MCP server gains kernel, service and page selection, and the GUI and HTTP backend move to extras. The pdf2zh_next submodule is removed.
• [October 3, 2026] Spaces between adjacent CJK and Latin letters in the legacy kernel.
• [October 2, 2026] --ultrafast mode for native-text PDFs (by @reycn).
• [September 8, 2026] Experimental OCR with paragraph regrouping and adaptive typesetting (by @reycn).

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