Merge pull request #66 from pescheckit/feature/configurable-default-context

Add configurable default context via CLI and environment variables

Author: pescheck-bram

README.md

@@ -142,6 +142,28 @@ The tool extracts context from your PO files and passes it to the AI for more ac
 
 **Tip:** Use detailed context for best results: `msgctxt "status label (not verb)"` works better than just `msgctxt "status"`.
 
+### Default Context
+
+Provide a default context for entries without `msgctxt`:
+
+```bash
+# Via command-line
+gpt-po-translator --folder ./locales --default-context "web application" --bulk
+
+# Via environment variable
+export GPT_TRANSLATOR_CONTEXT="mobile app for iOS"
+gpt-po-translator --folder ./locales --bulk
+
+# Via pyproject.toml
+# Add to your pyproject.toml:
+[tool.gpt-po-translator]
+default_context = "e-commerce checkout flow"
+```
+
+**Priority:** CLI argument > Environment variable > Config file
+
+The default context is applied to entries without explicit `msgctxt`, while entries with `msgctxt` always take precedence.
+
 ## 🏷️ AI Translation Tracking
 
 **All AI translations are automatically tagged** for transparency and compliance:
@@ -172,6 +194,7 @@ This helps you:
 | `--list-models` | Show available models |
 | `--fix-fuzzy` | Translate fuzzy entries |
 | `--folder-language` | Auto-detect languages from folders |
+| `--default-context` | Default translation context for entries without msgctxt |
 | `--no-ai-comment` | Disable AI tagging |
 | `--ollama-base-url` | Ollama server URL (default: `http://localhost:11434`) |
 | `--ollama-timeout` | Ollama timeout in seconds (default: 120) |

docs/usage.md

@@ -171,13 +171,20 @@ Below is a detailed explanation of all command-line arguments:
   *Description:* Provides the DeepSeek API key directly.  
   *Behind the scenes:* This key is required to make API calls to DeepSeek’s translation service.
 
-- **`--folder-language`**  
-  *Description:* Enables inferring the target language from the folder structure.  
+- **`--folder-language`**
+  *Description:* Enables inferring the target language from the folder structure.
   *Behind the scenes:* The tool inspects the path components (directory names) of each PO file and matches them against the provided language codes. Supports locale codes (e.g., folder `fr_CA` matches `-l fr_CA` for Canadian French, or falls back to `-l fr` for standard French).
 
-- **`--no-ai-comment`**  
-  *Description:* Disables the automatic addition of 'AI-generated' comments to translated entries.  
-  *Behind the scenes:* **By default (without this flag), every translation made by the AI is marked with a `#. AI-generated` comment in the PO file.** This flag prevents that marking, making AI translations indistinguishable from human translations in the file.  
+- **`--default-context CONTEXT`**
+  *Description:* Sets a default translation context for entries without `msgctxt`.
+  *Behind the scenes:* When the tool encounters PO entries without explicit `msgctxt` context, it applies this default context to provide additional information to the AI. Entries with explicit `msgctxt` always take precedence. Can also be set via the `GPT_TRANSLATOR_CONTEXT` environment variable or `default_context` in `pyproject.toml`.
+  *Priority:* CLI argument > Environment variable > Config file
+  *Example:* `--default-context "web application UI"` helps the AI understand the context for all translations without specific msgctxt.
+  *Note:* Use descriptive context (e.g., "e-commerce product page" rather than just "web") for best results.
+
+- **`--no-ai-comment`**
+  *Description:* Disables the automatic addition of 'AI-generated' comments to translated entries.
+  *Behind the scenes:* **By default (without this flag), every translation made by the AI is marked with a `#. AI-generated` comment in the PO file.** This flag prevents that marking, making AI translations indistinguishable from human translations in the file.
   *Note:* AI tagging is enabled by default for tracking, compliance, and quality assurance purposes.
 
 - **`-v, --verbose`**  
@@ -777,6 +784,54 @@ Translate to German: Save
 
 Result: **"Speichern"** (button action) instead of **"Sparen"** (to save money)
 
+### Default Context
+
+For entries without explicit `msgctxt`, you can provide a default context that applies to all translations:
+
+#### Configuration Methods
+
+**1. Command-Line Argument (highest priority):**
+```bash
+gpt-po-translator --folder ./locales --default-context "web application" --bulk
+```
+
+**2. Environment Variable:**
+```bash
+export GPT_TRANSLATOR_CONTEXT="mobile app for iOS"
+gpt-po-translator --folder ./locales --bulk
+```
+
+**3. Configuration File (pyproject.toml):**
+```toml
+[tool.gpt-po-translator]
+default_context = "e-commerce checkout flow"
+```
+
+#### Priority Order
+CLI argument > Environment variable > Config file
+
+#### Behavior
+- Entries **with** `msgctxt` → Uses the explicit `msgctxt` (always takes precedence)
+- Entries **without** `msgctxt` → Uses the default context
+- No default context configured → No context provided (original behavior)
+
+#### Example
+```bash
+gpt-po-translator --folder ./locales --default-context "medical device interface" --lang de
+```
+
+With this setup:
+```po
+# Entry WITH msgctxt - uses "button"
+msgctxt "button"
+msgid "Start"
+msgstr ""  → "Starten" (button action)
+
+# Entry WITHOUT msgctxt - uses default "medical device interface"
+msgid "Start"
+msgstr ""  → "Start" (medical procedure start, preserving technical term)
+```
+
 ### Best Practices
 
 **✓ Good - Detailed, Explicit Context:**
@@ -796,7 +851,9 @@ msgstr ""  → "Halten" (may still be wrong)
 **Key Points:**
 - **Be explicit** - Describe what you want AND what you don't want
 - **Provide examples** - Include similar terms or expected word forms
-- **Human review still needed** - msgctxt improves results but doesn't guarantee perfection
+- **Use default context for project-wide context** - Helps all translations understand domain (e.g., "legal contract", "gaming UI", "medical records")
+- **Use msgctxt for specific terms** - Override default with specific context when needed
+- **Human review still needed** - Context improves results but doesn't guarantee perfection
 
 ---
 

python_gpt_po/main.py

@@ -6,6 +6,7 @@
 from __future__ import annotations
 
 import logging
+import os
 import sys
 import traceback
 from argparse import Namespace
@@ -20,6 +21,7 @@
 from .services.translation_service import TranslationService
 from .utils.cli import (auto_select_provider, create_language_mapping, get_provider_from_args, parse_args,
                         show_help_and_exit, validate_provider_key)
+from .utils.config_loader import ConfigLoader
 
 
 def setup_logging(verbose: int = 0, quiet: bool = False):
@@ -218,6 +220,20 @@ def main():
             logging.warning(
                 "Note: --fuzzy flag is deprecated. Use --fix-fuzzy for safer fuzzy entry handling."
             )
+
+        # Get default context: Priority is CLI arg > Env var > Config file
+        default_context = None
+        if hasattr(args, 'default_context') and args.default_context:
+            default_context = args.default_context
+        elif os.getenv('GPT_TRANSLATOR_CONTEXT'):
+            default_context = os.getenv('GPT_TRANSLATOR_CONTEXT')
+        else:
+            # Try to get from config file
+            default_context = ConfigLoader.get_default_context(args.folder)
+
+        if default_context:
+            logging.info("Using default translation context: %s", default_context)
+
         # Create translation configuration
         flags = TranslationFlags(
             bulk_mode=args.bulk,
@@ -230,7 +246,8 @@ def main():
             provider_clients=provider_clients,
             provider=provider,
             model=model,
-            flags=flags
+            flags=flags,
+            default_context=default_context
         )
 
         # Process translations

python_gpt_po/models/config.py

@@ -5,7 +5,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Optional
 
 from .enums import ModelProvider
 
@@ -30,3 +30,4 @@ class TranslationConfig:
     provider: ModelProvider
     model: str
     flags: TranslationFlags
+    default_context: Optional[str] = None

python_gpt_po/services/translation_service.py

@@ -855,13 +855,26 @@ def _prepare_translation_request(self, po_file, po_file_path, file_lang, detail_
         """Prepare a translation request from PO file data."""
         entries = [entry for entry in po_file if is_entry_untranslated(entry)]
         texts = [entry.msgid for entry in entries]
-        contexts = [entry.msgctxt if hasattr(entry, 'msgctxt') else None for entry in entries]
+
+        # Extract contexts from entries, falling back to default_context if not present
+        contexts = []
+        for entry in entries:
+            if hasattr(entry, 'msgctxt') and entry.msgctxt:
+                contexts.append(entry.msgctxt)
+            elif self.config.default_context:
+                contexts.append(self.config.default_context)
+            else:
+                contexts.append(None)
+
         detail_lang = detail_languages.get(file_lang) if detail_languages else None
 
         # Log context usage
         context_count = sum(1 for c in contexts if c)
+        default_context_count = sum(1 for c in contexts if c == self.config.default_context)
         if context_count > 0:
-            logging.debug("Found %d entries with msgctxt in %s", context_count, po_file_path)
+            logging.debug("Found %d entries with context in %s", context_count, po_file_path)
+            if default_context_count > 0:
+                logging.debug("Using default context for %d entries", default_context_count)
 
         # Check for and warn about whitespace in msgid
         whitespace_entries = [