Skip to content

Commit 0310b02

Browse files
pescheck-brampescheck-bram
authored
Merge pull request #38 from pescheckit/pescheck-bram-patch-1
Update README.md
2 parents 51665a4 + e5eca02 commit 0310b02

File tree

1 file changed

+111
-133
lines changed

1 file changed

+111
-133
lines changed

‎README.md

Lines changed: 111 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -1,213 +1,191 @@
1-
# Python GPT-4 PO File Translator
1+
# GPT-PO Translator
22

33
[![Python Package CI](https://github.com/pescheckit/python-gpt-po/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/pescheckit/python-gpt-po/actions/workflows/ci-cd.yml)
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, 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.9-3.12.
7+
> Translate your gettext (.po) files with AI - supports OpenAI, Anthropic/Claude, and DeepSeek
88
9-
## Features
9+
## What is GPT-PO Translator?
1010

11-
- **Multi-Provider Support:** Integrates with OpenAI, Anthropic / Claude, and DeepSeek.
12-
- **Bulk & Individual Modes:** Translate entire files in batches or process entries one by one.
13-
- **Fuzzy Entry Management:** Automatically removes fuzzy entries to ensure clean translations.
14-
- **Folder-Based Language Inference:** Detects the target language from directory structure.
15-
- **Customizable Batch Size:** Configure the number of entries per translation request.
16-
- **Retry & Validation:** Automatic retries and validation to ensure concise, correct translations.
17-
- **Detailed Logging:** Transparent logging for progress monitoring and debugging.
18-
- **Flexible API Key Configuration:** Supply API keys via environment variables or command-line arguments.
19-
- **Detailed Language Option:** Use full language names (e.g., "German") for clearer prompts alongside language codes (e.g., de).
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.
2012

21-
## Requirements
13+
### Key Features
2214

23-
- Python 3.9+ (Python 3.9, 3.10, 3.11, and 3.12 are officially supported)
24-
- [polib](https://pypi.org/project/polib/)
25-
- [openai](https://pypi.org/project/openai/)
26-
- [tenacity](https://pypi.org/project/tenacity/)
27-
- [python-dotenv](https://pypi.org/project/python-dotenv/)
15+
- **Multiple AI providers** - 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+
- **Production-ready** - Includes retry logic, validation, and detailed logging
19+
- **Easy deployment** - Available as a Python package or Docker container
20+
- **Cross-version support** - Works with Python 3.9-3.12
2821

29-
## Installation
22+
## Getting Started
3023

31-
### Via PyPI
24+
### Quick Install
3225

3326
```bash
3427
pip install gpt-po-translator
3528
```
3629

37-
### Manual Installation
30+
### Basic Usage
31+
32+
```bash
33+
# Set up your API key
34+
export OPENAI_API_KEY='your_api_key_here'
35+
36+
# Translate files to German and French
37+
gpt-po-translator --folder ./locales --lang de,fr --bulk
38+
```
3839

39-
Clone the repository and install the package:
40+
## Installation Options
41+
42+
### PyPI (Recommended)
43+
44+
```bash
45+
pip install gpt-po-translator
46+
```
47+
48+
### Manual Installation
4049

4150
```bash
4251
git clone https://github.com/pescheckit/python-gpt-po.git
4352
cd python-gpt-po
4453
python3 -m venv .venv
4554
source .venv/bin/activate
4655
pip install -r requirements.txt
47-
python -m python_gpt_po.main --provider="deepseek" --list-models
4856
```
4957

50-
## API Key Configuration
58+
### Docker
5159

52-
You can provide your API key in two ways:
60+
```bash
61+
# Pull the latest image
62+
docker pull ghcr.io/pescheckit/python-gpt-po:latest
5363

54-
### Environment Variable
64+
# Run with your local directory mounted
65+
docker run -v $(pwd):/data \
66+
-e OPENAI_API_KEY="your_key" \
67+
ghcr.io/pescheckit/python-gpt-po:latest \
68+
--folder /data --lang fr,de --bulk
69+
```
70+
71+
## Setting Up API Keys
5572

56-
Set your OpenAI API key:
73+
### Option 1: Environment Variables
5774

5875
```bash
5976
export OPENAI_API_KEY='your_api_key_here'
77+
# Or for other providers:
78+
export ANTHROPIC_API_KEY='your_api_key_here'
79+
export DEEPSEEK_API_KEY='your_api_key_here'
6080
```
6181

62-
### Command-Line Argument
63-
64-
Pass your API key directly when invoking the tool:
82+
### Option 2: Command Line
6583

6684
```bash
67-
gpt-po-translator --folder ./locales --lang de,fr --api_key 'your_api_key_here' --bulk --bulksize 100 --folder-language
85+
gpt-po-translator --api_key 'your_api_key_here' [other options]
6886
```
6987

70-
## Usage
88+
## Usage Examples
7189

72-
Run the tool from the command line to translate your .po files:
90+
### Basic Translation
7391

7492
```bash
75-
gpt-po-translator --folder <path_to_po_files> --lang <language_codes> [options]
93+
# Translate to German
94+
gpt-po-translator --folder ./locales --lang de
7695
```
7796

78-
### Example
79-
80-
Translate .po files in the `./locales` folder to German and French:
97+
### Bulk Translation with Language Detection
8198

8299
```bash
83-
gpt-po-translator --folder ./locales --lang de,fr --api_key 'your_api_key_here' --bulk --bulksize 40 --folder-language --detail-lang "German,French"
100+
# Translate based on folder structure with custom batch size
101+
gpt-po-translator --folder ./locales --lang de,fr --bulk --bulksize 40 --folder-language
84102
```
85103

86-
## Documentation
87-
88-
For a detailed explanation of all available parameters and a deep dive into the internal workings of the tool, please see our [Advanced Usage Guide](docs/usage.md).
89-
90-
## Command-Line Options
91-
92-
- `--folder`: Path to the directory containing .po files.
93-
- `--lang`: Comma-separated target language codes (e.g., de,fr).
94-
- `--detail-lang`: Comma-separated full language names corresponding to the codes (e.g., "German,French").
95-
- `--fuzzy`: Remove fuzzy entries before processing.
96-
- `--bulk`: Enable bulk translation mode.
97-
- `--bulksize`: Set the number of entries per bulk translation (default is 50).
98-
- `--model`: Specify the translation model (defaults are provider-specific).
99-
- `--provider`: Specify the AI provider (openai, anthropic, or deepseek).
100-
- `--list-models`: List available models for the selected provider. This is the only command that can be used without `--folder` and `--lang`.
101-
- `--api_key`: API key for translation; can also be provided via environment variable.
102-
- `--folder-language`: Infer the target language from the folder structure.
103-
104-
## Logging & Error Handling
105-
106-
- **Logging:** Detailed logs track the translation process and help with debugging.
107-
- **Error Handling:** The tool automatically retries failed translations (up to three times) and validates output to prevent overly verbose responses.
104+
### Using Different AI Providers
108105

109-
## Testing
106+
```bash
107+
# Use Claude models from Anthropic
108+
gpt-po-translator --provider anthropic --folder ./locales --lang de
110109

111-
To run all tests:
110+
# Use DeepSeek models
111+
gpt-po-translator --provider deepseek --folder ./locales --lang de
112112

113-
```bash
114-
python -m pytest
113+
# List available models
114+
gpt-po-translator --provider openai --list-models
115115
```
116116

117-
## Using Docker
117+
## Command Reference
118118

119-
You can use this tool without installing Python on your local machine by running it in a Docker container.
119+
| Option | Description |
120+
|--------|-------------|
121+
| `--folder` | Path to your .po files |
122+
| `--lang` | Target language codes (comma-separated, e.g., `de,fr`) |
123+
| `--detail-lang` | Full language names (e.g., `"German,French"`) |
124+
| `--fuzzy` | Remove fuzzy entries before translating |
125+
| `--bulk` | Enable batch translation (recommended for large files) |
126+
| `--bulksize` | Entries per batch (default: 50) |
127+
| `--model` | Specific AI model to use |
128+
| `--provider` | AI provider: `openai`, `anthropic`, or `deepseek` |
129+
| `--list-models` | Show available models for selected provider |
130+
| `--api_key` | Your API key |
131+
| `--folder-language` | Auto-detect languages from folder structure |
120132

121-
### Using Pre-built Container
133+
## Advanced Docker Usage
122134

123-
Pull the latest container from GitHub Container Registry (defaults to Python 3.11):
135+
### Specific Python Versions
124136

125137
```bash
126-
docker pull ghcr.io/pescheckit/python-gpt-po:latest # Uses Python 3.11 by default
127-
```
138+
# Python 3.11 (default)
139+
docker pull ghcr.io/pescheckit/python-gpt-po:latest
128140

129-
You can also use a specific version tag for consistency, or specify a Python version:
141+
# Python 3.12
142+
docker pull ghcr.io/pescheckit/python-gpt-po:latest-py3.12
130143

131-
```bash
132-
docker pull ghcr.io/pescheckit/python-gpt-po:0.3.0 # Latest version
133-
docker pull ghcr.io/pescheckit/python-gpt-po:0.3.0-py3.11 # Python 3.11 specific
134-
docker pull ghcr.io/pescheckit/python-gpt-po:latest-py3.12 # Latest with Python 3.12
144+
# Specific version
145+
docker pull ghcr.io/pescheckit/python-gpt-po:0.3.0
135146
```
136147

137-
Run the container with any local directory mounted to any path inside the container:
148+
### Volume Mounting
138149

139-
```bash
140-
# Mount current directory to /data in container
141-
docker run -v $(pwd):/data \
142-
-e OPENAI_API_KEY="your_openai_key" \
143-
ghcr.io/pescheckit/python-gpt-po:latest \
144-
--folder /data --lang fr,de --bulk
150+
Mount any local directory to use in the container:
145151

146-
# Mount a specific absolute path to /translations in container
147-
docker run -v /home/user/my-translations:/translations \
148-
-e OPENAI_API_KEY="your_openai_key" \
149-
ghcr.io/pescheckit/python-gpt-po:latest \
150-
--folder /translations --lang fr,de --bulk
151-
152-
# Mount from a different drive or location on Windows
152+
```bash
153+
# Windows example
153154
docker run -v D:/projects/website/locales:/locales \
154-
-e OPENAI_API_KEY="your_openai_key" \
155+
-e OPENAI_API_KEY="your_key" \
155156
ghcr.io/pescheckit/python-gpt-po:latest \
156157
--folder /locales --lang fr,de --bulk
157-
158-
# On Mac/Linux, mount from any location
159-
docker run -v /Users/username/Documents/translations:/input \
160-
-e OPENAI_API_KEY="your_openai_key" \
161-
ghcr.io/pescheckit/python-gpt-po:latest \
162-
--folder /input --lang fr,de --bulk
163-
164-
# Multiple volumes can be mounted if needed
165-
docker run \
166-
-v /path/to/source:/input \
167-
-v /path/to/output:/output \
168-
-e OPENAI_API_KEY="your_openai_key" \
158+
159+
# Mac/Linux example
160+
docker run -v /Users/username/translations:/input \
161+
-e OPENAI_API_KEY="your_key" \
169162
ghcr.io/pescheckit/python-gpt-po:latest \
170163
--folder /input --lang fr,de --bulk
171164
```
172165

173-
Running without arguments will display usage help:
174-
175-
```bash
176-
docker run ghcr.io/pescheckit/python-gpt-po:latest
177-
```
166+
## Requirements
178167

179-
Quick reference - copy & paste commands:
168+
- Python 3.9+ (3.9, 3.10, 3.11, or 3.12)
169+
- Core dependencies:
170+
- polib
171+
- openai
172+
- tenacity
173+
- python-dotenv
180174

181-
```bash
182-
# Help text
183-
docker run ghcr.io/pescheckit/python-gpt-po:latest
175+
## Development
184176

185-
# Translate current directory files to French
186-
docker run -v $(pwd):/data -e OPENAI_API_KEY="your_key" ghcr.io/pescheckit/python-gpt-po:latest --folder /data --lang fr
177+
### Running Tests
187178

188-
# Use a specific Python version (3.12)
189-
docker run -v $(pwd):/data -e OPENAI_API_KEY="your_key" ghcr.io/pescheckit/python-gpt-po:latest-py3.12 --folder /data --lang fr
190-
191-
# List available models (no need for --folder or --lang)
192-
docker run -e OPENAI_API_KEY="your_key" ghcr.io/pescheckit/python-gpt-po:latest --provider openai --list-models
179+
```bash
180+
python -m pytest
193181
```
194182

195-
### Volume Mount Explanation
196-
197-
The `-v` flag uses the format: `-v /host/path:/container/path`
198-
199-
- `/host/path` can be any directory on your system
200-
- `/container/path` is where the directory appears inside the container
201-
- Use the `/container/path` with the `--folder` parameter
183+
## Documentation
202184

203-
For example, if you mount with `-v ~/translations:/data`, then use `--folder /data` in your command.
185+
For advanced usage and detailed documentation, please see:
186+
- [Advanced Usage Guide](docs/usage.md)
187+
- [GitHub Repository](https://github.com/pescheckit/python-gpt-po)
204188

205189
## License
206190

207-
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
208-
209-
## About
210-
211-
Powered by state-of-the-art AI models (including OpenAI’s GPT-4 and GPT-3.5), this tool is designed to streamline the localization process for .po files. Whether you need to process large batches or handle specific entries, the Python GPT-4 PO File Translator adapts to your translation needs.
212-
213-
For more details, contributions, or bug reports, please visit our [GitHub repository](https://github.com/pescheckit/python-gpt-po).
191+
MIT License - See the [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)