the command
Chinese in, English out. One command.
pdfdrill translate sends every prose element of a document to DeepL: paragraphs, abstracts, section headings, list items and footnotes. It writes the translation into the document model in place and keeps the original text beside it under <field>_source. Equations, code and figures are never sent, so the math arrives unchanged.
# 1 · a DeepL API key (a free key ends in :fx and uses the free host) $ export DEEPL_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:fx # 2 · once per session: translate is blocked until you attest you read the SKILL $ pdfdrill preflight $ pdfdrill preflight --ack <TOKEN> # TOKEN = the last line of SKILL.md # 3 · step zero, as always: does the PDF have a text layer? $ pdfdrill size Clutter.pdf # 4 · translate: Chinese → US English (builds the model first if there is none) $ pdfdrill translate Clutter.pdf --from ZH --to EN-US Translated to EN-US via DeepL (in place; original kept under <field>_source). • tiddlers: Clutter.pdf.drill/Clutter.tiddlers.json — 67 tiddler(s), translated text in the `text` field • markdown: Clutter.pdf.drill/Clutter.md — 99 object(s), bi-layer (translation + hidden source, CSS/JS toggle) # 5 · read it: the inspector's flag menu switches 🇨🇳 ZH ↔ 🇺🇸 EN-US $ pdfdrill inspect Clutter.pdf Docmodel inspector: 359 elements over 8 page(s). Open Clutter.pdf.drill/Clutter.inspect.html in a browser …
translate --from ZH --to EN-US, each section held at its heading. English runs longer, so what follows the heading shifts down; the equations and figures themselves are never sent to DeepL and do not change. The translation is DeepL's, unedited: 轨道 (railway track) comes out as “Orbit”. Paper: Peng Zezhou, Gao Hongmin, Hu Weidong, Jiang Huanyu, Liu Qingguo, Research on signal processing algorithm of Doppler speed measurement radar under clutter background.language codes
DeepL codes, not ISO names. --from ZH reads Chinese, simplified or traditional. --to EN-US is the default target; use --to EN-GB for British English. The same flags cover every DeepL pair: --from DE, --from RU, --from JA, --to PT-BR. --from is optional because DeepL detects the language, but give it: the model then records both languages instead of guessing one later.
what you get
The same document in two languages, in one model: every translated element keeps its original beside it. Read it in the inspector (pdfdrill inspect): the reflow view renders the English with its equations and figures, and the language menu switches back to the original. translate also rewrites the tiddler file (English prose, tagged translated) and a bi-layer <bibkey>.md. That Markdown is the token-compact LLM projection: formulas are [F1]/[E1] placeholders resolved in a glossary at the end, and figures are text stubs, so it is not the file to read. Earlier examples: EN → PT-BR, DE → EN.
cost control
DeepL bills by the character, so pdfdrill never pays twice. Elements that already carry <field>_source are skipped, and a rebuilt tiddler file gets its stored translations back for free. --limit 20 translates only the first 20 elements, which is a cheap test run. --force re-translates everything from the preserved original, never from the translation.
If size reports “NO text layer — scanned, OCR required”, there is no text to translate yet. OCR it with tesseract's Chinese model first, then translate: pdfdrill ocr paper-zh.pdf --lang chi_sim (use chi_tra for traditional characters, chi_sim+eng for mixed pages). The model is built from that lines.json. The tesseract language pack must be installed (tesseract --list-langs).
pdfdrill translates the model: you read the English in the inspector, where the formulas stay LaTeX you can search and reuse. It does not write a PDF that keeps the original page layout. For that, use PDFMathTranslate (pdf2zh). It typesets the translation back into the original pages, formulas and figures in place, and writes a translated-only PDF plus a bilingual one: pdf2zh Clutter.pdf -li zh -lo en -s deepl. The two tools work well together: pdf2zh for a PDF to print or send, pdfdrill for text and math an LLM or a wiki can use.
⛔ pdfdrill STOP … BLOCKED: the preflight gate from step 2. Run pdfdrill preflight and ack the token, or set PDFDRILL_NO_PREFLIGHT=1 in scripts.
DeepL unavailable: set DEEPL_API_KEY: the key is missing from the environment or .env.
Not found: --help: translate --help reads --help as a file name. pdfdrill help lists every command with its flags.
Nothing changed on a re-run: that is the idempotence at work; the document is already translated. Add --force to redo it.