pptrans 1.0.0

Translate PowerPoint presentations using modern LLM providers with vision-based review

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, and Grok 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

📦 Installation

Option 1: Install via pip (Recommended)

pip install pptrans

Option 2: Install from source

git clone https://github.com/Z-MarkUs/PPTrans.git
cd PPTrans
pip install -e .

Option 3: Use standalone applications

Download pre-built applications for:

• macOS Apple Silicon (arm64): PPT-Translator-arm64.app
• macOS Intel (x86_64): PPT-Translator-x86_64.app
• Windows (x86): PPT-Translator.exe

Or build from source:

# macOS
./build.sh

# Windows
build.bat

# Linux
python3 build_app.py linux

📋 Requirements

• Python 3.10+ (for pip installation)
• Provider API keys stored in environment variables (see below)

🔐 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	Example default model
DeepSeek	DEEPSEEK_API_KEY	DEEPSEEK_API_BASE	deepseek-chat
OpenAI	OPENAI_API_KEY	OPENAI_ORG	gpt-5 (use --model for Mini/Nano)
Anthropic	ANTHROPIC_API_KEY	—	claude-3.7-sonnet
Grok	GROK_API_KEY	GROK_API_BASE	grok-beta

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

🚀 Quick Start

After installation, use the pptrans command:

# Translate a single file
pptrans presentation.pptx --provider openai --source-lang zh --target-lang en

# Translate all PPT files in a directory
pptrans ./presentations/ --provider openai

# With vision review
pptrans presentation.pptx --provider openai --vision-review --vision-model gpt-5.1

# Generate review file for manual editing
pptrans presentation.pptx --provider openai --generate-review

📖 Usage

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

pptrans /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} – 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

.
├── ppt_translator/
│   ├── cli.py               # CLI parsing and orchestration
│   ├── pipeline.py          # PPT extraction, translation, regeneration
│   ├── providers/           # DeepSeek, OpenAI, Anthropic, Grok 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)

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