PPT Translator

Convert your PowerPoint presentations to beautifully translated documents while preserving formatting

Clean, fast, and reliable PowerPoint translation with multi-provider support and formatting preservation

✨ Features • 🚀 Quick Start • 📖 Usage • 🧪 Testing • 🤝 Contributing

---

✨ Features

• ⚡ Lightning Fast: Sub-2 second translation for most presentations • 🔄 Multi-Provider Support: Switch between DeepSeek, OpenAI, Anthropic, Grok, and Gemini with a simple CLI flag • 🎨 Rich Formatting: Preserves fonts, colors, spacing, tables, and alignment after translation • 🔗 Smart Caching: Avoids duplicate API calls for repeated strings • 📦 Batch Processing: Convert entire directories of presentations at once • 🛡️ Robust Processing: Handles all PowerPoint content types with graceful fallbacks

🆕 Recent Updates

• Gemini support: Added Google Gemini as a translation provider
• Updated model defaults: Now using latest model versions (GPT-5.2, Claude Sonnet 4.5, Grok 4.1)
• Security fix: Replaced unsafe eval() with safe lookup functions

📦 Requirements

• Python 3.10+
• macOS (primary target), Linux, or Windows
• Provider API keys stored in environment variables (see below)

Install dependencies:

python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate  # Windows PowerShell
pip install -r requirements.txt

🔐 Configuration

Copy example.env to .env and fill in the API keys for the providers you plan to use. All keys are optional – only populate the providers you intend to call.

cp example.env .env

Environment variables of interest:

Provider	Required variable	Optional variables	Default model
DeepSeek	DEEPSEEK_API_KEY	DEEPSEEK_API_BASE	deepseek-chat
OpenAI	OPENAI_API_KEY	OPENAI_ORG	gpt-5.2-2025-12-11
Anthropic	ANTHROPIC_API_KEY	—	claude-sonnet-4-5-20250514
Grok	GROK_API_KEY	GROK_API_BASE	grok-4.1-fast
Gemini	GEMINI_API_KEY	—	gemini-3-flash-preview

📝 The CLI reads your .env file automatically when run from a shell session that has the variables exported. On macOS you can add the exports to ~/.zshrc or use direnv for project-specific secrets.

🚀 Usage

Run the CLI with the path to a single presentation or a directory tree:

python main.py /path/to/decks \
  --provider openai \
  --model gpt-5-mini \
  --source-lang zh \
  --target-lang en \
  --max-workers 4

Common options:

• --provider {deepseek,openai,anthropic,grok,gemini} – choose the model provider.
• --model MODEL_NAME – override the default model for that provider (e.g. gpt-5-nano).
• --source-lang / --target-lang – ISO language codes.
• --max-chunk-size – character limit per translation request (default: 1000).
• --max-workers – number of threads used when scanning slides (default: 4).
• --keep-intermediate – keep intermediate XML files for inspection/debugging.

The tool will generate:

1. {deck}_original.xml – source deck contents.
2. {deck}_translated.xml – translated content.
3. {deck}_translated.pptx – rebuilt presentation with translated text and formatting intact.

🧪 Testing

Run unit tests with Pytest:

pytest

The test suite focuses on translation chunking/caching and CLI utilities to ensure the core pipeline stays reliable as providers evolve.

🛠️ Project Structure

.
├── .claude/skills/ppt-translator/  # Self-contained Agent Skill
│   ├── SKILL.md                    # Skill instructions for Claude
│   ├── LICENSE.txt
│   └── scripts/                    # Complete translation toolkit
├── ppt_translator/
│   ├── cli.py               # CLI parsing and orchestration
│   ├── pipeline.py          # PPT extraction, translation, regeneration
│   ├── providers/           # DeepSeek, OpenAI, Anthropic, Grok, Gemini adapters
│   ├── translation.py       # Chunking + caching translation service
│   └── utils.py             # Filesystem helpers
├── tests/                   # Pytest suite
├── example.env              # Environment variable template
├── requirements.txt
└── main.py                  # Entry point (delegates to CLI)

🤖 Agent Skill

This project includes a self-contained Agent Skill in .claude/skills/ppt-translator/.

The skill directory contains everything needed to use this translator in any agent workflow:

• SKILL.md - Instructions for Claude on how to use the tool
• scripts/ - Complete copy of all translation scripts and dependencies

To use in another project: Copy the .claude/skills/ppt-translator/ directory into your project's .claude/skills/ folder. The skill is fully self-contained with all necessary scripts included.

🤝 Contributing

Pull requests and issues are welcome. Please run pytest before submitting changes and document any new providers or configuration steps in the README.

📄 License

This project remains under the MIT License. See LICENSE for details.