Skip to content

Commit b9b4713

Browse files
pescheck-brampescheck-bram
authored
Merge pull request #50 from pescheckit/feature_updated-readme
Updated REAMDE.md
2 parents 2e738d8 + 7bb03cf commit b9b4713

File tree

2 files changed

+93
-186
lines changed

2 files changed

+93
-186
lines changed

‎README.md‎

Lines changed: 92 additions & 166 deletions
Original file line numberDiff line numberDiff line change
@@ -4,246 +4,172 @@
44
![PyPI](https://img.shields.io/pypi/v/gpt-po-translator?label=gpt-po-translator)
55
![Downloads](https://pepy.tech/badge/gpt-po-translator)
66

7-
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.
7+
**Translate gettext (.po) files using AI models.** Supports OpenAI, Azure OpenAI, Anthropic/Claude, and DeepSeek with automatic AI translation tagging.
88

9-
## What is GPT-PO Translator?
10-
11-
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.
12-
13-
### Key Features
14-
15-
- **Multiple AI providers** - OpenAI, Azure OpenAI, Anthropic/Claude, and DeepSeek
16-
- **Flexible translation modes** - Bulk or entry-by-entry processing
17-
- **Smart language handling** - Auto-detects target languages from folder structure
18-
- **AI translation tracking** - Automatically tags AI-generated translations with comments
19-
- **Production-ready** - Includes retry logic, validation, and detailed logging
20-
- **Easy deployment** - Available as a Python package or Docker container
21-
- **Cross-version support** - Works with Python 3.8-3.12
22-
23-
## Getting Started
24-
25-
### Quick Install
9+
## 🚀 Quick Start
2610

2711
```bash
12+
# Install
2813
pip install gpt-po-translator
29-
```
30-
31-
### Basic Usage
32-
33-
To translate the `po` files for the German and French languages found in the `locales` folder, using OpenAI:
3414

35-
```bash
36-
# Set up your API key
15+
# Set API key
3716
export OPENAI_API_KEY='your_api_key_here'
3817

39-
# Translate files to German and French
18+
# Translate to German and French
4019
gpt-po-translator --folder ./locales --lang de,fr --bulk
4120
```
4221

43-
## Installation Options
22+
## ✨ Key Features
4423

45-
### PyPI (Recommended)
24+
- **Multiple AI providers** - OpenAI, Azure OpenAI, Anthropic/Claude, DeepSeek
25+
- **AI translation tracking** - Auto-tags AI-generated translations with `#. AI-generated` comments
26+
- **Bulk processing** - Efficient batch translation for large files
27+
- **Smart language detection** - Auto-detects target languages from folder structure
28+
- **Fuzzy entry handling** - Translates and fixes fuzzy entries properly
29+
- **Docker ready** - Available as container for easy deployment
4630

31+
## 📦 Installation
32+
33+
### PyPI (Recommended)
4734
```bash
4835
pip install gpt-po-translator
4936
```
5037

51-
### Manual Installation
38+
### Docker
39+
```bash
40+
docker pull ghcr.io/pescheckit/python-gpt-po:latest
41+
```
5242

43+
### Manual
5344
```bash
5445
git clone https://github.com/pescheckit/python-gpt-po.git
5546
cd python-gpt-po
56-
python3 -m venv .venv
57-
source .venv/bin/activate
58-
pip install -r requirements.txt
47+
pip install -e .
5948
```
6049

61-
### Docker
62-
63-
```bash
64-
# Pull the latest image
65-
docker pull ghcr.io/pescheckit/python-gpt-po:latest
50+
## 🔧 Setup
6651

67-
# Run with your local directory mounted
68-
docker run -v $(pwd):/data \
69-
-e OPENAI_API_KEY="your_key" \
70-
ghcr.io/pescheckit/python-gpt-po:latest \
71-
--folder /data --lang fr,de --bulk
52+
### API Keys
7253

73-
# Or with Azure OpenAI
74-
docker run -v $(pwd):/data \
75-
-e AZURE_OPENAI_API_KEY="your_key" \
76-
-e AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" \
77-
-e AZURE_OPENAI_API_VERSION="2024-02-01" \
78-
ghcr.io/pescheckit/python-gpt-po:latest \
79-
--provider azure_openai --folder /data --lang fr,de --bulk
80-
```
54+
Choose your AI provider and set the corresponding API key:
8155

82-
## Setting Up API Keys
56+
```bash
57+
# OpenAI
58+
export OPENAI_API_KEY='your_key'
8359

84-
### Option 1: Environment Variables
60+
# Anthropic/Claude
61+
export ANTHROPIC_API_KEY='your_key'
8562

86-
```bash
87-
export OPENAI_API_KEY='your_api_key_here'
88-
# Or for other providers:
89-
export ANTHROPIC_API_KEY='your_api_key_here'
90-
export DEEPSEEK_API_KEY='your_api_key_here'
63+
# DeepSeek
64+
export DEEPSEEK_API_KEY='your_key'
9165

92-
# For Azure OpenAI:
93-
export AZURE_OPENAI_API_KEY='your_api_key_here'
66+
# Azure OpenAI
67+
export AZURE_OPENAI_API_KEY='your_key'
9468
export AZURE_OPENAI_ENDPOINT='https://your-resource.openai.azure.com/'
9569
export AZURE_OPENAI_API_VERSION='2024-02-01'
9670
```
9771

98-
### Option 2: Command Line
99-
100-
```bash
101-
gpt-po-translator --api_key 'your_api_key_here' [other options]
102-
```
103-
104-
## Usage Examples
72+
## 💡 Usage Examples
10573

10674
### Basic Translation
107-
10875
```bash
10976
# Translate to German
11077
gpt-po-translator --folder ./locales --lang de
111-
```
11278

113-
### Bulk Translation with Language Detection
114-
115-
```bash
116-
# Translate based on folder structure with custom batch size
117-
gpt-po-translator --folder ./locales --lang de,fr --bulk --bulksize 40 --folder-language
79+
# Multiple languages
80+
gpt-po-translator --folder ./locales --lang de,fr,es --bulk
11881
```
11982

120-
### Using Different AI Providers
121-
83+
### Different AI Providers
12284
```bash
123-
# Use Claude models from Anthropic
85+
# Use Claude (Anthropic)
12486
gpt-po-translator --provider anthropic --folder ./locales --lang de
12587

126-
# Use DeepSeek models
88+
# Use DeepSeek
12789
gpt-po-translator --provider deepseek --folder ./locales --lang de
12890

12991
# Use Azure OpenAI
130-
gpt-po-translator --provider azure_openai \
131-
--azure-openai-endpoint https://your-resource.openai.azure.com/ \
132-
--azure-openai-api-version 2024-02-01 \
133-
--folder ./locales --lang de
134-
135-
# List available models for different providers
136-
gpt-po-translator --provider openai --list-models
137-
gpt-po-translator --provider azure_openai \
138-
--azure-openai-endpoint https://your-resource.openai.azure.com/ \
139-
--azure-openai-api-version 2024-02-01 \
140-
--list-models
92+
gpt-po-translator --provider azure_openai --folder ./locales --lang de
14193
```
14294

143-
### AI Translation Tracking
95+
### Docker Usage
96+
```bash
97+
# Basic usage
98+
docker run -v $(pwd):/data \
99+
-e OPENAI_API_KEY="your_key" \
100+
ghcr.io/pescheckit/python-gpt-po:latest \
101+
--folder /data --lang de,fr --bulk
102+
103+
# With Azure OpenAI
104+
docker run -v $(pwd):/data \
105+
-e AZURE_OPENAI_API_KEY="your_key" \
106+
-e AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" \
107+
-e AZURE_OPENAI_API_VERSION="2024-02-01" \
108+
ghcr.io/pescheckit/python-gpt-po:latest \
109+
--provider azure_openai --folder /data --lang de
110+
```
144111

145-
**By default, all AI-generated translations are automatically marked with comments** for easy tracking and compliance:
112+
## 🏷️ AI Translation Tracking
146113

147-
```bash
148-
# Default behavior - AI translations are tagged with comments
149-
gpt-po-translator --folder ./locales --lang de
114+
**All AI translations are automatically tagged** for transparency and compliance:
150115

151-
# Result in PO file:
116+
```po
152117
#. AI-generated
153118
msgid "Hello"
154119
msgstr "Hallo"
155-
156-
# To disable AI tagging (not recommended)
157-
gpt-po-translator --folder ./locales --lang de --no-ai-comment
158120
```
159121

160122
This helps you:
161-
- Identify which translations were made by AI vs human translators
162-
- Track incremental changes when new AI translations are added
163-
- Comply with requirements to identify AI-generated content
123+
- Track which translations are AI vs human-generated
124+
- Comply with AI content disclosure requirements
125+
- Manage incremental translation workflows
164126

165-
**Note:** Django's `makemessages` removes these comments when updating PO files, but translations are preserved. Re-run the translator after `makemessages` to restore AI tagging.
127+
**Note:** Django's `makemessages` removes these comments but preserves translations. Re-run the translator after `makemessages` to restore tags.
166128

167-
## Command Reference
129+
## 📚 Command Reference
168130

169131
| Option | Description |
170132
|--------|-------------|
171-
| `--folder` | Path to your .po files |
172-
| `--lang` | Target language codes (comma-separated, e.g., `de,fr`) |
173-
| `--detail-lang` | Full language names (e.g., `"German,French"`) |
174-
| `--fuzzy` | Remove fuzzy entries before translating (DEPRECATED - use `--fix-fuzzy`) |
175-
| `--fix-fuzzy` | Translate and fix fuzzy entries properly (recommended) |
176-
| `--bulk` | Enable batch translation (recommended for large files) |
133+
| `--folder` | Path to .po files |
134+
| `--lang` | Target languages (e.g., `de,fr,es`) |
135+
| `--provider` | AI provider: `openai`, `azure_openai`, `anthropic`, `deepseek` |
136+
| `--bulk` | Enable batch translation (recommended) |
177137
| `--bulksize` | Entries per batch (default: 50) |
178-
| `--model` | Specific AI model to use |
179-
| `--provider` | AI provider: `openai`, `azure_openai`, `anthropic`, or `deepseek` |
180-
| `--list-models` | Show available models for selected provider |
181-
| `--api_key` | Your API key |
182-
| `--folder-language` | Auto-detect languages from folder structure |
183-
| `--no-ai-comment` | Disable AI-generated comment tagging (enabled by default) |
138+
| `--model` | Specific model to use |
139+
| `--list-models` | Show available models |
140+
| `--fix-fuzzy` | Translate fuzzy entries |
141+
| `--folder-language` | Auto-detect languages from folders |
142+
| `--no-ai-comment` | Disable AI tagging |
184143

185-
## Advanced Docker Usage
186-
187-
### Specific Python Versions
144+
## 🛠️ Development
188145

146+
### Build Docker Locally
189147
```bash
190-
# Python 3.11 (default)
191-
docker pull ghcr.io/pescheckit/python-gpt-po:latest
192-
193-
# Python 3.12
194-
docker pull ghcr.io/pescheckit/python-gpt-po:latest-py3.12
195-
196-
# Specific version
197-
docker pull ghcr.io/pescheckit/python-gpt-po:0.3.0
148+
git clone https://github.com/pescheckit/python-gpt-po.git
149+
cd python-gpt-po
150+
docker build -t python-gpt-po .
198151
```
199152

200-
### Volume Mounting
201-
202-
Mount any local directory to use in the container:
203-
153+
### Run Tests
204154
```bash
205-
# Windows example with OpenAI
206-
docker run -v D:/projects/website/locales:/locales \
207-
-e OPENAI_API_KEY="your_key" \
208-
ghcr.io/pescheckit/python-gpt-po:latest \
209-
--folder /locales --lang fr,de --bulk
155+
# Local
156+
python -m pytest
210157

211-
# Mac/Linux example with Azure OpenAI
212-
docker run -v /Users/username/translations:/input \
213-
-e AZURE_OPENAI_API_KEY="your_key" \
214-
-e AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" \
215-
-e AZURE_OPENAI_API_VERSION="2024-02-01" \
216-
ghcr.io/pescheckit/python-gpt-po:latest \
217-
--provider azure_openai --folder /input --lang fr,de --bulk
158+
# Docker
159+
docker run --rm -v $(pwd):/app -w /app --entrypoint python python-gpt-po -m pytest -v
218160
```
219161

220-
## Requirements
221-
222-
- Python 3.9+ (3.9, 3.10, 3.11, or 3.12)
223-
- Core dependencies:
224-
- polib
225-
- openai
226-
- tenacity
227-
- python-dotenv
228-
229-
## Development
162+
## 📋 Requirements
230163

231-
### Running Tests
232-
233-
```bash
234-
python -m pytest
235-
```
236-
```bash
237-
docker run --rm -v $(pwd):/app -w /app --entrypoint python python-gpt-po -m pytest -v
238-
```
164+
- Python 3.8+
165+
- Dependencies: `polib`, `openai`, `anthropic`, `requests`, `tenacity`
239166

240-
## Documentation
167+
## 📖 Documentation
241168

242-
For more detailed information:
243-
- **[Advanced Usage Guide](docs/usage.md)** - Comprehensive guide with all options and internal mechanics
244-
- **[Development Guide](docs/development.md)** - For contributors
245-
- **[GitHub Repository](https://github.com/pescheckit/python-gpt-po)** - Source code and issues
169+
- **[Advanced Usage Guide](docs/usage.md)** - Comprehensive options and mechanics
170+
- **[Development Guide](docs/development.md)** - Contributing guidelines
171+
- **[GitHub Issues](https://github.com/pescheckit/python-gpt-po/issues)** - Bug reports and feature requests
246172

247-
## License
173+
## 📄 License
248174

249-
MIT License - See the [LICENSE](LICENSE) file for details.
175+
MIT License - See [LICENSE](LICENSE) for details.

‎docs/usage.md‎

Lines changed: 1 addition & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ Below is a detailed explanation of all command-line arguments:
121121

122122
- **`--fix-fuzzy`**
123123
*Description:* Translate and clean fuzzy entries safely (recommended over `--fuzzy`).
124-
*Behind the scenes:* The tool filters for entries with the 'fuzzy' flag and attempts to translate them, removing the flag upon successful translation. AI-generated translations are marked as usual unless `--no-ai-comment` is used.
124+
*Behind the scenes:* The tool filters for entries with the 'fuzzy' flag and attempts to translate them, removing the flag upon successful translation.
125125

126126
- **`--bulk`**
127127
*Description:* Enables bulk translation mode, meaning multiple texts will be translated in a single API call.
@@ -231,25 +231,6 @@ If you don't want AI translations to be marked, use the `--no-ai-comment` flag:
231231
gpt-po-translator --folder ./locales --lang de --no-ai-comment
232232
```
233233

234-
### Programmatic Access
235-
236-
The tool provides helper methods for working with AI-generated translations programmatically:
237-
238-
```python
239-
from python_gpt_po.services.po_file_handler import POFileHandler
240-
import polib
241-
242-
# Load a PO file
243-
po_file = polib.pofile('messages.po')
244-
245-
# Get all AI-generated entries
246-
ai_entries = POFileHandler.get_ai_generated_entries(po_file)
247-
248-
# Remove AI-generated comments if needed
249-
POFileHandler.remove_ai_generated_comments(po_file)
250-
po_file.save()
251-
```
252-
253234
---
254235

255236
## Behind the Scenes: API Calls and Post-Processing

0 commit comments

Comments
 (0)