Merge pull request #64 from pescheckit/feature_added-ollama

Feature added ollama

Author: pescheck-bram

README.md

@@ -4,7 +4,7 @@
 ![PyPI](https://img.shields.io/pypi/v/gpt-po-translator?label=gpt-po-translator)
 ![Downloads](https://pepy.tech/badge/gpt-po-translator)
 
-**Translate gettext (.po) files using AI models.** Supports OpenAI, Azure OpenAI, Anthropic/Claude, and DeepSeek with automatic AI translation tagging.
+**Translate gettext (.po) files using AI models.** Supports OpenAI, Azure OpenAI, Anthropic/Claude, DeepSeek, and Ollama (local) with automatic AI translation tagging.
 
 ## 🚀 Quick Start
 
@@ -21,7 +21,8 @@ gpt-po-translator --folder ./locales --bulk
 
 ## ✨ Key Features
 
-- **Multiple AI providers** - OpenAI, Azure OpenAI, Anthropic/Claude, DeepSeek
+- **Multiple AI providers** - OpenAI, Azure OpenAI, Anthropic/Claude, DeepSeek, and Ollama (local)
+- **Privacy option** - Use Ollama for local, offline translations with no cloud API
 - **AI translation tracking** - Auto-tags AI-generated translations with `#. AI-generated` comments
 - **Bulk processing** - Efficient batch translation for large files
 - **Smart language detection** - Auto-detects target languages from folder structure
@@ -49,7 +50,7 @@ pip install -e .
 
 ## 🔧 Setup
 
-### API Keys
+### API Keys (Cloud Providers)
 
 Choose your AI provider and set the corresponding API key:
 
@@ -69,6 +70,26 @@ export AZURE_OPENAI_ENDPOINT='https://your-resource.openai.azure.com/'
 export AZURE_OPENAI_API_VERSION='2024-02-01'
 ```
 
+### Or Use Ollama (Local, No API Key Needed)
+
+```bash
+# 1. Install Ollama
+curl -fsSL https://ollama.com/install.sh | sh
+
+# 2. Pull a model
+ollama pull qwen2.5    # Best for multilingual (Arabic, Chinese, etc.)
+# OR
+ollama pull llama3.2   # Fast for European languages
+
+# 3. Translate (no API key required!)
+gpt-po-translator --provider ollama --folder ./locales
+
+# For non-Latin scripts, use qwen2.5 WITHOUT --bulk
+gpt-po-translator --provider ollama --model qwen2.5 --folder ./locales --lang ar
+```
+
+> **💡 Important:** For Ollama with **non-Latin languages** (Arabic, Chinese, Japanese, etc.), **omit the `--bulk` flag**. Single-item translation is more reliable because the model doesn't have to format responses as JSON.
+
 ## 💡 Usage Examples
 
 ### Basic Translation
@@ -93,16 +114,28 @@ gpt-po-translator --provider deepseek --folder ./locales --lang de
 
 # Use Azure OpenAI with auto-detection
 gpt-po-translator --provider azure_openai --folder ./locales --bulk
+
+# Use Ollama (local, private, free) - omit --bulk for non-Latin scripts
+gpt-po-translator --provider ollama --folder ./locales
 ```
 
 ### Docker Usage
 ```bash
-# Basic usage
+# Basic usage with OpenAI
 docker run -v $(pwd):/data \
   -e OPENAI_API_KEY="your_key" \
   ghcr.io/pescheckit/python-gpt-po:latest \
   --folder /data --bulk
 
+# With Ollama (local, no API key needed)
+# Note: Omit --bulk for better quality with non-Latin scripts
+docker run --rm \
+  -v $(pwd):/data \
+  --network host \
+  ghcr.io/pescheckit/python-gpt-po:latest \
+  --provider ollama \
+  --folder /data
+
 # With Azure OpenAI
 docker run -v $(pwd):/data \
   -e AZURE_OPENAI_API_KEY="your_key" \
@@ -135,14 +168,16 @@ This helps you:
 |--------|-------------|
 | `--folder` | Path to .po files |
 | `--lang` | Target languages (e.g., `de,fr,es`, `fr_CA`, `pt_BR`) |
-| `--provider` | AI provider: `openai`, `azure_openai`, `anthropic`, `deepseek` |
+| `--provider` | AI provider: `openai`, `azure_openai`, `anthropic`, `deepseek`, `ollama` |
 | `--bulk` | Enable batch translation (recommended for large files) |
 | `--bulksize` | Entries per batch (default: 50) |
 | `--model` | Specific model to use |
 | `--list-models` | Show available models |
 | `--fix-fuzzy` | Translate fuzzy entries |
 | `--folder-language` | Auto-detect languages from folders |
 | `--no-ai-comment` | Disable AI tagging |
+| `--ollama-base-url` | Ollama server URL (default: `http://localhost:11434`) |
+| `--ollama-timeout` | Ollama timeout in seconds (default: 120) |
 | `-v, --verbose` | Show progress information (use `-vv` for debug) |
 | `-q, --quiet` | Only show errors |
 | `--version` | Show version and exit |

docs/usage.md

@@ -426,6 +426,251 @@ gpt-po-translator --folder ./locales --lang de --no-ai-comment
 
 ---
 
+## Using Ollama (Local AI Provider)
+
+### Overview
+
+Ollama allows you to run AI models locally on your machine, providing:
+- **Privacy**: All translations happen locally, no data sent to cloud services
+- **Cost**: No API fees - completely free
+- **Offline**: Works without internet connection
+- **Control**: Full control over model and infrastructure
+
+### Prerequisites
+
+1. **Install Ollama**
+   ```bash
+   # macOS/Linux
+   curl -fsSL https://ollama.com/install.sh | sh
+
+   # Or download from https://ollama.com
+   ```
+
+2. **Pull a model**
+   ```bash
+   # For multilingual (Arabic, Chinese, etc.)
+   ollama pull qwen2.5
+
+   # For European languages only
+   ollama pull llama3.2
+
+   # Other options
+   ollama pull llama3.1   # Better quality, slower
+   ollama pull mistral    # Good for European languages
+   ```
+
+3. **Start Ollama** (if not already running)
+   ```bash
+   ollama serve
+   ```
+
+### Basic Usage
+
+```bash
+# Latin scripts (English, French, Spanish, etc.) - can use bulk mode
+gpt-po-translator --provider ollama --folder ./locales --bulk
+
+# Non-Latin scripts (Arabic, Chinese, Japanese, etc.) - omit --bulk for better quality
+gpt-po-translator --provider ollama --model qwen2.5 --folder ./locales --lang ar
+
+# Specify a model
+gpt-po-translator --provider ollama --model llama3.1 --folder ./locales
+
+# List available models
+gpt-po-translator --provider ollama --list-models
+```
+
+> **⚠️ Important:** For **non-Latin languages**, **omit the `--bulk` flag**. Local models struggle with JSON formatting for Arabic/Chinese/etc., resulting in poor translation quality or errors. Single-item mode is more reliable.
+
+### Configuration
+
+#### Option 1: Environment Variable
+
+```bash
+export OLLAMA_BASE_URL="http://localhost:11434"
+gpt-po-translator --provider ollama --folder ./locales --bulk
+```
+
+#### Option 2: CLI Arguments
+
+```bash
+# Custom port
+gpt-po-translator --provider ollama \
+  --ollama-base-url http://localhost:8080 \
+  --folder ./locales --bulk
+
+# Increase timeout for slow models
+gpt-po-translator --provider ollama \
+  --ollama-timeout 300 \
+  --folder ./locales --bulk
+```
+
+#### Option 3: Config File
+
+Add to your `pyproject.toml`:
+
+```toml
+[tool.gpt-po-translator.provider.ollama]
+base_url = "http://localhost:11434"
+model = "llama3.2"
+timeout = 120
+
+[tool.gpt-po-translator]
+bulk_mode = true
+bulk_size = 50
+```
+
+Then simply run:
+```bash
+gpt-po-translator --provider ollama --folder ./locales
+```
+
+### Advanced Scenarios
+
+#### Remote Ollama Server
+
+Run Ollama on a different machine:
+
+```bash
+# On the Ollama server (192.168.1.100)
+ollama serve --host 0.0.0.0
+
+# On your machine
+gpt-po-translator --provider ollama \
+  --ollama-base-url http://192.168.1.100:11434 \
+  --folder ./locales --bulk
+```
+
+Or set in `pyproject.toml`:
+```toml
+[tool.gpt-po-translator.provider.ollama]
+base_url = "http://192.168.1.100:11434"
+```
+
+#### Docker with Ollama
+
+Run Ollama on your host machine, then use Docker with `--network host`:
+
+```bash
+# 1. Start Ollama on host
+ollama serve
+
+# 2. Pull a model on host
+ollama pull qwen2.5
+
+# 3. Run translator in Docker (Linux/macOS)
+docker run --rm \
+  -v $(pwd):/data \
+  --network host \
+  ghcr.io/pescheckit/python-gpt-po:latest \
+  --provider ollama \
+  --folder /data
+
+# macOS/Windows Docker Desktop: use host.docker.internal
+docker run --rm \
+  -v $(pwd):/data \
+  ghcr.io/pescheckit/python-gpt-po:latest \
+  --provider ollama \
+  --ollama-base-url http://host.docker.internal:11434 \
+  --folder /data
+```
+
+**With config file:**
+```bash
+# Add Ollama config to pyproject.toml in your project
+docker run --rm \
+  -v $(pwd):/data \
+  -v $(pwd)/pyproject.toml:/data/pyproject.toml \
+  --network host \
+  ghcr.io/pescheckit/python-gpt-po:latest \
+  --provider ollama \
+  --folder /data
+```
+
+### Performance Considerations
+
+**Pros:**
+- No API costs
+- Privacy and data control
+- No rate limits
+- Offline capability
+
+**Cons:**
+- Quality varies by model (may not match GPT-4)
+- Requires local resources (RAM, GPU recommended)
+- Initial setup needed (install Ollama, pull models)
+
+**Performance Tips:**
+1. **Use GPU**: Install Ollama with GPU support for 10-100x speedup
+2. **Choose appropriate models**:
+   - Small projects: `llama3.2` (fast, good quality)
+   - Better quality: `llama3.1` (slower, better accuracy)
+   - Multilingual: `qwen2.5` (excellent for non-Latin scripts like Arabic, Chinese, etc.)
+   - Specialized: `mistral`, `gemma2`
+3. **Increase timeout** for large models: `--ollama-timeout 300`
+4. **Bulk mode vs Single mode**:
+   - **Bulk mode (`--bulk`)**: Faster but requires model to return valid JSON - recommended for cloud providers
+   - **Single mode (no `--bulk`)**: Slower but more reliable for local models, especially with non-Latin scripts
+   - For Ollama with languages like Arabic/Chinese/Japanese, **omit `--bulk`** for better quality
+
+### Recommended Models for Translation
+
+| Model | Size | Speed | Quality | Best For |
+|-------|------|-------|---------|----------|
+| `llama3.2` | 3B | ⚡⚡⚡ Fast | ⭐⭐⭐ Good | General use, Latin scripts only |
+| `llama3.1` | 8B | ⚡⚡ Medium | ⭐⭐⭐⭐ Better | Better quality, medium projects |
+| `qwen2.5` | 7B | ⚡⚡ Medium | ⭐⭐⭐⭐ Excellent | **Multilingual** (Arabic, Chinese, etc.) |
+| `mistral` | 7B | ⚡⚡ Medium | ⭐⭐⭐ Good | European languages |
+| `gemma2` | 9B | ⚡ Slower | ⭐⭐⭐⭐ Better | High quality translations |
+
+**Note:** For non-Latin scripts (Arabic, Chinese, Japanese, etc.), use `qwen2.5` or larger models **without `--bulk` flag** for best results.
+
+### Troubleshooting
+
+**"Cannot connect to Ollama"**
+```bash
+# Check if Ollama is running
+curl http://localhost:11434/api/tags
+
+# Start Ollama
+ollama serve
+
+# Check if running on different port
+ollama serve --help
+```
+
+**Slow translations**
+- Use GPU-enabled Ollama installation
+- Choose a smaller model (`llama3.2` instead of `llama3.1`)
+- Increase `--bulksize` to batch more entries together
+- Close other applications to free up RAM
+
+**Model not found**
+```bash
+# List installed models
+ollama list
+
+# Pull the model
+ollama pull llama3.2
+```
+
+**Timeout errors**
+```bash
+# Increase timeout
+gpt-po-translator --provider ollama --ollama-timeout 300 --folder ./locales
+```
+
+### Configuration Priority
+
+Ollama settings are loaded in this order (highest to lowest):
+
+1. **CLI arguments**: `--ollama-base-url`, `--ollama-timeout`
+2. **Environment variables**: `OLLAMA_BASE_URL`
+3. **Config file**: `pyproject.toml` under `[tool.gpt-po-translator.provider.ollama]`
+4. **Defaults**: `http://localhost:11434`, timeout `120s`
+
+---
+
 ## Whitespace Handling in Translations
 
 ### Overview

python_gpt_po/models/enums.py

@@ -11,6 +11,7 @@ class ModelProvider(Enum):
     ANTHROPIC = "anthropic"
     DEEPSEEK = "deepseek"
     AZURE_OPENAI = "azure_openai"
+    OLLAMA = "ollama"
 
 
 ModelProviderList = [provider.value for provider in ModelProvider]