Ppt Translator

---
name: ppt-translator
description: Translate PowerPoint presentations while preserving formatting (fonts, colors, alignment, tables). Supports multiple LLM providers (OpenAI, Anthropic, DeepSeek, Grok, Gemini) plus an optional post-translation visual audit using the deepseek-v4-flash-vision-exp vision model. Use when translating .pptx files between languages, especially for CJK to/from English translations where text expansion/contraction is a concern, or when you need to QA rendered slides for overflow, truncation, or garbled text.
license: MIT - see LICENSE.txt
---

# PowerPoint Translation Skill

Translate PowerPoint presentations while preserving all formatting including fonts, colors, spacing, tables, and alignment.

## When to Use This Skill

- Translating `.pptx` files between languages
- Batch translating multiple presentations in a directory
- Preserving slide formatting during translation (especially CJK ↔ English)
- QA-ing a translated deck with a vision language model (`--vision-audit`) to catch text overflow, truncation, garbled glyphs, untranslated leftovers, overlaps, or contrast problems
- When you need to inspect intermediate XML for debugging

## Setup

Before first use, set up the environment:

```bash
# Navigate to the scripts directory
cd .claude/skills/ppt-translator/scripts

# Create virtual environment and install dependencies
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
pip install -r requirements.txt

# Configure API keys
cp example.env .env
# Edit .env with your provider API key(s)
```

## Basic Usage

```bash
cd .claude/skills/ppt-translator/scripts
source .venv/bin/activate

python main.py /path/to/presentation.pptx \
  --source-lang zh \
  --target-lang en
```

(The default provider is DeepSeek `deepseek-v4-flash`.)

## Provider Configuration

| Provider  | Environment Variable | Default Model              |
|-----------|---------------------|----------------------------|
| deepseek  | `DEEPSEEK_API_KEY`  | `deepseek-v4-flash`        |
| openai    | `OPENAI_API_KEY`    | `gpt-5.2-2025-12-11`       |
| anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-5-20250514` |
| grok      | `GROK_API_KEY`      | `grok-4.1-fast`            |
| gemini    | `GEMINI_API_KEY`    | `gemini-3-flash-preview`   |

## CLI Reference

| Option | Description | Default |
|--------|-------------|---------|
| `--provider` | LLM provider: `deepseek`, `openai`, `anthropic`, `grok`, `gemini` | `deepseek` |
| `--model` | Override default model for provider | Provider default |
| `--source-lang` | Source language ISO code | `zh` |
| `--target-lang` | Target language ISO code | `en` |
| `--max-chunk-size` | Characters per API request | `1000` |
| `--max-workers` | Threads for slide extraction | `4` |
| `--keep-intermediate` | Retain XML files for debugging | `false` |
| `--vision-audit` | After translation, render every rebuilt slide to an image and inspect it with DeepSeek's vision model for overflow, truncation, garbled glyphs, untranslated text, overlaps, or contrast issues. Requires `DEEPSEEK_API_KEY` and LibreOffice + poppler (`pdftoppm`) installed. Writes `{deck}_translated_vision_audit.md`. | `false` |
| `--vision-model` | Vision model used by `--vision-audit` | `deepseek-v4-flash-vision-exp` |
| `--vision-dpi` | Rendering resolution for audit images | `100` |

## Output Files

For each input `presentation.pptx`, the tool generates:

1. `presentation_original.xml` - Extracted source content (deleted unless `--keep-intermediate`)
2. `presentation_translated.xml` - Translated content (deleted unless `--keep-intermediate`)
3. `presentation_translated.pptx` - Final translated presentation with formatting intact
4. `presentation_translated_vision_audit.md` - Only with `--vision-audit`: per-slide findings from the vision model, grouped by slide with severity (high/medium/low)

## Common Workflows

### Translate a Single File (Chinese → English)

```bash
python main.py deck.pptx --provider anthropic --source-lang zh --target-lang en
```

### Batch Translate a Directory

```bash
python main.py /path/to/presentations/ --provider openai --source-lang ja --target-lang en
```

### Debug Translation Issues

```bash
python main.py deck.pptx --keep-intermediate --provider deepseek
# Inspect the generated XML files to see extracted/translated content
```

### Use a Specific Model

```bash
python main.py deck.pptx --provider openai --model gpt-5-mini
```

### Translate with Gemini (Cost-Effective)

```bash
python main.py deck.pptx --provider gemini --source-lang ko --target-lang en
```

### Translate and Run the Visual Audit

```bash
python main.py deck.pptx --source-lang zh --target-lang en --vision-audit
```

After rebuilding the deck, every slide is rendered to a PNG (LibreOffice headless → `pdftoppm`) and sent to `deepseek-v4-flash-vision-exp` together with the slide's expected translated text. The model compares the rendering against the expected content and reports concrete visual defects. Read `{deck}_translated_vision_audit.md` afterwards and fix any HIGH-severity findings (e.g. by shortening text or enlarging boxes) before shipping the deck.

Audit-only reruns on an already-translated deck are not needed — the audit runs automatically at the end of a `--vision-audit` run, and a failed audit never aborts the translation itself.

## Supported Languages

Use standard ISO 639-1 language codes:

| Code | Language |
|------|----------|
| `zh` | Chinese (Simplified) |
| `en` | English |
| `ja` | Japanese |
| `ko` | Korean |
| `es` | Spanish |
| `fr` | French |
| `de` | German |
| `pt` | Portuguese |
| `ru` | Russian |
| `ar` | Arabic |

## Design Notes

### Font Scaling

The tool automatically scales fonts down (70% for text, 80% for tables) to accommodate text expansion when translating from compact languages (Chinese, Japanese, Korean) to English. This prevents text overflow in fixed-size text boxes.

### Caching

Repeated strings within a presentation are cached to avoid redundant API calls. This is especially useful for presentations with recurring headers, footers, or terminology.

### Chunking

Long text blocks are intelligently split at sentence boundaries to stay within API limits while preserving translation quality.

## Troubleshooting

### "API key not found"

Ensure your `.env` file in the scripts directory contains the correct environment variable:
```bash
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
```

### Formatting looks wrong

1. Use `--keep-intermediate` to inspect the XML files
2. Check if the source presentation has unusual formatting
3. Try a different provider

### Translation incomplete

1. Check for API rate limits with your provider
2. Try reducing `--max-chunk-size` for very long text blocks
3. Ensure your API key has sufficient quota

### "Visual audit skipped: ... tools that were not found"

The visual audit needs LibreOffice (`soffice`) and poppler (`pdftoppm`):

```bash
brew install --cask libreoffice && brew install poppler   # macOS
# apt install libreoffice poppler-utils                   # Debian/Ubuntu
```

If LibreOffice itself crashes on launch (seen on some macOS 26 + LibreOffice 25.x combos), upgrade it: `brew upgrade --cask libreoffice`.

### "The visual audit requires a DeepSeek API key"

The audit always calls DeepSeek's vision endpoint regardless of the translation provider, so `DEEPSEEK_API_KEY` must be set even when translating with another provider.

## Script Reference

The `scripts/` directory contains:

- `main.py` - Entry point
- `requirements.txt` - Python dependencies
- `example.env` - Environment variable template
- `ppt_translator/` - Core translation module
  - `cli.py` - CLI argument parsing
  - `pipeline.py` - PPT extraction and regeneration
  - `translation.py` - Chunking and caching
  - `providers/` - LLM provider implementations
  - `vision_audit.py` - Slide rendering (LibreOffice + pdftoppm) and DeepSeek vision-model QA