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)

• When you need to inspect intermediate XML for debugging

Setup

Before first use, set up the environment:

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

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

python main.py /path/to/presentation.pptx
--provider openai
--source-lang zh
--target-lang en

Provider Configuration

Provider Environment Variable Default Model

openai OPENAI_API_KEY

gpt-5.2-2025-12-11

anthropic ANTHROPIC_API_KEY

claude-sonnet-4-5-20250514

deepseek DEEPSEEK_API_KEY

deepseek-chat

grok GROK_API_KEY

grok-4.1-fast

gemini GEMINI_API_KEY

gemini-3-flash-preview

CLI Reference

Option Description Default

--provider

LLM provider: openai , anthropic , deepseek , grok , gemini

openai

--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

Output Files

For each input presentation.pptx , the tool generates:

• presentation_original.xml

• Extracted source content (deleted unless --keep-intermediate )

• presentation_translated.xml

• Translated content (deleted unless --keep-intermediate )

• presentation_translated.pptx

• Final translated presentation with formatting intact

Common Workflows

Translate a Single File (Chinese → English)

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

Batch Translate a Directory

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

Debug Translation Issues

python main.py deck.pptx --keep-intermediate --provider deepseek

Inspect the generated XML files to see extracted/translated content

Use a Specific Model

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

Translate with Gemini (Cost-Effective)

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

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:

OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-...

Formatting looks wrong

• Use --keep-intermediate to inspect the XML files

• Check if the source presentation has unusual formatting

• Try a different provider

Translation incomplete

• Check for API rate limits with your provider

• Try reducing --max-chunk-size for very long text blocks

• Ensure your API key has sufficient quota

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