pdf-translator

Category: Content & Multimedia | Uploader: Overdue-Lin | Downloads: 0 | Version: v1.0（Latest）
Translate PDF documents while preserving original formatting. Converts PDF pages to images for layout analysis, extracts text and embedded images, translates content using agent's multilingual capabilities, and generates LaTeX code to recreate the original document structure with translated text. Special support for arXiv papers: when user provides arXiv ID (e.g., "2310.12345") or arXiv URL (e.g., "https://arxiv.org/abs/2310.12345" or "https://arxiv.org/pdf/2310.12345.pdf"), automatically download the source TeX files, translate the LaTeX content, and compile to PDF.
Changelog: Source: GitHub https://github.com/Overdue-Lin/pdf-translate-skill
Directory Structure

Current level: Root
📁 assets/
- 📄 base_template.tex 5.5 KB
📁 references/
- 📄 latex_templates.md 7.0 KB
- 📄 troubleshooting.md 7.2 KB
📁 scripts/
- 📄 compile_latex.py 7.7 KB
- 📄 download_arxiv_source.py 6.5 KB
- 📄 extract_images.py 5.2 KB
- 📄 pdf_to_images.py 3.9 KB
📄 README.md 1.7 KB
📄 SKILL.md 15.7 KB
SKILL.md

---
name: pdf-translator
description: Translate PDF documents while preserving original formatting. Converts PDF pages to images for layout analysis, extracts text and embedded images, translates content using agent's multilingual capabilities, and generates LaTeX code to recreate the original document structure with translated text. Special support for arXiv papers: when user provides arXiv ID (e.g., "2310.12345") or arXiv URL (e.g., "https://arxiv.org/abs/2310.12345" or "https://arxiv.org/pdf/2310.12345.pdf"), automatically download the source TeX files, translate the LaTeX content, and compile to PDF.
---

# PDF Translator Skill

A comprehensive skill for translating PDF documents while maintaining their original layout, formatting, and visual structure. This skill combines multimodal analysis, text extraction, machine translation, and LaTeX typesetting to produce high-quality translated PDFs.

## When to Use This Skill

Use this skill when you need to:
- Translate PDF documents from one language to another
- Preserve the original document's visual layout and formatting
- Handle documents with mixed text and images
- Process academic papers, reports, or formatted documents
- Support Chinese/English bidirectional translation
- **Translate arXiv papers** (provide arXiv ID like "2310.12345" or URL like "https://arxiv.org/abs/2310.12345")

## Prerequisites

### Required Software
- **Python 3.8+** with pip
- **PyMuPDF** (`pip install pymupdf pillow`)
- **XeLaTeX** (TeX Live or MiKTeX) for PDF compilation
- **ctex LaTeX package** for Chinese support
- **wget or curl** (for downloading arXiv source files)

### Installation Commands
```bash
# Python dependencies
pip install pymupdf pillow requests

# LaTeX (choose one)
# Ubuntu/Debian:
sudo apt install texlive-xetex texlive-lang-chinese

# macOS (Homebrew):
brew install mactex

# Windows: Download MiKTeX from https://miktex.org/
```

## Workflow Overview

The PDF translation follows this pipeline:

```
PDF Input → Page Images → Layout Analysis → Text Extraction → Translation → LaTeX Generation → PDF Output
```

### arXiv Paper Translation (Preferred Method)

When the user provides an **arXiv ID** or **arXiv URL**, use this optimized workflow:

```
arXiv ID/URL → Download Source TeX → Translate TeX Content → Compile → PDF Output
```

This method is **preferred** for arXiv papers because:
- Source TeX files preserve all formatting automatically
- No need for layout analysis or image extraction
- Higher quality translation output
- Faster processing

#### Step 1: Detect arXiv Input

Detect if user provided:
- **arXiv ID**: e.g., `2310.12345`, `hep-th/9901001`
- **arXiv URL**: e.g., 
  - `https://arxiv.org/abs/2310.12345`
  - `https://arxiv.org/pdf/2310.12345.pdf`
  - `https://arxiv.org/abs/hep-th/9901001`

**Extract arXiv ID** from input:
- From URL: extract the ID after `/abs/` or `/pdf/`
- From direct ID: use as-is

#### Step 2: Download arXiv Source

Download the source TeX files from arXiv using the provided script:

```bash
# Using the provided script
python scripts/download_arxiv_source.py 2310.12345 output_dir/

# Or with URL
python scripts/download_arxiv_source.py https://arxiv.org/abs/2310.12345 ./
```

**Manual download:**
```bash
# Method 1: Use arXiv's official source download
# Navigate to: https://arxiv.org/e-print/{arxiv_id}
# Download format: .tar.gz containing all source files

# Method 2: Use wget
wget -O source.tar.gz https://arxiv.org/e-print/2310.12345
tar -xzf source.tar.gz
```

The downloaded archive typically contains:
- Main `.tex` file (usually named after the paper ID)
- Style files (`.bst`, `.cls`)
- Bibliography (`.bib`)
- Figures (`.pdf`, `.png`, `.eps`)
- Other source files

#### Step 3: Identify Main TeX File

Find the main TeX file in the extracted contents:
- Usually named after the paper ID (e.g., `main.tex`, `paper.tex`)
- Check for `\documentclass` or `\begin{document}` to identify the entry point
- May need to inspect multiple `.tex` files to find the one with `\maketitle` or `\begin{document}`

#### Step 4: Translate TeX Content(!IMPORTANT)

Read and translate the main TeX file:

1. **Read the TeX file** and identify translatable content:
   - Text between `{` and `}` in regular text environments
   - Section titles, captions, footnotes
   - Abstract content
   
2. **Preserve non-translatable elements**:
   - Math formulas (`$...$`, `\[...\]`)
   - LaTeX commands (`\ref{...}`, `\cite{...}`)
   - Figure/table commands
   - Code blocks

3. **Translation approach**:
   - Translate text content while keeping LaTeX markup intact
   - Use `ctex` or `\usepackage{ctex}` for Chinese support
   - Maintain paragraph structure

4. **Key translation rules**:
   - Keep all `\section{...}`, `\subsection{...}` content - translate the text inside
   - Keep all `\caption{...}` content - translate inside
   - Keep all `\footnote{...}` content - translate inside  
   - Keep math formulas completely unchanged
   - Keep `\includegraphics{}` paths unchanged
   - Keep `\bibliography{}` unchanged
   - Translate abstract text

**Example translation:**
```latex
% Original:
\section{Introduction}
We present a new method for...

% Translated:
\section{介绍}
我们提出了一种新的方法...
```

#### Step 5: Compile Translated TeX

Compile the translated TeX file to PDF:

```bash
# Ensure Chinese support
# Add to preamble if not present:
\usepackage{ctex}

# Compile
xelatex translated.tex
# Run twice for references
xelatex translated.tex
```

Or use the provided script:
```bash
python scripts/compile_latex.py translated.tex output_dir/ --passes 2
```

#### Step 6: Handle Dependencies

If compilation fails due to missing packages or files:
1. Check for missing `.sty`, `.cls`, or `.bst` files
2. Copy missing files from the original arXiv source
3. Check `\graphicspath` for figure locations
4. Ensure all `\input{}` files are present

---

### Standard PDF Translation Workflow

### Step 1: Convert PDF to Page Images

Convert each PDF page to a high-quality image for multimodal analysis.

```bash
python scripts/pdf_to_images.py input.pdf output_pages/ --dpi 150
```

**Output:**
- `page_001.png`, `page_002.png`, ... (page images)
- `manifest.json` (page dimensions and metadata)

### Step 2: Extract Embedded Images

Extract original images from the PDF for reuse in the translated document.

```bash
python scripts/extract_images.py input.pdf output_extracted/
```

**Output:**
- `images/img_001_01.png`, ... (extracted images)
- `images_manifest.json` (image positions and metadata)

### Step 3: Analyze Layout and Extract Content

For each page image, analyze the layout and extract content:

**Using multimodal analysis:**
1. Describe the page layout structure (columns, sections, headers, footers)
2. Identify text blocks, their positions, and reading order
3. Identify figures, tables, and their captions
4. Note any special formatting (lists, equations, quotes)

**Prompt template for layout analysis:**
```
Analyze this PDF page image and describe:
1. Overall layout structure (columns, margins, alignment)
2. Text blocks with their approximate positions and hierarchy
3. Images, figures, or tables with their locations
4. Any special elements (headers, footers, page numbers, footnotes)

Provide a structured description that can be used to recreate this layout in LaTeX.
```

### Step 4: Translate Text Content

Translate the extracted text while maintaining:
- Technical terms accuracy
- Proper nouns (names, places)
- Formatting markers (emphasis, bold)
- Contextual meaning

**Translation guidelines:**
- Preserve original paragraph structure
- Maintain consistent terminology
- Handle inline formatting (bold, italic, code)
- Keep mathematical formulas unchanged

### Step 5: Generate LaTeX Code

Create LaTeX code that recreates the original layout with translated content.

**Key considerations:**
1. **Document class**: `article` for papers, `report` for longer documents
2. **Page geometry**: Match original margins
3. **Multi-column layouts**: Use `multicol` package
4. **Figures**: Use `\includegraphics` with proper positioning (Note: Insert the extracted images into their original positions)
5. **Tables**: Recreate with `tabular` or `longtable` (Note: Insert the identical table at its original position)
6. **Chinese support**: Always use `ctex` package with XeLaTeX
7. **!IMPORTANT**: Please modify the template format to match the style of the original PDF (Note: Pay special attention to the switching between single-column and double-column layouts)

**!IMPORTANT**: You can refer to **./references/latex_template.md** for details related to LaTeX generation.

**Template structure:**
```latex
\documentclass[12pt, a4paper]{article}
\usepackage{ctex}  % Chinese support
\usepackage{graphicx}
\usepackage{geometry}
% ... other packages

\begin{document}
% Translated content here
\end{document}
```

### Step 6: Compile LaTeX to PDF

Compile the generated LaTeX code to produce the final translated PDF.

```bash
python scripts/compile_latex.py translated.tex output_dir/ --passes 2
```

**Output:**
- `translated.pdf` (final translated document)

If any errors occur, you can troubleshoot them by referring to **./references/troubleshooting.md**.

## Detailed Implementation Guide

### Phase 1: Preparation

1. **Create working directory structure:**
   ```
   working_dir/
   ├── input.pdf
   ├── pages/           # Page images
   ├── extracted/       # Extracted images
   ├── translated.tex   # Generated LaTeX
   └── output.pdf       # Final result
   ```

2. **Convert PDF to images:**
   ```
   Use: python scripts/pdf_to_images.py
   Output: pages/page_001.png, ..., pages/manifest.json
   ```

3. **Extract embedded images:**
   ```
   Use: python scripts/extract_images.py
   Output: extracted/images/*, extracted/images_manifest.json
   ```

### Phase 2: Page-by-Page Processing

For each page:

1. **View page image** using multimodal capability

2. **Analyze layout structure:**
   - Number of columns
   - Section headings
   - Paragraph blocks
   - Figure/table positions
   - Header/footer content

3. **Extract text content:**
   - Use vision to identify text regions
   - Transcribe text from image (OCR-like)
   - Note formatting (bold, italic, font sizes)

4. **Translate content:**
   - Translate each text block
   - Maintain structure and formatting
   - Handle technical terms appropriately

5. **Generate LaTeX for page:**
   - Apply appropriate layout template
   - Insert translated text
   - Include images with correct positions
   - Handle special elements (tables, equations)

### Phase 3: Document Assembly

1. **Combine all pages into single LaTeX file:**
   - Use base_template.tex as foundation
   - Insert page content in order
   - Handle cross-page elements (tables, figures)

2. **Compile to PDF:**
   ```
   Use: python scripts/compile_latex.py
   Run multiple passes for references
   ```

3. **Verify output:**
   - Check all pages rendered correctly
   - Verify images are included
   - Confirm formatting matches original

## Common Layout Patterns

### Single Column Document
```latex
\section{Section Title}
Translated paragraph content here.

\begin{figure}[htbp]
  \centering
  \includegraphics[width=0.8\textwidth]{image.png}
  \caption{Translated caption}
\end{figure}
```

### Two Column Layout
```latex
\begin{multicols}{2}
\section{Left Column}
Content...

\section{Content Spanning}
...
\end{multicols}
```

### Academic Paper Structure
```latex
\title{Translated Title}
\author{Authors}
\maketitle

\begin{abstract}
Translated abstract...
\end{abstract}

\section{Introduction}
Content...

\section{Methods}
Content...

\bibliographystyle{plain}
\bibliography{references}
```

## Reference Files

- `assets/base_template.tex` - Base LaTeX template with Chinese support
- `references/latex_templates.md` - LaTeX code patterns for various layouts
- `references/troubleshooting.md` - Common issues and solutions

## Troubleshooting

### Font Issues
If Chinese characters don't render:
- Ensure XeLaTeX is used (not pdfLaTeX)
- Check ctex package is installed
- Verify system has Chinese fonts installed

### Image Not Found
If images don't appear in output:
- Check `\graphicspath` includes correct directory
- Verify image files exist and are readable
- Use correct file extensions in `\includegraphics`

### Layout Mismatch
If layout differs from original:
- Adjust geometry settings for margins
- Use appropriate figure placement options
- Check for column count differences

### Compilation Errors
If LaTeX compilation fails:
- Check log file for specific errors
- Verify all required packages are installed
- Ensure no syntax errors in generated code

### arXiv Specific Issues

#### Cannot Download Source
If arXiv source download fails:
- Check if the paper has source available (not all papers have TeX sources)
- Try alternative URL: `https://arxiv.org/e-print/{arxiv_id}`
- Some older papers may not have source available

#### Missing Package Errors
If compilation fails with "File not found" errors:
- Copy missing `.sty`, `.cls` files from the original download to your working directory
- Check for `\usepackage{...}` commands and ensure all referenced files exist
- Use `kpsewhich` to check if packages are installed system-wide

#### arXiv ID Format
Common arXiv ID formats:
- **New format**: `YYMM.NNNNN` (e.g., `2310.12345`)
- **Old format**: `archive/YYMMNNN` (e.g., `hep-th/9901001`)
- Both formats work with the download URL

## Best Practices

1. **Quality over speed**: Take time to analyze layout accurately
2. **Iterative refinement**: Generate, compile, review, and improve
3. **Preserve semantics**: Maintain document meaning over exact formatting
4. **Handle edge cases**: Be prepared for tables, equations, code blocks
5. **Test compilation**: Verify LaTeX compiles before final output

## Limitations

- **Exact pixel-perfect replication**: LaTeX is not a pixel-based layout engine
- **Complex graphics**: Vector illustrations may need to be captured as images
- **Custom fonts**: May require font substitution
- **Dynamic content**: JavaScript or form fields are not supported
- **Encrypted PDFs**: Cannot process password-protected documents

## Output Verification Checklist

- [ ] All pages included in output
- [ ] Text correctly translated
- [ ] Images positioned correctly
- [ ] Tables formatted properly
- [ ] No LaTeX compilation errors
- [ ] Chinese characters render correctly
- [ ] Page numbers and headers present
- [ ] Overall formatting matches original

## arXiv Translation Example

Here's a complete example of translating an arXiv paper:

### User Input
> "请翻译这篇 arXiv 论文: https://arxiv.org/abs/2310.12345"

### Workflow Execution

**Step 1: Detect arXiv ID**
- URL: `https://arxiv.org/abs/2310.12345`
- Extracted ID: `2310.12345`

**Step 2: Download Source**
```bash
python scripts/download_arxiv_source.py 2310.12345 ./arxiv_src
```

**Step 3: Identify Main TeX File**
- Found: `main.tex` (the main entry point)
- Also found: `refs.bib`, `figures/`, `style files`

**Step 4: Translate TeX Content**
- Read `main.tex`
- Translate section titles: `\section{Abstract}` → `\section{摘要}`
- Translate body text while preserving:
  - Math formulas: `$E = mc^2$` (unchanged)
  - Citations: `\cite{author2023}` (unchanged)
  - Figures: `\includegraphics{fig1.pdf}` (unchanged)
- Output: `main_zh.tex`

**Step 5: Add Chinese Support**
- Ensure `\usepackage{ctex}` or `\usepackage[UTF8]{ctex}` is in preamble
- If not present, add it

**Step 6: Compile to PDF**
```bash
python scripts/compile_latex.py main_zh.tex ./output --passes 2
```

**Step 7: Deliver Output**
- Translated PDF saved to: `./output/main_zh.pdf`

---

## Notes

- Some arXiv papers don't have source available (only PDF). In this case, fall back to standard PDF translation workflow.
- For papers with complex LaTeX packages, you may need to install additional packages.
- The `download_arxiv_source.py` script requires `curl` or `wget` to be installed.
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
pdf-translator

Directory Structure

SKILL.md

Report

Notice
