How to Translate Academic PDFs in One Command Without Losing Formulas & Layout

Read Papers Without Manual Screenshots: Translate Full PDFs in One Command While Keeping Formulas & Layout

Recently, my advisor handed me a stack of English papers to review over the weekend for our group meeting. Opening a 12-page paper, I saw it packed with formulas, tables, and figures. Using standard translation tools mangled the equations; screenshot-based translation was painfully slow.

Then I found PDFMathTranslate on GitHub's Trending list (over 36k stars today). I gave it a shot and was genuinely impressed: one command translates the entire paper, keeps formulas, tables, and layout perfectly intact, and generates a bilingual Chinese-English version.

In this tutorial, I’ll walk you through setting up and using this tool from scratch. By the end, you’ll be able to translate your own research papers effortlessly.

Prerequisites

Before starting, make sure you meet the following requirements:

• Python 3.11 - 3.12 (The project strictly requires these versions. Avoid 3.13+ for now.)
• Basic familiarity with terminal/command-line operations.
• A PDF file to translate (English academic papers work best).
• Network Environment: The tool relies on AI models downloaded from HuggingFace. Users in certain regions may encounter network issues, which I'll address later.

No machine learning knowledge or GPU is required—it runs perfectly on CPU. Under the hood, it uses DocLayout-YOLO for layout detection and LLMs for translation. In short: it identifies text, formulas, and images in the PDF, translates only the text, and leaves everything else exactly as is.

Step 1: Install pdf2zh

The project recommends using uv for faster installation, but standard pip works too. Choose whichever you prefer.

Option 1: Install via uv (Recommended)

uv is an extremely fast Python package manager. Install it first, then use it to install pdf2zh:

## Install uv
pip install uv

## Use uv to install pdf2zh (handles Python version dependencies automatically)
uv tool install --python 3.12 pdf2zh

Option 2: Install via pip

pip install pdf2zh

Why use uv? In my tests, uv is over 10x faster than pip and automatically manages virtual environments, preventing dependency conflicts. If uv downloads slowly on your network, pip works just fine.

Verify the installation:

pdf2zh --version

If it prints a version number, you're all set.

Step 2: Translate a Paper with One Command

Once installed, using it is incredibly simple. Place the PDF you want to translate in your current directory and run:

pdf2zh your-paper.pdf

It defaults to Google Translate. After execution, two files will appear in your current directory:

• your-paper-mono.pdf – Monolingual translated version (English to Chinese)
• your-paper-dual.pdf – Bilingual side-by-side version (Highly recommended)

The process is fully automated. A ~10-page paper usually takes 1-3 minutes.

Why keep the bilingual version? For research, side-by-side translation is invaluable. Original text on the left, translated text on the right makes terminology mapping obvious and is perfect for screenshots in literature reviews.

Real-World Example: Translate an arXiv Paper with DeepL

Translating local files is fine, but let's do a complete workflow: download from arXiv → translate with DeepL → specify output directory → translate only the first 3 pages for a quick preview.

Scenario

I want to read a new LLM paper but don't want to commit to the full text yet. I'll translate just the first 3 pages to check the abstract and introduction. I also prefer DeepL over Google Translate for academic accuracy.

Steps

## 1. Download the paper using wget (replace with your target paper URL)
wget https://arxiv.org/pdf/2401.00001.pdf -O paper.pdf

## 2. Configure DeepL translation + translate pages 1-3 + set output directory
pdf2zh paper.pdf \
  -p 1-3 \
  -s deepl \
  -li en \
  -lo zh \
  -o ./translation-output \
  -t 4

Here’s a breakdown of each parameter:

Note: DeepL requires an API Key. The tool will prompt you for it, or you can set it via an environment variable:

export DEEPL_AUTH_KEY=your_deepl_api_key

After execution, check the ./translation-output folder for the translated bilingual PDF.

Advanced: Other Translation Backends & CLI Tips

Supported Translation Services

The project supports multiple translation backends. Switch as needed:

• Google (Default, free, no API key required)
• DeepL (High quality, requires API key)
• OpenAI (Requires endpoint and API key)
• Ollama (Locally deployed, completely free and private)
• MiniMax, Caiyun, etc.

To switch services, just change the -s parameter. For example, using local Ollama:

pdf2zh paper.pdf -s ollama -li en -lo zh

Why recommend Ollama? If your papers contain sensitive data (e.g., internal corporate docs), local Ollama ensures your data never leaves your machine. Just make sure you have Ollama installed and a translation model pulled beforehand.

Batch Translate an Entire Folder

If you have 20 papers to translate, no need to run commands one by one:

pdf2zh --dir /path/to/papers/ -o /path/to/output/

The tool will iterate through all PDFs in the directory. Run it over the weekend, and your translations will be ready on Monday.

Launch Web GUI (For Non-Technical Colleagues)

pdf2zh -i

This opens a browser at http://localhost:7860/ with a visual interface. You can drag-and-drop PDFs, choose translation services, and preview results. Perfect for sharing with non-technical team members.

Troubleshooting / Common Pitfalls

1. Installation succeeds but running fails: AI model download error

This is the most common issue for users in regions with restricted network access. The tool needs to download the DocLayout-YOLO model, but HuggingFace can be unstable.

Solution: Set a HuggingFace mirror endpoint:

## Linux / macOS
export HF_ENDPOINT=https://hf-mirror.com

## Windows CMD
set HF_ENDPOINT=https://hf-mirror.com

## Windows PowerShell
$env:HF_ENDPOINT = "https://hf-mirror.com"

Re-run the translation command. The model will download from the Chinese mirror.

2. Translated layout looks messy

The default mode is fast, prioritizing speed. If your paper has complex formatting (e.g., two-column layouts, cross-page tables), try compatibility mode:

pdf2zh paper.pdf --compatible

If it still struggles, the repo has an experimental v2 engine (requires additional setup). Check the GitHub repo for updates.

3. Python version mismatch

The project requires Python 3.11 or 3.12. Verify with python --version. If your version is off, use uv to manage it seamlessly:

uv tool install --python 3.12 pdf2zh

uv will automatically handle the correct Python version download.

Summary

Here’s what we covered:

1. Installation: pip install pdf2zh (or use uv for speed)
2. Basic Translation: pdf2zh paper.pdf (one command)
3. Service Configuration: Switch backends with -s (DeepL, Ollama, OpenAI, etc.)
4. Real-World Workflow: arXiv download → DeepL translation → preview first 3 pages
5. Batch Processing: --dir flag to translate entire folders
6. GUI Mode: pdf2zh -i for non-technical users

What impresses me most about this project is how it simplifies a notoriously hard problem (preserving PDF layout during translation) into a single command. No mangled equations, no broken tables, accurate figure captions—pain points anyone who has translated papers will deeply appreciate.

Next Steps: If you read papers frequently, check out the Zotero plugin to save translations directly to your reference manager. You can also explore the --mcp flag to integrate it into AI Agent workflows.

If you've been manually struggling with paper translations, I highly recommend installing this today. The time saved on translating one paper is enough to read abstracts for two more.