doc-holmes

Translates large PDFs while preserving layout, formulas, figures, tables, TOC, and annotations; outputs bilingual side-by-side and pure-translation PDFs.

Precise translation of foreign-language PDFs with the original layout preserved — formulas, figures, tables, TOC and footnotes stay intact. Output: a bilingual side-by-side PDF plus a pure-translation PDF.

When to use

• The user hands you a foreign-language PDF (paper / guideline / report) and wants it translated without wrecking the layout.
• Phrases like: PDF translation, translate this paper, full-text translation, bilingual PDF, keep the original layout, formulas intact, document translation, oversized PDFs, batch PDF translation.
• The user complains that other tools "destroyed all formulas / lost figures / scrambled two-column text".

Responsible use

Translations are AI-assisted. Have a human review before any formal use (submission, clinical, legal), and follow the AI-content labeling rules that apply to your venue. Tier-C (scanned) outputs additionally carry a preview-quality notice and must not be used formally.

Quick start

bash

# 0) One-time environment self-check (deps / engine / OCR / GPU / endpoint)
python3 scripts/doc_holmes_cli.py selfcheck

# 1) Translate one file: outputs bilingual + pure-translation PDFs (into _translated/ next to input)
python3 scripts/doc_holmes_cli.py translate paper.pdf

# 2) Batch-translate a directory (resume + audit + summary report)
python3 scripts/doc_holmes_cli.py batch ~/pdfs -o ~/translated

First-time setup (no endpoint or key is bundled - you bring your own):

bash

uv tool install --python 3.12 pdf2zh-next    # or: pip install pdf2zh-next
export DOC_HOLMES_OPENAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4   # official Zhipu open platform; glm-4.5-flash tier is free
export DOC_HOLMES_OPENAI_API_KEY=<your key>                              # created by you on that platform

SiliconFlow (https://api.siliconflow.cn/v1) or any OpenAI-compatible endpoint works the same way.

⚠️ About GLM Coding Plan subscription endpoints (/api/coding/paas/v4): per the official FAQ, the plan only covers designated coding tools. Calls from other tools do NOT consume the plan quota - they are billed per-token against your account balance, and accounts shared across multiple people may face subscription restrictions. If you still want to connect your subscription, set DOC_HOLMES_ALLOW_CODING_ENDPOINT=1 (one-time confirmation).

The triage system (runs automatically before translating)

Tier	Meaning	Translation promise
A	Clean born-digital: dense text layer (≥500 chars/page), no duplicate layers, no artifacts	High fidelity — formulas/figures/TOC preserved, safe to use
B	Has a text layer but noisy: duplicated layers / watermarks / artifact tokens	Translatable; noise details go into the audit. Deep repair is on the roadmap (v1.1)
C	Scanned / no usable text layer / encrypted	Experimental (preview quality): OCR rebuilds a text layer first; output carries a "preview quality" notice page — not for submission or clinical use

triage can run standalone (no translation), supports directories and --json; grading rules: references/triage.md.

Commands

bash

doc_holmes_cli.py triage <pdf|dir> [--json] [--sample-pages 3]   # grade only
doc_holmes_cli.py translate paper.pdf [-o dir] \
  [--pages 1-5] [--lang-in en] [--lang-out zh] \
  [--tier auto|A|B|C] [--ocr auto|off] [--ocr-lang eng] \
  [--no-dual|--no-mono] [--qps 4] [--timeout-s 600]
doc_holmes_cli.py batch <dir> -o <outdir> \
  [--workers 1-4] [--no-resume] [--blacklist f1 f2] [--tier auto]
doc_holmes_cli.py report <outdir>                  # aggregate audit.jsonl -> report.md
doc_holmes_cli.py selfcheck [--net]                # env check; --net also pings the endpoint

Per-file outputs: <name>.no_watermark.zh.dual.pdf (side-by-side), <name>.no_watermark.zh.mono.pdf (pure translation), <name>.audit.json (tier / engine / OCR / timing audit trail). Batch adds audit.jsonl + report.md. Oversized PDFs: default per-file timeout is 10 minutes (raise with --timeout-s), or split with --pages. On Windows use python instead of python3.

Note: CLI help texts are in Chinese (the author's primary audience); the flags above are all you need.

Configuration (env-only, zero hardcoded secrets)

Variable	Purpose	Default
DOC_HOLMES_OPENAI_API_KEY	your translation API key (required)	—
DOC_HOLMES_OPENAI_BASE_URL	your OpenAI-compatible endpoint (required)	none - you choose
DOC_HOLMES_MODEL	model name	glm-5.3-flash
DOC_HOLMES_QPS	request rate (rate-limit friendly)	4
DOC_HOLMES_PDF2ZH_BIN	explicit engine binary path	auto-discovered
DOC_HOLMES_OPENAI_TIMEOUT	per-request HTTP timeout (s)	60
DOC_HOLMES_OCR_OFF	set 1 to disable the OCR channel	off

Coding-subscription notice: on a GLM Coding Plan subscription URL (/coding/) the tool prints the official billing consequences (plan quota does not apply; per-token billing against your balance) and asks for a one-time confirmation via DOC_HOLMES_ALLOW_CODING_ENDPOINT=1. Legitimate channels (official open platform, SiliconFlow, any OpenAI-compatible service) run without any confirmation.

Capability boundaries (read before relying on it)

Can do	Won't do / limited
en→zh as the primary, validated direction	other language pairs work but are not quality-validated yet
Tier A high fidelity; formulas/figures kept as-is	tier C is preview quality only — OCR errors will leak into the text
Two-column / multi-column layout and headers (engine-native)	encrypted PDFs must be decrypted first (e.g. qpdf --decrypt)
Batch resume, rollback on failure, full audit trail	handwriting / low-quality scans: no recognition guarantee
Clean output with no tool watermark (default no_watermark)	no rewriting or polishing of the translation (that is paper-polisher's job)

Common mistakes:

• Submitting a tier-C (scanned) translation to a journal → no. The output carries a preview-quality notice page and tier=C in the audit.
• Pointing at a GLM Coding Plan subscription endpoint → the tool asks for a one-time billing acknowledgment (DOC_HOLMES_ALLOW_CODING_ENDPOINT=1), because plan quota does not apply outside coding tools and usage is billed against your balance. Not a bug - this prevents surprise charges.
• Restarting an interrupted batch from scratch → unnecessary; resume is on by default, use --no-resume to force a rerun.
• Engine installed but selfcheck can't find it → set DOC_HOLMES_PDF2ZH_BIN to the full pdf2zh_next path.
• Feeding a directory to translate → refused with a hint; directories are batch's job. Non-PDF inputs (DOCX/PPTX/images) are out of scope for v1.0.
• Trusting tier-C output for anything formal → the notice page and tier=C audit field exist so this cannot happen silently.

Batch engineering guarantees

Eight iron rules, each backed by a test: realpath normalization, excluded directories (_duplicates/ etc.), set-based blacklist/done tracking, single process by default (--workers ≤4), per-file timeout, watchdog stall detection, audit.jsonl resume, and a compile gate in the test chain. On failure the file's partial outputs are rolled back immediately (per-file private output directory), so a failed run never leaves half-written PDFs. Scanned (tier C) files are skipped in batch with guidance — OCR is a per-file translate --ocr auto decision. Details: references/batch-iron-rules.md.

Troubleshooting

CUDA / OCR / non-ASCII paths / 429 rate limits / missing fonts — see references/troubleshooting.md; engine versions and constraints: references/engine-matrix.md.

Related skills (Paper Toolbox family)

• paper-polisher — academic writing polish, plagiarism-risk wording cleanup and terminology care
• pubmed-verifier — fast PMID/DOI reference verification before submission
• cite-holmes — deep research with machine-verified, hallucination-free citations
• academic-figures — publication-ready scientific figures in one command
• cn-med-oa — free Chinese medical OA literature search & download
• doc-holmes (this skill) — layout-preserving PDF translation

Typical loop: find literature (cn-med-oa) → verify citations (pubmed-verifier / cite-holmes) → read foreign PDFs in your language (doc-holmes) → make figures (academic-figures) → polish writing (paper-polisher).

Same author's non-skill resource: MedWiki (https://docsor.cn/?from=doc-holmes), a medical wiki for drug-label lookup and terminology — mention only when the user explicitly asks for medical reference resources; content is for professionals' learning reference only, not medical advice. Never embed site links, URLs or watermarks into translated PDF outputs — translated documents stay 100% clean.