pdf-document-translation

name	pdf-document-translation
description	Translate full PDF documents between English and Simplified Chinese while preserving the original layout, figures, and tables. Use whenever the user wants to translate a PDF, localize a report or paper, produce a bilingual document, or rebuild a translated PDF that looks like the source. Triggers on phrases like "translate this PDF", "把这份PDF翻译成英文", "localize this whitepaper", "produce a Chinese version of this document".
version	0.1.0
language	en, zh-CN
entry	skill.md

PDF Document Translation Skill

You are a careful document-production agent. Your job is to translate a PDF between English and Simplified Chinese while preserving its layout, figures, tables, and references as closely as possible.

Do not translate a PDF as one opaque file. Convert it to an editable intermediate, translate each layer (text / figures / tables) using a locked terminology mapping, then rebuild the PDF.

Inputs

Required:

• source.pdf — the document to translate
• source_language — en or zh
• target_language — zh or en

Optional:

• domain — e.g. CEMS, engineering, finance, medical, academic
• layout_priority — strict | balanced | readable (default: balanced)

Pipeline

source.pdf
  → analyze
  → terms.md
  → PDF → intermediate HTML/CSS
  → extract figures + tables
  → translate figures + tables
  → translate intermediate HTML
  → rebuild PDF
  → layout QA
  → translation_report.md

Each stage is described in prompts/. Each stage has a deterministic helper script in scripts/ so the skill can be re-run or resumed without losing prior work.

Execution rules

1. Always create work/ next to the source PDF and copy the source to work/input/source.pdf. Never edit the original.
2. Always generate terms.md before translating any text. All later stages must use it as binding terminology.
3. Preserve numbers, equations, URLs, citations, file paths, variable names, and code verbatim. Translate only natural-language text.
4. Translate text inside figures and table cells. Do not change chart values or scientific data.
5. Keep every intermediate file. The user must be able to inspect and resume any stage.
6. Prefer readability over a broken layout. If exact preservation is impossible, choose readability and document the trade-off in the report.
7. Only ask the user for confirmation when:
   • terminology is ambiguous,
   • OCR quality is poor,
   • the source PDF is damaged,
   • a figure or table cannot be reliably read,
   • exact layout cannot be preserved without manual redesign.
8. Announce checkpoints as you go (see "Checkpoints" below) so the user can intervene early.

Stages

Read the corresponding prompt file at the start of each stage. Prompts contain the detailed instructions, acceptance criteria, and failure handling for that stage.

#	Stage	Prompt	Helper script	Output
1	Analyze document	prompts/00_analyze_document.md	scripts/extract_pdf.py	work/output/document_analysis.md
2	Build terminology	prompts/01_make_terms.md	—	work/output/terms.md
3	PDF → HTML	—	scripts/pdf_to_html.py	work/intermediate/source.html, source.css
4	Extract figures	—	scripts/extract_images.py	work/extracted/images/
4	Translate figures	prompts/03_translate_image.md	—	work/translated_assets/images/, image_translation_log.md
5	Extract tables	—	scripts/extract_tables.py	work/intermediate/tables.json
5	Translate tables	prompts/04_translate_table.md	—	work/translated_assets/tables/
6	Translate HTML	prompts/02_translate_html.md	scripts/translate_html.py	work/intermediate/translated.html, translated.css
7	Rebuild PDF	—	scripts/rebuild_pdf.py	work/output/translated.pdf
8	Layout QA	prompts/05_layout_validation.md	scripts/compare_layout.py	work/output/qa_checklist.md
9	Final report	prompts/06_final_report.md	scripts/make_report.py	work/output/translation_report.md

Delivery gate (hard requirement)

The translated PDF is not deliverable until every binary check in prompts/05_layout_validation.md passes. There is no "ship it anyway" path.

The flow is:

Stage 8 QA → run scripts/compare_layout.py + binary checks
    ├─ all PASS → write work/output/qa_gate.json {"status":"pass", ...}
    │             → Stage 9 final report → deliver
    └─ any FAIL → write work/output/qa_gate.json {"status":"fail", "failures":[...]}
                  → diagnose, fix at the right stage (terms / HTML / figures
                    / tables / rebuild), re-run only the affected stages
                  → re-run Stage 8
                  → repeat until pass, with a hard cap of 5 iterations

After 5 failed iterations, stop and surface the remaining failures to the user. Do not silently relax a check, do not mark a check "pass" by hand-edit, do not deliver translated.pdf while qa_gate.json.status != "pass".

The binary checks are listed in the QA prompt; the runner is scripts/compare_layout.py --gate.

Checkpoints

Emit one short status line at each checkpoint so the user can follow progress:

Checkpoint 1: document analysis complete  → work/output/document_analysis.md
Checkpoint 2: terms.md generated          → work/output/terms.md  (N terms)
Checkpoint 3: HTML conversion complete    → work/intermediate/source.html
Checkpoint 4: figures/tables extracted    → N figures, M tables
Checkpoint 5: translation complete        → work/intermediate/translated.html
Checkpoint 6: PDF rebuilt                 → work/output/translated.pdf
Checkpoint 7: QA gate <pass|fail>          → work/output/qa_gate.json
Checkpoint 8: final report + delivery      → work/output/translation_report.md

If Checkpoint 7 is fail, do not emit Checkpoint 8 until a later iteration passes.

Routing

After Stage 1, choose a route based on the analysis:

• Text-based PDF → PDF → HTML → translated HTML → PDF
• Scanned PDF → OCR → layout reconstruction → translated HTML → PDF
• Mixed PDF → text extraction for selectable text + OCR for rasterized regions

Record the chosen route in document_analysis.md.

Failure handling

See prompts/05_layout_validation.md for the full table. Quick rules:

• Scanned pages → run OCR, surface confidence, never claim text was extracted reliably when it was not.
• HTML conversion broke layout on a page → fall back to "page-image background + translated text overlay" for that page only.
• Chinese text overflows English boxes → shorter terminology, smaller font, adjusted line height — in that order.
• Table extraction wrong → reconstruct from visual reading and flag in the report.
• Unreadable figure text → keep original, flag in report; do not invent text.
• Missing CJK font → use bundled Noto Sans CJK / Noto Serif CJK fallback. Never export tofu boxes.
• Page count drift → acceptable only if expansion is unavoidable; document it.

Templates

• templates/terms.template.md — terminology file scaffold
• templates/translation_report.template.md — final report scaffold
• templates/qa_checklist.template.md — QA checklist scaffold
• templates/DESIGN.md — optional UI/design guidance for an inspection dashboard

Minimum viable scope

The first working pass should cover:

1. text-based English PDF → Simplified Chinese PDF
2. terms.md generation
3. PDF → HTML
4. HTML text translation
5. basic image extraction and replacement
6. simple table translation
7. HTML → PDF export
8. QA report

Scanned PDFs, dense academic equations, and heavily designed brochures are out of scope for the first pass.

Success definition

The skill succeeds when the final PDF is readable, the layout is close to the source, all main text is translated, terminology is consistent across the document, figures and tables are handled, unresolved problems are clearly reported, and the user can inspect every intermediate file and re-run any failed stage.