pdf-translate

PDF Translation Skill

Translate PDF documents and generate beautifully typeset Chinese documents. Output in both Markdown and PDF formats.

Version Information

Current Version: v4.0.0 Release Date: 2026-02-21

v4.0.0 Changes

Adopted a Markdown-first workflow: generate structured Markdown first, then convert to PDF
Switched the PDF engine from reportlab to weasyprint (supports full HTML/CSS typesetting)
Fixed the garbled Chinese text issue in code blocks (added CJK font fallback)
Full support: heading levels, code blocks, tables, lists, quotes, bold and italics
Added scripts/md2pdf.py general-purpose conversion script

Core Workflow

Step 1: Extract PDF text

import pdfplumber

pdf = pdfplumber.open("输入文件.pdf")
for i, page in enumerate(pdf.pages):
    text = page.extract_text()
    if text:
        print(f"--- Page {i+1} ---")
        print(text)

For long documents (>20 pages), first extract the first few pages to understand the structure, then extract in batches.

Step 2: Analyze document structure

Read through the full text, identify the following elements, and plan the Markdown mapping:

Source Element	Markdown Mapping
Document Title	`#`
Chapter	`##`
Section	`###`
Subsection	`####`
Table of Contents	Link list `- [章节名](#锚点)`
Body Paragraph	Paragraph (separated by blank lines)
Code Block	``` fence (do not translatecontent)
Table	`\| 列1 \| 列2 \|` syntax
Ordered List	`1.` start
Unordered List	`-` start
Quote/Callout Box	`>` syntax
Footer/Page Number	Discard

Step 3: Translate chapter by chapter into Chinese Markdown

Must translate chapter by chapter, do not output the entire text at once. Append to the file after completing each chapter.

Translation Rules

Keep proper nouns in English: on first occurrence, append the English in parentheses, e.g. "progressive disclosure (Progressive Disclosure)"
Do not translate code blocks：``` : keep the content inside code blocks as the original text, and only translate the explanatory text outside the fences
Do not translate inline code: keep identifiers, commands, and file names inside backticks in English
Maintain the hierarchy：# → ## → ### → #### do not skip levels
Blank lines are required between paragraphs: there must be blank lines before and after every paragraph, list, code block, and table
List format：- or 1. at the start, use 2 spaces for nesting indentation
Table format：| 列1 | 列2 | syntax, must have a |---|---| separator row
Quote format：> at the start

Translation Quality Standards

See translation-standards.md

Three-step translation workflow: rewrite the first draft → diagnose issues → polish and finalize
Four major language transformation strategies: hypotaxis → parataxis, passive → active, abstract → concrete, trim redundancy
Eliminate "Europeanized expressions" and "translationese"

Formatting Errors That Must Be Avoided

❌ No blank lines between paragraphs → text gets crammed together
❌ No blank line before list items → not recognized as a list
❌ No blank lines before and after tables → tables cannot be rendered
❌ Code block ``` has no blank lines before and after → the code block will not be displayed
❌ Heading ## has no blank lines before and after → the heading will not be recognized
❌ Translate the code inside code blocks
❌ Outputting all content at once causes truncation

Step 4: Output the Markdown file

Write to the .md file, in the same directory as the original PDF, with the filename:原文件名_中文翻译.md

Step 5: Generate the PDF

Use scripts/md2pdf.py to convert Markdown into a beautifully typeset PDF:

python3 ${SKILL_DIR}/scripts/md2pdf.py "输入.md" "输出.pdf"

On macOS, if it reports that gobject cannot be found:

DYLD_FALLBACK_LIBRARY_PATH="/opt/homebrew/lib" python3 ${SKILL_DIR}/scripts/md2pdf.py "输入.md" "输出.pdf"

You can also use the copy in the project directory:

python3 scripts/md2pdf.py "输入.md" "输出.pdf"

PDF typesetting features:

A4 page size, automatic pagination, page numbers
Chinese fonts (PingFang/Heiti/YaHei) + English font fallback
Dark-background code blocks (support Chinese comments)
Professional table styles (alternating row colors, borders)
Blockquotes with a blue left border
Heading hierarchy styles (blue rules, decreasing font sizes)

Step 6: Confirm the output

After translation is complete, inform the user of:

.md file path
.pdf file path
Document overview (page count, word count)

Dependency installation

# macOS
brew install pango
pip3 install pdfplumber markdown weasyprint

# 旧方案依赖（仍可用）
pip3 install reportlab pypdf

Script directory

Script	Purpose
`scripts/md2pdf.py`	Recommended Markdown → PDF (weasyprint engine)
`scripts/translate_pdf.py`	Legacy: basic PDF extraction and generation (reportlab)
`scripts/generate_complete_pdf.py`	Legacy: complete workflow (reportlab)

Troubleshooting

Issue	Solution
Garbled Chinese text in code blocks	Use `md2pdf.py`(v4.0, CJK font fallback fixed)
weasyprint reports that gobject cannot be found	`DYLD_FALLBACK_LIBRARY_PATH="/opt/homebrew/lib"`
Chinese fonts are not displayed	Confirm that the system has PingFang or Heiti fonts
Markdown formatting is broken	Check whether there are blank lines before and after block-level elements

For more issues, see troubleshooting.md

Reference documentation：