README.md

---
title: PDF Translator
emoji: 📄
colorFrom: indigo
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
---

# PDF Translator — End-to-End (OCR → Translate → Render)

A single Gradio app that runs a full document-translation pipeline and rebuilds a
**layout-faithful PDF** in the target language. It chains three phases into one
end-to-end flow:

| Phase | Package | What it does |
|-------|---------|--------------|
| **1 · Parse / OCR** | [`pdf2zh/parser`](pdf2zh/parser) | Layout detection + OCR (Surya) and table cells (PaddleOCR) → a structured `ParsedDocument` (JSON). |
| **2 · Translate** | [`pdf2zh/translation`](pdf2zh/translation) | Async, chunked LLM translation with glossary, math-fix, TOC-fix and vision passes. |
| **3 · Render** | [`pdf2zh/render`](pdf2zh/render) | Rebuilds the PDF with **Typst**, overlaying translated text on the original layout. |

- **Entry point:** [`app.py`](app.py) → warms up models, then launches the Gradio UI ([`pdf2zh/webapp/ui.py`](pdf2zh/webapp/ui.py)).
- **Orchestration:** [`pdf2zh/e2e.py`](pdf2zh/e2e.py) — `run_pipeline()` chains Phase 1 → 2 → 3.

---

## Table of contents

1. [How it works](#how-it-works)
2. [Prerequisites (exact versions)](#prerequisites-exact-versions)
3. [Quick start — Docker (recommended, closest to production)](#quick-start--docker-recommended-closest-to-production)
4. [Run locally without Docker (personal GPU / laptop)](#run-locally-without-docker-personal-gpu--laptop)
5. [Configuration reference (`.env`)](#configuration-reference-env)
6. [Model downloads & caching](#model-downloads--caching)
7. [Using the web app](#using-the-web-app)
8. [Command-line & programmatic use](#command-line--programmatic-use)
9. [Testing](#testing)
10. [Deploy to a Hugging Face Space](#deploy-to-a-hugging-face-space)
11. [Troubleshooting](#troubleshooting)
12. [Customizing](#customizing)
13. [Known limitations](#known-limitations)
14. [License](#license)

---

## How it works

```
app.py  (Gradio UI, warmup() on boot, demo.queue serializes requests)
   │
   ▼
pdf2zh/e2e.py :: run_pipeline(pdf_path, src_lang, tgt_lang, provider,
                              api_key, model, pages, font, work_dir, progress)
   ├─ Phase 1  get_parser().parse_pdf(...)         # StageAParser — models loaded ONCE (singleton)
   │              └─ writes work_dir/phase1_parsed.json
   ├─ Phase 2  translate_document(parsed_dict, TranslatorConfig)
   │              └─ writes work_dir/phase2_translated.json
   └─ Phase 3  render_document(pdf_path, translated_dict, out.pdf, RenderConfig)
                  └─ shells out to the `typst` binary → translated_<hash>.pdf
```

- **Model singleton** — `StageAParser` loads ~3–5 GB of OCR weights exactly once
  (`warmup()` at startup), not per request. See [`pdf2zh/e2e.py`](pdf2zh/e2e.py).
- **Providers** — OpenRouter, Gemini, OpenAI, DeepSeek, MiniMax, Anthropic, LiteLLM.
  The user supplies their **own API key** in the UI; nothing is stored server-side.
- **Fonts** — the chosen font heads a multilingual fallback chain
  (Noto Sans / Noto Serif / Noto CJK / Be Vietnam Pro) so missing glyphs degrade
  gracefully. The default Helvetica lacks Vietnamese glyphs and is always overridden.

---

## Prerequisites (exact versions)

Reproducing this project reliably means matching the following stack. Deviating
(especially on the OCR/GPU pins) is the most common cause of a broken build.

| Component | Version / constraint | Notes |
|-----------|----------------------|-------|
| **Python** | `>=3.10, <3.13` | 3.10 / 3.11 / 3.12 only. Set in [`pyproject.toml`](pyproject.toml). |
| **Typst** | `v0.14.2` binary on `PATH` | Phase 3 shells out to it. Later 0.x may work but is untested. |
| **CUDA (GPU path)** | **13.x** runtime + driver | Docker base = `nvidia/cuda:13.0.0-cudnn-runtime-ubuntu22.04`. |
| **surya-ocr** | `==0.17.1` (pinned) | 0.18+ dropped the `settings.*_BATCH_SIZE` API used by `hardware.py`. |
| **transformers** | `==4.56.1` (pinned) | Matches surya-ocr 0.17.1. |
| **paddleocr** | `==3.6.0` (pinned) | Table-cell recognition. |
| **paddlepaddle-gpu** | `==3.3.1` (cu130) | Installed from the `cu130` extra index (see `requirements.txt`). |
| **torch / torchvision / numpy** | unpinned | Left to pip so it resolves a CUDA stack compatible with paddle. |
| **Fonts** | Noto Sans, Noto Serif, Noto CJK, Be Vietnam Pro | Must be visible to Typst (bundled in the Docker image). |

> **GPU is strongly recommended.** Phase 1 (Surya + PaddleOCR + Torch) is slow on CPU.
> A single 16 GB T4 works for small page ranges; an A100 (80 GB) handles the full
> batch-size settings in `.env.example`. On Apple Silicon the parser auto-selects
> the `mps` device with reduced batch sizes.

---

## Quick start — Docker (recommended, closest to production)

Docker is the only path that pins **every** system dependency (CUDA, Typst, fonts,
locale). Use it for the most reproducible result.

```bash
# 1. Clone
git clone https://github.com/HoanggNguyen/PDFTranslator.git
cd PDFTranslator

# 2. Seed the environment file (the container also does this, but do it locally too)
cp .env.example .env

# 3. Build the image (installs CUDA deps, Typst v0.14.2, fonts, Python deps)
docker build -t pdf2zh .

# 4a. Run WITH a GPU (requires the NVIDIA Container Toolkit on the host)
docker run --gpus all -p 7860:7860 pdf2zh

# 4b. Run WITHOUT a GPU (CPU only — much slower, fine for testing wiring)
docker run -p 7860:7860 -e DEVICE=cpu pdf2zh

# 5. Open the app
#    http://localhost:7860
```

**Persisting model weights across restarts** (avoid re-downloading ~3–5 GB):

```bash
docker run --gpus all -p 7860:7860 \
  -v "$PWD/.model-cache:/data" \
  pdf2zh
```

The container entrypoint prefers `/data` for all model caches when it is writable
(see the `entrypoint.sh` block in the [`Dockerfile`](Dockerfile)); mounting a host
volume there makes the weights survive container restarts.

> **NVIDIA Container Toolkit** is required for `--gpus all`. Install it on the host
> first: <https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html>.
> Verify with `docker run --rm --gpus all nvidia/cuda:13.0.0-base-ubuntu22.04 nvidia-smi`.

---

## Run locally without Docker (personal GPU / laptop)

Use this when you want to develop against the code directly. You are responsible
for three system dependencies that Docker would otherwise provide: **Python 3.10–3.12**,
the **Typst binary**, and **fonts**.

### 1. Clone and create an isolated environment

```bash
git clone https://github.com/HoanggNguyen/PDFTranslator.git
cd PDFTranslator

python3.12 -m venv .venv          # any 3.10–3.12 interpreter
source .venv/bin/activate         # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
```

### 2. Install the Typst binary (v0.14.2)

Phase 3 calls the `typst` executable. It must be on `PATH` (or point `TYPST_BIN`
at it).

```bash
# macOS (Homebrew)
brew install typst          # then verify the version is 0.14.x
typst --version

# Linux (x86_64) — pinned release, matches the Docker image
wget -qO /tmp/typst.tar.xz \
  "https://github.com/typst/typst/releases/download/v0.14.2/typst-x86_64-unknown-linux-musl.tar.xz"
tar -xJf /tmp/typst.tar.xz -C /tmp
sudo install -m 0755 /tmp/typst-x86_64-unknown-linux-musl/typst /usr/local/bin/typst
typst --version

# Any platform (Cargo)
cargo install typst-cli --locked
```

### 3. Install fonts (Vietnamese + CJK coverage)

Typst renders with whatever fonts it can find. Install Noto (covers Vietnamese and
CJK) and optionally Be Vietnam Pro, then confirm Typst sees them:

- **Linux:** `sudo apt-get install -y fonts-noto-core fonts-noto-cjk && fc-cache -f`
- **macOS:** install the Noto families (e.g. via Homebrew casks or Google Fonts).
- Alternatively, drop `.ttf/.otf` files into a directory and set `PDF2ZH_FONT_DIR`
  to it; the app passes that directory to Typst's `--font-path`.

```bash
typst fonts | grep -i noto     # should list Noto families
```

### 4. Install Python dependencies

```bash
# GPU stack (Linux + CUDA 13) — installs paddlepaddle-gpu (cu130) via the extra index
pip install -r requirements.txt

# CPU / macOS: requirements.txt targets a CUDA GPU. On a machine without a
# CUDA GPU, edit requirements.txt to drop the `paddlepaddle-gpu` line and the
# cu130 --extra-index-url, and install the CPU wheel instead:
#   pip install paddlepaddle==3.3.1
# then: pip install -r requirements.txt
```

### 5. Configure and run

```bash
cp .env.example .env            # then edit as needed (see Configuration reference)
python app.py                   # warms up models, serves http://localhost:7860
```

The first launch downloads the OCR weights (~3–5 GB) — see the next section.

---

## Configuration reference (`.env`)

`.env` is **gitignored**; [`.env.example`](.env.example) is the tracked template —
always `cp .env.example .env` after cloning. Values are read by
[`pdf2zh/config.py`](pdf2zh/config.py) (`Settings`, via `pydantic-settings`) and
consumed by the Phase-1 parser.

| Variable | Default | Meaning |
|----------|---------|---------|
| `DEVICE` | `auto` | `cuda`, `mps`, `cpu`, or `auto` (→ CUDA if a GPU is present, else MPS, else CPU). |
| `PAGE_BATCH_SIZE` | *(unset)* | Pages processed per batch. Leave unset on small GPUs. |
| `LAYOUT_BATCH_SIZE` | *(unset)* | Surya layout batch. |
| `DETECTION_BATCH_SIZE` | *(unset)* | Surya text-detection batch. |
| `OCR_BATCH_SIZE` | *(unset)* | Surya recognition batch (heaviest on VRAM). |
| `TABLE_BATCH_SIZE` | *(unset)* | Paddle table-cell batch. |
| `DETECTOR_BLANK_THRESHOLD` | `0.5` | OCR accuracy tuning (not VRAM related). |
| `DETECTOR_TEXT_THRESHOLD` | `0.6` | Must be **>** the blank threshold. |

**Batch-size guidance** (from `.env.example`):
- **Large GPU (A100 80 GB):** the values in `.env.example` (OCR 512, layout/detection 64,
  page 32, table 512) peak around 45–55 GB VRAM.
- **Small GPU (T4 16 GB):** leave every batch size **unset (empty)** so Surya picks
  safe defaults and avoids OOM.
- Unset values fall back to per-device defaults in
  [`pdf2zh/parser/utils/hardware.py`](pdf2zh/parser/utils/hardware.py).

### Provider / API keys

You do **not** put translation API keys in `.env` for normal use — they are entered
in the web UI per request and never stored. For **headless/CLI** runs you may set the
provider's env var instead of passing `--api-key`:

| Provider (UI label) | Key (config) | Env var | Default model |
|---------------------|--------------|---------|---------------|
| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `google/gemini-3.1-flash-lite` |
| Gemini | `gemini` | `GEMINI_API_KEY` | `gemini-2.5-flash-lite` |
| OpenAI | `openai` | `OPENAI_API_KEY` | `gpt-4o-mini` |
| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek-chat` |
| MiniMax | `minimax` | `MINIMAX_API_KEY` | `MiniMax-Text-01` |
| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` | `claude-haiku-4-5` |
| LiteLLM | `litellm` | `LITELLM_API_KEY` (+ `LITELLM_BASE_URL`) | proxy-routed |

Defined in [`pdf2zh/translation/config.py`](pdf2zh/translation/config.py) (`PROVIDERS`).

---

## Model downloads & caching

The OCR weights are **not** bundled — they download on the **first request** and are
then cached. Point these env vars at a persistent, writable directory to download
them only once:

| Env var | What it caches |
|---------|----------------|
| `MODEL_CACHE_DIR` | Surya layout / detection / recognition models (Datalab). |
| `PADDLE_PDX_CACHE_HOME` | Paddle table-cell model (PaddleX). |
| `HF_HOME` / `TRANSFORMERS_CACHE` | Hugging Face / transformers assets. |

In Docker these default to `/app/.cache/*` and, when Hugging Face Persistent Storage
(or a mounted `-v host:/data`) is available, to `/data/*` (handled by the entrypoint).
Locally they default to the standard per-tool locations unless you export them, e.g.:

```bash
export MODEL_CACHE_DIR="$HOME/.cache/pdf2zh/datalab"
export PADDLE_PDX_CACHE_HOME="$HOME/.cache/pdf2zh/paddlex"
export HF_HOME="$HOME/.cache/pdf2zh/huggingface"
```

> First run also warms the Typst package cache (`cmarker`, `mitex`). In Docker this
> is pre-baked; locally Typst fetches them once from `@preview` (needs network on
> first render).

---

## Using the web app

1. Upload a PDF in the main panel.
2. In the sidebar pick a **Provider**, paste your **API key** (optionally click
   *Load models* to fetch the model list, or type a model name).
3. Choose **source / target language**, **output font**, and **page range**
   (All / First page / First 5 / First N — capped at 50 pages per request to guard
   against OOM).
4. Click **Translate**. A modal streams per-phase progress.
5. Preview and download the translated PDF.

---

## Command-line & programmatic use

Useful for automation, batch jobs, and debugging a single phase in isolation.

### End-to-end (all three phases)

```python
from pdf2zh.e2e import run_pipeline

out = run_pipeline(
    pdf_path="test/file/translate.cli.plain.text.pdf",
    src_lang="English", tgt_lang="Vietnamese",
    provider="openrouter", api_key="<YOUR_KEY>",
    model=None,                 # None → provider default
    pages=[0],                  # 0-based list, or None for all pages
    font="Noto Sans",
    work_dir="/tmp/e2e_test",   # phase1/phase2 JSON + final PDF land here
    progress=lambda f, m: print(f"{f:.0%} {m}"),
)
print("OUTPUT:", out)
```

### Phase 2 only — translate an existing parsed JSON

```bash
python test/verify_translate.py \
  --input test_local/output_math.json \
  --provider openrouter --api-key "$OPENROUTER_API_KEY" \
  --src English --tgt Vietnamese
```

(The underlying CLI is [`pdf2zh/translation/cli.py`](pdf2zh/translation/cli.py):
`--provider`, `--model`, `--api-key`, `--concurrent`, `--chunk-bytes`,
`--no-glossary`, `--no-math-fix`, `--no-toc-fix`, …)

### Phase 3 only — render translated JSON back onto the original PDF

```bash
python -m pdf2zh.render \
  --pdf <source.pdf> \
  --parsed test_local/output_math.translated.json \
  --output /tmp/render_test.pdf \
  --font-family "Noto Sans" \
  --typst-bin typst
```

See [`pdf2zh/render/cli.py`](pdf2zh/render/cli.py) for all flags
(`--pages`, `--min-font`, `--no-redact`, `--keep-typst-source`, `--aggressive-compress`, …).

---

## Testing

```bash
# 0. Cheap import check (does NOT load models)
python -c "import pdf2zh.e2e; print('e2e import OK')"

# 1. Unit / integration tests (do not require a GPU or API key for most cases)
pytest -q

# 2. Phase-2 smoke (needs an API key)
python test/verify_translate.py --input test_local/output_math.json \
       --provider openrouter --api-key "$OPENROUTER_API_KEY" --src English --tgt Vietnamese

# 3. Phase-3 render feasibility / smoke
python test/verify_render.py --input <source.pdf> \
       --parsed test_local/output_math.translated.json --output /tmp/render_test.pdf
```

Tips: the first run downloads the OCR models (~3–5 GB); use a **single page** while
iterating to keep API cost and latency low.

---

## Customizing

- **Add a font** — drop a `.ttf/.otf` into the font directory (`PDF2ZH_FONT_DIR`,
  `/app/fonts` in Docker; see [`Dockerfile`](Dockerfile)) and add its family name to
  `BUNDLED_FONTS` in [`pdf2zh/e2e.py`](pdf2zh/e2e.py).
- **Add a provider** — add an entry to `PROVIDERS` in
  [`pdf2zh/translation/config.py`](pdf2zh/translation/config.py) and to `PROVIDER_KEY`
  in [`pdf2zh/webapp/config.py`](pdf2zh/webapp/config.py).
- **Change page limit / default language / default font** — edit the constants in
  [`pdf2zh/webapp/config.py`](pdf2zh/webapp/config.py) (`MAX_CUSTOM_PAGES`,
  `PAGE_PRESETS`) and [`pdf2zh/e2e.py`](pdf2zh/e2e.py) (`SUPPORTED_LANGUAGES`,
  `DEFAULT_FONT`).
- **Tune OCR batch sizes / device** — edit `.env` (see Configuration reference).

---

## Known limitations

- Equation elements without `equation_words` are rendered as-is (not translated).
- A single T4 (16 GB) can OOM on large PDFs; the UI caps custom page counts at 50 and
  serializes requests via `demo.queue()`. Reduce the page range if needed.
- Phase 3 depends on the external `typst` binary; a version mismatch can change layout.

---

## License

This project builds on [PDFMathTranslate](https://github.com/Byaidu/PDFMathTranslate)
(AGPL-3.0). See [`LICENSE`](LICENSE).