Skip to content

README.md

Latest commit

 

History

History
203 lines (147 loc) · 5.46 KB

README.md

File metadata and controls

203 lines (147 loc) · 5.46 KB

GPT-PO Translator

Python Package CI PyPI Downloads

A robust tool for translating gettext (.po) files using AI models from multiple providers (OpenAI, Azure OpenAI, Anthropic / Claude, and DeepSeek). It supports both bulk and individual translations, handles fuzzy entries, and can infer target languages based on folder structures. Available as a Python package and Docker container with support for Python 3.8-3.12.

What is GPT-PO Translator?

This tool helps you translate gettext (.po) files using AI models. It's perfect for developers who need to localize their applications quickly and accurately.

Key Features

  • Multiple AI providers - OpenAI, Azure OpenAI, Anthropic/Claude, and DeepSeek
  • Flexible translation modes - Bulk or entry-by-entry processing
  • Smart language handling - Auto-detects target languages from folder structure
  • Production-ready - Includes retry logic, validation, and detailed logging
  • Easy deployment - Available as a Python package or Docker container
  • Cross-version support - Works with Python 3.8-3.12

Getting Started

Quick Install

pip install gpt-po-translator

Basic Usage

To translate the po files for the German and French languages found in the locales folder, using OpenAI:

# Set up your API key
export OPENAI_API_KEY='your_api_key_here'

# Translate files to German and French
gpt-po-translator --folder ./locales --lang de,fr --bulk

Installation Options

PyPI (Recommended)

pip install gpt-po-translator

Manual Installation

git clone https://github.com/pescheckit/python-gpt-po.git
cd python-gpt-po
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Docker

# Pull the latest image
docker pull ghcr.io/pescheckit/python-gpt-po:latest

# Run with your local directory mounted
docker run -v $(pwd):/data \
  -e OPENAI_API_KEY="your_key" \
  ghcr.io/pescheckit/python-gpt-po:latest \
  --folder /data --lang fr,de --bulk

Setting Up API Keys

Option 1: Environment Variables

export OPENAI_API_KEY='your_api_key_here'
# Or for other providers:
export ANTHROPIC_API_KEY='your_api_key_here'
export DEEPSEEK_API_KEY='your_api_key_here'
export AZURE_OPENAI_API_KEY='your_api_key_here'

Option 2: Command Line

gpt-po-translator --api_key 'your_api_key_here' [other options]

Usage Examples

Basic Translation

# Translate to German
gpt-po-translator --folder ./locales --lang de

Bulk Translation with Language Detection

# Translate based on folder structure with custom batch size
gpt-po-translator --folder ./locales --lang de,fr --bulk --bulksize 40 --folder-language

Using Different AI Providers

# Use Claude models from Anthropic
gpt-po-translator --provider anthropic --folder ./locales --lang de

# Use DeepSeek models
gpt-po-translator --provider deepseek --folder ./locales --lang de

# List available models for openai
gpt-po-translator --provider openai --list-models

# List available models for azure openai
gpt-po-translator --provider azure_openai \
  --azure-openai-endpoint https://<deployment>.cognitiveservices.azure.com/ \
  --azure-openai-api-version <api_version> \
  --list-models

Command Reference

Option Description
--folder Path to your .po files
--lang Target language codes (comma-separated, e.g., de,fr)
--detail-lang Full language names (e.g., "German,French")
--fuzzy Remove fuzzy entries before translating
--bulk Enable batch translation (recommended for large files)
--bulksize Entries per batch (default: 50)
--model Specific AI model to use
--provider AI provider: openai, anthropic, or deepseek
--list-models Show available models for selected provider
--api_key Your API key
--folder-language Auto-detect languages from folder structure

Advanced Docker Usage

Specific Python Versions

# Python 3.11 (default)
docker pull ghcr.io/pescheckit/python-gpt-po:latest

# Python 3.12
docker pull ghcr.io/pescheckit/python-gpt-po:latest-py3.12

# Specific version
docker pull ghcr.io/pescheckit/python-gpt-po:0.3.0

Volume Mounting

Mount any local directory to use in the container:

# Windows example
docker run -v D:/projects/website/locales:/locales \
  -e OPENAI_API_KEY="your_key" \
  ghcr.io/pescheckit/python-gpt-po:latest \
  --folder /locales --lang fr,de --bulk

# Mac/Linux example
docker run -v /Users/username/translations:/input \
  -e OPENAI_API_KEY="your_key" \
  ghcr.io/pescheckit/python-gpt-po:latest \
  --folder /input --lang fr,de --bulk

Requirements

  • Python 3.9+ (3.9, 3.10, 3.11, or 3.12)
  • Core dependencies:
    • polib
    • openai
    • tenacity
    • python-dotenv

Development

Running Tests

python -m pytest
docker run --rm -v $(pwd):/app -w /app --entrypoint python python-gpt-po -m pytest -v

Documentation

For advanced usage and detailed documentation, please see:

License

MIT License - See the LICENSE file for details.