pdf-layout-translate

Translate an illustrated PDF into another language while keeping every illustration, colour, border and page exactly where it was.

Built to make a Catalan edition of a beautifully illustrated Spanish tabletop RPG for my kids. The same pipeline works for any live-text PDF and any language pair — Catalan, English, German, whatever you need.

Why it exists

The usual tools destroy illustrated books:

• OCR-and-rebuild loses the layout entirely.
• Overlay tools paste text boxes on top of the artwork.
• Online "PDF translators" flatten 200+ pages of design into a Word file.

This pipeline treats the PDF as what it is — geometry plus text streams — and replaces only the live text layer, re-typeset to fit the original text boxes. The artwork is never rendered, so it can't be damaged.

What's here

• SKILL.md + SKILL-README.md — the workflow as an AI-agent skill: extraction, translation lanes, rendering, verification.
• scripts/ — the core tools: extract page geometry to JSON (render_full.py --dump), machine-translate the text layer (auto_translate.py), enrich style/font info (enrich_styles.py), render translated pages back into the PDF (render_full.py).
• pipeline/ — the full production run for a 236-page book: page classification, terminology audits, review batches, verification, final PDF assembly. Use it as a reference for scaling past a few pages.
• glossary.csv — example terminology glossary (source term → target languages) that keeps translations consistent across a whole book.

Two translation lanes

• Hand translation for the passages worth the effort — edit the JSON translation files directly.
• Machine translation for fast full coverage — then review with the audit scripts.

Both lanes feed the same geometry-aware renderer, and a verification step checks each rebuilt page against the original's geometry before print.

What's NOT here

No book content. The book this was built for is a commercial work, so its text, translations and artwork are not in this repository. Bring your own PDF — the pipeline reads your copy and writes your private edition. Translations of copyrighted works are for personal use; don't redistribute them.

Quick start

# 1. Dump one page's geometry + text to JSON (inspect what the renderer sees)
python3 scripts/render_full.py --source your-book.pdf --pages 5 --dump --out page-005.json

# 2. Machine-translate a page range into a translation JSON (edit by hand after)
python3 scripts/auto_translate.py --source your-book.pdf --pages 5-5 --out book.de.json

# 3. Render the translated page over the original geometry
python3 scripts/render_full.py --source your-book.pdf --pages 5 --translation book.de.json --out page-005-de.pdf

Target language and provider are set inside auto_translate.py; the translation JSON is plain text you can edit, review, or hand to a human translator. SKILL.md documents the full workflow.

Start with one representative chapter, stabilise terminology in the glossary, then scale the same workflow to the whole book.

License

MIT (the tooling, not any book you feed it).