translatronx 1.0.2 → 2.1.0

package/README.md

@@ -20,7 +20,6 @@ translatronx treats translations like source code:
 
 > translatronx is not another translation management system. It is a **translation compiler** — it treats language like code: build once → ship everywhere → zero runtime cost.
 
-
 ## 🌟 Features
 
 - **🔄 Incremental & Deterministic** - Only translates new/changed strings, same input = same output
@@ -31,19 +30,25 @@ translatronx treats translations like source code:
 - **📊 State-Aware** - SQLite ledger tracks changes without storing actual translations
 - **🛡️ Production-Ready** - Atomic writes, transaction safety, zero data loss on interruption
 - **🎨 Customizable Prompts** - Fine-tune translation quality with formatting, glossaries, and brand voice
+- **📝 Context Files** - Provide LLMs with context for each translation key to improve quality
 - **📈 Comprehensive Reporting** - Detailed statistics, cost estimates, and audit trails
 
 ## 📋 Table of Contents
 
 - [Installation](#-installation)
 - [Quick Start](#-quick-start)
-- [Configuration](#-configuration)
+- [Tutorial: Step-by-Step Guide](#-tutorial-step-by-step-guide)
+  - [Basic Translation Workflow](#1-basic-translation-workflow)
+  - [Using Context Files for Better Translations](#2-using-context-files-for-better-translations)
+  - [Managing Existing Translations](#3-managing-existing-translations)
+  - [Customizing Prompts](#4-customizing-prompts)
+  - [CI/CD Integration](#5-cicd-integration)
+- [Configuration Reference](#-configuration-reference)
 - [CLI Commands](#-cli-commands)
+- [Context Files](#-context-files)
 - [Advanced Usage](#-advanced-usage)
-- [Edge Cases & Troubleshooting](#-edge-cases--troubleshooting)
 - [Best Practices](#-best-practices)
 - [API Reference](#-api-reference)
-- [Contributing](#-contributing)
 
 ## 📦 Installation
 
@@ -76,39 +81,7 @@ npm install -g translatronx
 npx translatronx init
 ```
 
-This creates a `translatronx.config.ts` file in your project root:
-
-```typescript
-import { defineConfig } from 'translatronx';
-
-export default defineConfig({
-  sourceLanguage: 'en',
-  targetLanguages: [
-    { language: 'French', shortCode: 'fr' },
-    { language: 'German', shortCode: 'de' },
-    { language: 'Spanish', shortCode: 'es' }
-  ],
-  extractors: [
-    {
-      type: 'json',
-      pattern: './locales/en.json'
-    }
-  ],
-  providers: [
-    {
-      name: 'openai',
-      type: 'openai',
-      model: 'gpt-4o-mini',
-      temperature: 0.3
-    }
-  ],
-  output: {
-    dir: './locales',
-    format: 'json',
-    fileNaming: '{shortCode}.json'
-  }
-});
-```
+This creates a `translatronx.config.ts` file in your project root.
 
 ### 2. Set API Key
 
@@ -165,481 +138,457 @@ This generates:
 - `./locales/de.json`
 - `./locales/es.json`
 
-### 5. Check Status
+## 📚 Tutorial: Step-by-Step Guide
+
+### 1. Basic Translation Workflow
+
+#### Step 1.1: Initialize Your Project
 
 ```bash
-npx translatronx status
+# Create a new directory for your translations
+mkdir my-app-i18n
+cd my-app-i18n
+
+# Initialize npm project
+npm init -y
+
+# Install translatronx
+npm install --save-dev translatronx
+
+# Initialize configuration
+npx translatronx init
 ```
 
-## ⚙️ Configuration
+#### Step 1.2: Configure Your Project
 
-### Complete Configuration Reference
+Edit `translatronx.config.ts`:
 
 ```typescript
 import { defineConfig } from 'translatronx';
 
 export default defineConfig({
-  // Source language code (ISO 639-1)
   sourceLanguage: 'en',
-
-  // Target languages with full names and short codes
   targetLanguages: [
     { language: 'French', shortCode: 'fr' },
-    { language: 'German (Formal)', shortCode: 'de-formal' },
-    { language: 'Simplified Chinese', shortCode: 'zh-Hans' }
+    { language: 'German', shortCode: 'de' },
+    { language: 'Spanish', shortCode: 'es' }
   ],
-
-  // Extractors define how to find translatable strings
   extractors: [
     {
-      type: 'json',                    // 'json' | 'typescript' | 'custom'
-      pattern: './locales/en.json',    // Glob pattern(s)
-      keyPrefix: 'app',                // Optional: prefix for all keys
-      exclude: ['**/node_modules/**']  // Optional: exclude patterns
+      type: 'json',
+      pattern: './locales/en.json'
     }
   ],
-
-  // LLM providers configuration
   providers: [
     {
-      name: 'openai-primary',
+      name: 'openai',
       type: 'openai',
       model: 'gpt-4o-mini',
-      temperature: 0.3,
-      maxRetries: 3,
-      apiKey: process.env.OPENAI_API_KEY,  // Optional: defaults to env var
-      fallback: 'anthropic-backup'         // Optional: fallback provider
-    },
-    {
-      name: 'anthropic-backup',
-      type: 'anthropic',
-      model: 'claude-3-5-sonnet-20241022',
-      temperature: 0.3,
-      maxRetries: 2
+      temperature: 0.3
     }
   ],
-
-  // Validation rules
-  validation: {
-    preservePlaceholders: true,      // Ensure {var} placeholders are preserved
-    maxLengthRatio: 3,               // Max target/source length ratio
-    preventSourceLeakage: true,      // Prevent untranslated source text
-    brandNames: ['Acme', 'Widget'],  // Protected brand names
-    customRules: []                  // Custom validation functions
-  },
-
-  // Output configuration
   output: {
     dir: './locales',
-    format: 'json',                  // 'json' | 'yaml' | 'typescript'
-    flat: false,                     // Flatten nested objects
-    indent: 2,                       // JSON indentation
-    fileNaming: '{shortCode}.json',  // File naming pattern
-    allowSameFolder: false           // Allow source & target in same dir
-  },
-
-  // Prompt customization
-  prompts: {
-    customContext: 'This is a mobile banking app. Use financial terminology.',
-    formatting: 'formal',            // 'formal' | 'casual' | 'technical'
-    glossary: {
-      'Dashboard': 'Tableau de bord',
-      'Settings': 'Paramètres'
-    },
-    brandVoice: 'Professional, trustworthy, and user-friendly',
-    userPrompt: [                    // Custom user prompt (optional)
-      'Translate the following strings for a mobile app.',
-      'Maintain consistency with previous translations.'
-    ]
-  },
-
-  // Advanced settings
-  advanced: {
-    batchSize: 20,                   // Strings per LLM call
-    concurrency: 3,                  // Parallel LLM requests
-    cacheDir: './.translatronx',      // State directory
-    ledgerPath: './.translatronx/ledger.sqlite',
-    verbose: false                   // Enable verbose logging
+    format: 'json',
+    fileNaming: '{shortCode}.json'
   }
 });
 ```
 
-### Configuration Options Explained
+#### Step 1.3: Create Your Source Translations
 
-#### Target Languages
-
-Each target language requires:
-- `language`: Full language name (e.g., "French", "German (Formal)")
-- `shortCode`: ISO code or custom code (e.g., "fr", "de-formal", "zh-Hans")
-
-The `language` field provides context to the LLM for better translations.
-
-#### Extractors
+Create `./locales/en.json`:
 
-**JSON Extractor:**
-```typescript
+```json
 {
-  type: 'json',
-  pattern: './locales/**/*.json',
-  exclude: ['**/node_modules/**']
+  "app": {
+    "title": "My Awesome App",
+    "description": "The best app you'll ever use"
+  },
+  "navigation": {
+    "home": "Home",
+    "about": "About",
+    "contact": "Contact Us"
+  },
+  "auth": {
+    "login": "Log in",
+    "logout": "Log out",
+    "signup": "Sign up",
+    "forgotPassword": "Forgot Password?"
+  },
+  "messages": {
+    "welcome": "Welcome, {username}!",
+    "goodbye": "See you soon, {username}!",
+    "error": "An error occurred. Please try again."
+  }
 }
 ```
 
-**TypeScript Extractor:**
-```typescript
-{
-  type: 'typescript',
-  pattern: './src/**/*.ts',
-  keyPrefix: 'app'
-}
-```
+#### Step 1.4: Run Your First Translation
 
-#### Providers
+```bash
+# Set your API key
+export OPENAI_API_KEY=your-api-key-here
 
-**OpenAI:**
-```typescript
-{
-  name: 'openai',
-  type: 'openai',
-  model: 'gpt-4o-mini',  // or 'gpt-4o', 'gpt-4-turbo'
-  temperature: 0.3,
-  apiKey: process.env.OPENAI_API_KEY
-}
+# Run translation sync
+npx translatronx sync
 ```
 
-**Anthropic:**
-```typescript
-{
-  name: 'anthropic',
-  type: 'anthropic',
-  model: 'claude-3-5-sonnet-20241022',
-  temperature: 0.3,
-  apiKey: process.env.ANTHROPIC_API_KEY
-}
-```
+**What happens:**
+1. translatronx reads your source file (`en.json`)
+2. Extracts all translatable strings
+3. Batches them efficiently for the LLM
+4. Generates translations for all target languages
+5. Writes output files (`fr.json`, `de.json`, `es.json`)
+6. Stores state in `.translatronx/ledger.sqlite`
 
-**Groq:**
-```typescript
-{
-  name: 'groq',
-  type: 'groq',
-  model: 'llama-3.3-70b-versatile',
-  temperature: 0.3,
-  apiKey: process.env.GROQ_API_KEY
-}
-```
+#### Step 1.5: Check Translation Status
 
-**Azure OpenAI:**
-```typescript
-{
-  name: 'azure',
-  type: 'azure-openai',
-  model: 'gpt-4o',
-  baseUrl: 'https://your-resource.openai.azure.com',
-  apiKey: process.env.AZURE_OPENAI_KEY
-}
+```bash
+npx translatronx status
 ```
 
-**OpenRouter:**
-```typescript
-{
-  name: 'openrouter',
-  type: 'openrouter',
-  model: 'anthropic/claude-3.5-sonnet',
-  apiKey: process.env.OPENROUTER_API_KEY
-}
+**Output:**
 ```
+📊 Translation Coverage Report
 
-**Local Models:**
-```typescript
-{
-  name: 'local',
-  type: 'local',
-  model: 'llama3',
-  baseUrl: 'http://localhost:11434'  // Ollama endpoint
-}
+┌─────────────┬────────┬───────────┬──────────┬──────────┐
+│ Language    │ Total  │ Clean     │ Dirty    │ Coverage │
+├─────────────┼────────┼───────────┼──────────┼──────────┤
+│ French (fr) │ 12     │ 12        │ 0        │ 100.0%   │
+│ German (de) │ 12     │ 12        │ 0        │ 100.0%   │
+│ Spanish (es)│ 12     │ 12        │ 0        │ 100.0%   │
+└─────────────┴────────┴───────────┴──────────┴──────────┘
 ```
 
-#### Output File Naming
+#### Step 1.6: Update Source and Re-sync
 
-Use placeholders in `fileNaming`:
-- `{shortCode}` - Language short code (e.g., "fr")
-- `{language}` - Full language name (e.g., "French")
+Add a new string to `en.json`:
 
-Examples:
-- `{shortCode}.json` → `fr.json`
-- `{language}.translation.json` → `French.translation.json`
-- `translations/{shortCode}/app.json` → `translations/fr/app.json`
+```json
+{
+  "app": {
+    "title": "My Awesome App",
+    "description": "The best app you'll ever use",
+    "tagline": "Built with love ❤️"  // NEW!
+  },
+  // ... rest of the file
+}
+```
 
-## 🎮 CLI Commands
+Run sync again:
 
-### `translatronx init`
+```bash
+npx translatronx sync
+```
 
-Initialize translatronx configuration.
+**Output:**
+```
+✅ Translation sync complete!
 
-```bash
-translatronx init
+Statistics:
+  Total strings: 13
+  Translated: 3    ← Only the new string!
+  Failed: 0
+  Skipped: 10      ← Existing translations skipped
 ```
 
-Creates `translatronx.config.ts` with default settings.
+**This is the power of incremental translation!** Only new/changed strings are translated, saving you time and money.
 
 ---
 
-### `translatronx sync`
+### 2. Using Context Files for Better Translations
 
-Synchronize translations (incremental processing).
+Context files allow you to provide additional information to the LLM about each translation key, resulting in more accurate and contextually appropriate translations.
+
+#### Step 2.1: Generate a Context File Template
 
 ```bash
-translatronx sync [options]
+npx translatronx context generate --source ./locales/en.json
 ```
 
-**Options:**
-- `-f, --force` - Force regeneration of manual overrides
-- `-v, --verbose` - Enable verbose output with streaming
+**Output:**
+```
+📝 Generating context file template...
 
-**Examples:**
+  Source: /path/to/locales/en.json
+  Output: /path/to/locales/en.context.json
+  Merge:  No
 
-```bash
-# Normal incremental sync
-translatronx sync
+✅ Context file generated successfully!
+
+💡 Tip: Edit locales/en.context.json to add context for each translation key
+```
 
-# Force regenerate all translations (ignores manual edits)
-translatronx sync --force
+This creates `./locales/en.context.json`:
 
-# Verbose mode with detailed logging
-translatronx sync --verbose
+```json
+{
+  "app": {
+    "title": {
+      "value": "My Awesome App",
+      "context": ""
+    },
+    "description": {
+      "value": "The best app you'll ever use",
+      "context": ""
+    },
+    "tagline": {
+      "value": "Built with love ❤️",
+      "context": ""
+    }
+  },
+  "navigation": {
+    "home": {
+      "value": "Home",
+      "context": ""
+    },
+    // ... etc
+  }
+}
 ```
 
-**What happens during sync:**
-1. Extracts source strings from configured files
-2. Computes hashes and detects changes
-3. Identifies new/modified strings needing translation
-4. Deduplicates identical strings across keys
-5. Batches strings for efficient LLM calls
-6. Translates using configured provider(s)
-7. Validates translations (placeholders, length, etc.)
-8. Atomically writes to target files
-9. Updates ledger with new state
+#### Step 2.2: Add Context to Your Keys
 
----
+Edit `en.context.json` to add helpful context:
 
-### `translatronx status`
+```json
+{
+  "app": {
+    "title": {
+      "value": "My Awesome App",
+      "context": "Main application title shown in the header and browser tab"
+    },
+    "description": {
+      "value": "The best app you'll ever use",
+      "context": "Marketing tagline shown on the landing page. Should be enthusiastic and engaging."
+    },
+    "tagline": {
+      "value": "Built with love ❤️",
+      "context": "Footer tagline. Keep the heart emoji in all translations."
+    }
+  },
+  "auth": {
+    "login": {
+      "value": "Log in",
+      "context": "Button text for user authentication. Should be concise and action-oriented."
+    },
+    "logout": {
+      "value": "Log out",
+      "context": "Button text for ending user session."
+    },
+    "forgotPassword": {
+      "value": "Forgot Password?",
+      "context": "Link text for password recovery. Should be phrased as a question."
+    }
+  },
+  "messages": {
+    "welcome": {
+      "value": "Welcome, {username}!",
+      "context": "Greeting shown when user logs in. {username} is the user's display name."
+    }
+  }
+}
+```
 
-Display coverage statistics and system state.
+#### Step 2.3: Validate Your Context File
 
 ```bash
-translatronx status
+npx translatronx context validate
 ```
 
 **Output:**
 ```
-📊 Checking status...
+🔍 Validating context file...
 
-Project Statistics:
-  Total keys: 127
-  Manual overrides: 3
+  Source:  /path/to/locales/en.json
+  Context: /path/to/locales/en.context.json
 
-Language Coverage:
-  French (fr):
-    ✓ Translated: 127
-    ✗ Failed: 0
-    Coverage: 100%
-
-  German (de):
-    ✓ Translated: 124
-    ✗ Failed: 3
-    Coverage: 98%
-
-Latest Run:
-  Run ID:    run_2026-01-29T06-30-00
-  Model:     gpt-4o-mini
-  Cost:      $0.0142
-  Duration:  Completed
+✅ Context file is valid!
 ```
 
----
-
-### `translatronx retry`
+#### Step 2.4: Enable Context in Configuration
 
-Retry failed translation batches.
+Update `translatronx.config.ts`:
 
-```bash
-translatronx retry [options]
+```typescript
+export default defineConfig({
+  // ... other config
+  extractors: [
+    {
+      type: 'json',
+      pattern: './locales/en.json',
+      contextFile: {
+        enabled: true,
+        pattern: './locales/en.context.json',
+        autoGenerate: false,
+        autoUpdate: false
+      }
+    }
+  ],
+  // ... rest of config
+});
 ```
 
-**Options:**
-- `--batch <id>` - Specific batch ID to retry
-- `--lang <code>` - Specific language to retry (comma-separated)
-- `--dry-run` - Show what would be retried without making changes
+#### Step 2.5: Re-translate with Context
 
-**Examples:**
+To see the improvement, let's force a retranslation:
 
 ```bash
-# Retry all failed translations
-translatronx retry
+# Delete existing translations
+rm ./locales/fr.json ./locales/de.json ./locales/es.json
 
-# Retry only French translations
-translatronx retry --lang fr
+# Clear the ledger to force retranslation
+rm -rf .translatronx
 
-# Retry multiple languages
-translatronx retry --lang fr,de,es
-
-# Dry run to see what would be retried
-translatronx retry --dry-run
+# Run sync with context
+npx translatronx sync
 ```
 
----
+**The LLM now receives context for each string, resulting in better translations!**
 
-### `translatronx check`
+For example, without context:
+- "Log in" might be translated as "Connexion" (noun) in French
 
-Validate target files without making changes.
+With context ("Button text for user authentication"):
+- "Log in" is translated as "Se connecter" (verb/action) in French
 
-```bash
-translatronx check
-```
+---
 
-**Note:** This command validates:
-- Placeholder preservation
-- JSON structure integrity
-- Length ratios
-- Source text leakage
+### 3. Managing Existing Translations
 
----
+If you already have translations and want to add context files without affecting them:
 
-## 🔥 Advanced Usage
+#### Step 3.1: Import Context from Source
 
-### Manual Override Protection
+```bash
+npx translatronx context import --source ./locales/en.json
+```
 
-translatronx detects when you manually edit translations and protects them from being overwritten.
+**Output:**
+```
+📥 Importing context from source...
 
-**Workflow:**
+  Source:  /path/to/locales/en.json
+  Output:  /path/to/locales/en.context.json
+  Merge:   Yes
 
-1. **Initial translation:**
-   ```json
-   // fr.json (auto-generated)
-   {
-     "welcome": "Bienvenue dans notre application !"
-   }
-   ```
+✅ Context imported from source successfully!
+  • Existing context preserved
+  • New keys from source added
+  • Source values updated to match current source
+  • Your existing translations are safe
 
-2. **Manual edit:**
-   ```json
-   // fr.json (manually edited)
-   {
-     "welcome": "Bienvenue sur notre plateforme !"
-   }
-   ```
+💡 Tip: Your existing translations will NOT be affected.
+   Context files only improve future translations.
+```
 
-3. **Next sync:**
-   - translatronx detects hash mismatch
-   - Marks as `MANUAL` status in ledger
-   - **Skips** this key in future syncs
+**Key Points:**
+- ✅ Your existing translation files (`fr.json`, `de.json`, etc.) are **never touched**
+- ✅ Existing context you've written is **preserved**
+- ✅ New keys from source are **added** with empty context
+- ✅ Only **future translations** will benefit from context
 
-4. **Force regeneration (if needed):**
-   ```bash
-   translatronx sync --force
-   ```
+#### Step 3.2: Sync Context When Source Changes
 
-### Provider Fallback Chain
+When you add/remove keys in your source file:
 
-Configure multiple providers with automatic fallback:
+```bash
+npx translatronx context sync
+```
 
-```typescript
-providers: [
-  {
-    name: 'primary',
-    type: 'openai',
-    model: 'gpt-4o-mini',
-    fallback: 'backup'
-  },
-  {
-    name: 'backup',
-    type: 'anthropic',
-    model: 'claude-3-5-sonnet-20241022',
-    fallback: 'local'
-  },
-  {
-    name: 'local',
-    type: 'local',
-    model: 'llama3',
-    baseUrl: 'http://localhost:11434'
-  }
-]
+**Output:**
 ```
+🔄 Syncing context file with source...
 
-**Fallback triggers:**
-- API rate limits
-- Network errors
-- Validation failures after max retries
+  Source:  /path/to/locales/en.json
+  Context: /path/to/locales/en.context.json
 
-### Custom Prompt Engineering
+✅ Context file synced successfully!
+  • New keys added
+  • Deleted keys removed
+  • Existing context preserved
+```
 
-Fine-tune translation quality with custom prompts:
+---
 
-```typescript
-prompts: {
-  // Context about your application
-  customContext: `
-    This is a healthcare application for patients and doctors.
-    Use medical terminology appropriately.
-    Maintain HIPAA-compliant language.
-  `,
-
-  // Tone and style
-  formatting: 'formal',
-
-  // Glossary for consistent terminology
-  glossary: {
-    'Appointment': 'Rendez-vous',
-    'Medical Record': 'Dossier médical',
-    'Prescription': 'Ordonnance'
-  },
+### 4. Customizing Prompts
 
-  // Brand voice
-  brandVoice: 'Compassionate, professional, and clear',
+Improve translation quality by customizing the prompts sent to the LLM.
 
-  // Custom user prompt (advanced)
-  userPrompt: [
-    'Translate the following medical app strings.',
-    'Ensure all medical terms are accurate.',
-    'Use patient-friendly language where appropriate.'
-  ]
-}
-```
+#### Step 4.1: Add Custom Context
 
-### Same-Folder Source and Target
+```typescript
+export default defineConfig({
+  // ... other config
+  prompts: {
+    customContext: 'This is a mobile banking app. Use financial terminology and maintain a professional tone.',
+  }
+});
+```
 
-By default, translatronx prevents source and target files in the same directory to avoid confusion. Enable if needed:
+#### Step 4.2: Add Glossary
 
 ```typescript
-output: {
-  dir: './locales',
-  allowSameFolder: true,
-  fileNaming: '{shortCode}.json'
-}
+export default defineConfig({
+  // ... other config
+  prompts: {
+    glossary: {
+      'Dashboard': 'Tableau de bord',
+      'Account': 'Compte',
+      'Transaction': 'Transaction',
+      'Balance': 'Solde'
+    }
+  }
+});
 ```
 
-**Example structure:**
+#### Step 4.3: Set Formatting Style
+
+```typescript
+export default defineConfig({
+  // ... other config
+  prompts: {
+    formatting: 'formal',  // 'formal' | 'casual' | 'technical'
+    brandVoice: 'Professional, trustworthy, and user-friendly'
+  }
+});
 ```
-locales/
-  ├── en.json (source)
-  ├── fr.json (target)
-  ├── ta.json (target)
-  └── es.json (target)
+
+#### Step 4.4: Custom User Prompt
+
+```typescript
+export default defineConfig({
+  // ... other config
+  prompts: {
+    userPrompt: [
+      'Translate the following strings for a mobile banking application.',
+      'Maintain consistency with previous translations.',
+      'Use formal language and financial terminology.',
+      'Preserve all placeholders like {username} exactly as they appear.'
+    ]
+  }
+});
 ```
 
-### CI/CD Integration
+---
+
+### 5. CI/CD Integration
 
-#### GitHub Actions
+#### Step 5.1: GitHub Actions
+
+Create `.github/workflows/translations.yml`:
 
 ```yaml
-name: Sync Translations
+name: Update Translations
 
 on:
   push:
-    branches: [main]
     paths:
       - 'locales/en.json'
+      - 'locales/en.context.json'
+    branches:
+      - main
 
 jobs:
   translate:
@@ -650,449 +599,654 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: '18'
+          node-version: '20'
       
       - name: Install dependencies
         run: npm ci
       
-      - name: Sync translations
+      - name: Run translations
         env:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
         run: npx translatronx sync
       
       - name: Commit translations
         run: |
-          git config user.name "Translation Bot"
-          git config user.email "bot@example.com"
-          git add locales/
-          git commit -m "chore: update translations" || exit 0
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add locales/*.json
+          git diff --quiet && git diff --staged --quiet || git commit -m "chore: update translations"
           git push
 ```
 
-#### GitLab CI
+#### Step 5.2: GitLab CI
+
+Create `.gitlab-ci.yml`:
 
 ```yaml
 translate:
+  image: node:20
   stage: build
-  image: node:18
-  script:
-    - npm ci
-    - npx translatronx sync
-  artifacts:
-    paths:
-      - locales/
   only:
     changes:
       - locales/en.json
+      - locales/en.context.json
+  script:
+    - npm ci
+    - npx translatronx sync
+    - git config user.email "ci@gitlab.com"
+    - git config user.name "GitLab CI"
+    - git add locales/*.json
+    - git diff --quiet && git diff --staged --quiet || (git commit -m "chore: update translations" && git push)
+  variables:
+    OPENAI_API_KEY: $OPENAI_API_KEY
 ```
 
-### Programmatic API Usage
+---
+
+## ⚙️ Configuration Reference
 
-Use translatronx programmatically in Node.js:
+### Complete Configuration Example
 
 ```typescript
-import { TranslationCompiler, loadConfig } from 'translatronx';
+import { defineConfig } from 'translatronx';
 
-async function translateApp() {
-  // Load configuration
-  const config = await loadConfig();
-  
-  // Create compiler instance
-  const compiler = new TranslationCompiler(config);
-  
-  // Run sync
-  const stats = await compiler.sync({ verbose: true });
-  
-  console.log(`Translated ${stats.translatedUnits} strings`);
-  console.log(`Cost: $${stats.costEstimateUsd.toFixed(4)}`);
-  
-  // Close ledger connection
-  compiler.close();
-}
+export default defineConfig({
+  // Source language code (ISO 639-1)
+  sourceLanguage: 'en',
 
-translateApp().catch(console.error);
-```
+  // Target languages with full names and short codes
+  targetLanguages: [
+    { language: 'French', shortCode: 'fr' },
+    { language: 'German (Formal)', shortCode: 'de-formal' },
+    { language: 'Simplified Chinese', shortCode: 'zh-Hans' }
+  ],
+
+  // Extractors define how to find translatable strings
+  extractors: [
+    {
+      type: 'json',                    // 'json' | 'typescript' | 'custom'
+      pattern: './locales/en.json',    // Glob pattern(s)
+      keyPrefix: 'app',                // Optional: prefix for all keys
+      exclude: ['**/node_modules/**'], // Optional: exclude patterns
+      contextFile: {                   // Optional: context file configuration
+        enabled: true,
+        pattern: './locales/en.context.json',
+        autoGenerate: false,
+        autoUpdate: false
+      }
+    }
+  ],
 
-## 🐛 Edge Cases & Troubleshooting
+  // LLM providers configuration
+  providers: [
+    {
+      name: 'openai-primary',
+      type: 'openai',
+      model: 'gpt-4o-mini',
+      temperature: 0.3,
+      maxRetries: 3,
+      apiKey: process.env.OPENAI_API_KEY,  // Optional: defaults to env var
+      fallback: 'anthropic-backup'         // Optional: fallback provider
+    },
+    {
+      name: 'anthropic-backup',
+      type: 'anthropic',
+      model: 'claude-3-5-sonnet-20241022',
+      temperature: 0.3,
+      maxRetries: 2
+    }
+  ],
 
-### Edge Case 1: Placeholder Variations
+  // Validation rules
+  validation: {
+    preservePlaceholders: true,      // Ensure {var} placeholders are preserved
+    maxLengthRatio: 3,               // Max target/source length ratio
+    preventSourceLeakage: true,      // Prevent untranslated source text
+    brandNames: ['Acme', 'Widget'],  // Protected brand names
+    customRules: []                  // Custom validation functions
+  },
 
-**Problem:** Different placeholder formats in your app.
+  // Output configuration
+  output: {
+    dir: './locales',
+    format: 'json',                  // 'json' | 'yaml' | 'typescript'
+    flat: false,                     // Flatten nested objects
+    indent: 2,                       // JSON indentation
+    fileNaming: '{shortCode}.json',  // File naming pattern
+    allowSameFolder: false           // Allow source & target in same dir
+  },
 
-**Solution:** translatronx automatically detects and preserves:
-- `{variable}` - Single braces
-- `{{variable}}` - Double braces
-- `$variable` - Dollar sign
-- `%s`, `%d` - Printf-style
-- `%1$s` - Positional
+  // Prompt customization
+  prompts: {
+    customContext: 'This is a mobile banking app. Use financial terminology.',
+    formatting: 'formal',            // 'formal' | 'casual' | 'technical'
+    glossary: {
+      'Dashboard': 'Tableau de bord',
+      'Settings': 'Paramètres'
+    },
+    brandVoice: 'Professional, trustworthy, and user-friendly',
+    userPrompt: [                    // Custom user prompt (optional)
+      'Translate the following strings for a mobile app.',
+      'Maintain consistency with previous translations.'
+    ]
+  },
 
-**Example:**
-```json
-{
-  "greeting": "Hello, {name}!",
-  "count": "You have {{count}} messages",
-  "format": "User: %s, ID: %d"
-}
+  // Advanced settings
+  advanced: {
+    batchSize: 20,                   // Strings per LLM call
+    concurrency: 3,                  // Parallel LLM requests
+    cacheDir: './.translatronx',     // State directory
+    ledgerPath: './.translatronx/ledger.sqlite',
+    verbose: false                   // Enable verbose logging
+  }
+});
 ```
 
-All placeholders are preserved exactly in translations.
+### Configuration Options
+
+#### `sourceLanguage`
+- **Type:** `string`
+- **Required:** Yes
+- **Description:** ISO 639-1 language code for source language
+
+#### `targetLanguages`
+- **Type:** `Array<{ language: string, shortCode: string }>`
+- **Required:** Yes
+- **Description:** Array of target languages with full names and codes
+
+#### `extractors`
+- **Type:** `Array<ExtractorConfig>`
+- **Required:** Yes
+- **Description:** Configuration for extracting translatable strings
+
+##### Extractor Context File Options
+- `enabled`: Enable context file support
+- `pattern`: Path to context file (defaults to `{source}.context.json`)
+- `autoGenerate`: Auto-generate context file if missing
+- `autoUpdate`: Auto-update context file when source changes
+
+#### `providers`
+- **Type:** `Array<ProviderConfig>`
+- **Required:** Yes
+- **Description:** LLM provider configuration
+
+Supported providers:
+- `openai` - OpenAI (GPT-4, GPT-3.5, etc.)
+- `anthropic` - Anthropic (Claude)
+- `groq` - Groq
+- `azure-openai` - Azure OpenAI
+- `openrouter` - OpenRouter
+
+#### `validation`
+- **Type:** `ValidationConfig`
+- **Required:** No
+- **Description:** Translation validation rules
+
+#### `output`
+- **Type:** `OutputConfig`
+- **Required:** Yes
+- **Description:** Output file configuration
+
+#### `prompts`
+- **Type:** `PromptConfig`
+- **Required:** No
+- **Description:** Prompt customization options
+
+#### `advanced`
+- **Type:** `AdvancedConfig`
+- **Required:** No
+- **Description:** Advanced performance and behavior settings
 
-### Edge Case 2: Nested JSON Structures
+---
 
-**Problem:** Deep nesting in translation files.
+## 🖥️ CLI Commands
 
-**Solution:** translatronx flattens keys internally using dot notation:
+### `translatronx sync`
 
-```json
-{
-  "auth": {
-    "login": {
-      "title": "Sign In",
-      "button": "Log In"
-    }
-  }
-}
+Synchronize translations (incremental processing).
+
+```bash
+npx translatronx sync [options]
+```
+
+**Options:**
+- `-f, --force` - Force regeneration of manual overrides
+- `-v, --verbose` - Enable verbose output
+
+**Example:**
+```bash
+npx translatronx sync --verbose
 ```
 
-Internally tracked as:
-- `auth.login.title`
-- `auth.login.button`
+---
 
-Output maintains original structure.
+### `translatronx status`
 
-### Edge Case 3: Empty or Whitespace Strings
+Display coverage statistics and system state.
 
-**Problem:** Empty strings or whitespace-only values.
+```bash
+npx translatronx status
+```
 
-**Behavior:**
-- Empty strings (`""`) are skipped
-- Whitespace-only strings are normalized and translated
-- Leading/trailing whitespace is preserved if intentional
+**Output:**
+```
+📊 Translation Coverage Report
 
-### Edge Case 4: Very Long Strings
+┌─────────────┬────────┬───────────┬──────────┬──────────┐
+│ Language    │ Total  │ Clean     │ Dirty    │ Coverage │
+├─────────────┼────────┼───────────┼──────────┼──────────┤
+│ French (fr) │ 12     │ 12        │ 0        │ 100.0%   │
+│ German (de) │ 12     │ 11        │ 1        │ 91.7%    │
+└─────────────┴────────┴───────────┴──────────┴──────────┘
+```
 
-**Problem:** Strings exceeding token limits.
+---
 
-**Solution:**
-- Automatic chunking for strings > 1000 characters
-- Configurable `maxLengthRatio` validation
-- Warning if target exceeds `source length × maxLengthRatio`
+### `translatronx retry`
 
-### Edge Case 5: Special Characters & Encoding
+Retry failed translation batches.
 
-**Problem:** Unicode, emojis, RTL languages.
+```bash
+npx translatronx retry [options]
+```
 
-**Solution:**
-- All text normalized to Unicode NFC
-- Full Unicode support including emojis 🎉
-- RTL languages (Arabic, Hebrew) handled correctly
-- HTML entities preserved
+**Options:**
+- `--batch <id>` - Specific batch ID to retry
+- `--lang <code>` - Specific language to retry
+- `--dry-run` - Show what would be retried without making changes
 
-### Edge Case 6: Interrupted Sync
+**Example:**
+```bash
+npx translatronx retry --lang fr --dry-run
+```
 
-**Problem:** Process killed during translation.
+---
 
-**Solution:**
-- Atomic file writes (temp file → rename)
-- Transactional ledger updates
-- No partial/corrupted files
-- Safe to re-run sync immediately
+### `translatronx init`
 
-### Edge Case 7: API Rate Limits
+Initialize translatronx configuration.
 
-**Problem:** Provider rate limits exceeded.
+```bash
+npx translatronx init
+```
 
-**Solution:**
-- Automatic retry with exponential backoff
-- Fallback to secondary provider
-- Configurable `maxRetries` per provider
-- Batch size adjustment
+Creates a `translatronx.config.ts` file in your project root.
 
-### Edge Case 8: Inconsistent Translations
+---
 
-**Problem:** Same source string translated differently.
+### `translatronx context generate`
 
-**Solution:**
-- Deduplication groups identical strings
-- Single translation reused across all occurrences
-- Glossary ensures terminology consistency
-- Prompt version tracking for reproducibility
+Generate context file template from source file.
 
-### Common Errors
+```bash
+npx translatronx context generate [options]
+```
 
-#### Error: "Configuration file not found"
+**Options:**
+- `--source <path>` - Source file path (overrides config)
+- `--output <path>` - Context file output path
+- `--merge` - Merge with existing context file
+- `--dry-run` - Preview changes without writing
 
+**Example:**
 ```bash
-Error: Could not find translatronx.config.ts
+npx translatronx context generate --source ./locales/en.json
 ```
 
-**Solution:**
+---
+
+### `translatronx context validate`
+
+Validate context file matches source file.
+
 ```bash
-translatronx init
+npx translatronx context validate [options]
 ```
 
-#### Error: "API key not set"
+**Options:**
+- `--source <path>` - Source file path (overrides config)
+- `--context <path>` - Context file path (overrides config)
 
+**Example:**
 ```bash
-Error: OPENAI_API_KEY environment variable not set
+npx translatronx context validate
 ```
 
-**Solution:**
+---
+
+### `translatronx context sync`
+
+Sync context file with source (add new keys, remove deleted keys).
+
 ```bash
-export OPENAI_API_KEY=your-key
+npx translatronx context sync [options]
 ```
 
-#### Error: "Placeholder mismatch"
+**Options:**
+- `--source <path>` - Source file path (overrides config)
+- `--context <path>` - Context file path (overrides config)
+- `--dry-run` - Preview changes without writing
 
+**Example:**
 ```bash
-ValidationError: Placeholder mismatch in key "greeting"
-Source: {name}, Target: {nom}
+npx translatronx context sync --dry-run
 ```
 
-**Solution:** This is a validation error preventing incorrect translations. The LLM will retry automatically.
+---
 
-#### Error: "Source file not found"
+### `translatronx context import`
+
+Import/generate context file from source JSON (preserves existing translations).
 
 ```bash
-Error: Source file not found: ./locales/en.json
+npx translatronx context import [options]
 ```
 
-**Solution:** Create the source file or update `extractors.pattern` in config.
+**Options:**
+- `--source <path>` - Source JSON file to generate context from
+- `--output <path>` - Output context file path
+- `--merge` - Merge with existing context file (default: true)
+- `--dry-run` - Preview changes without writing
+
+**Example:**
+```bash
+npx translatronx context import --source ./locales/en.json
+```
 
-## ✅ Best Practices
+**Use Case:** Perfect for users who already have translations and want to add context files without affecting existing translations.
 
-### 1. Version Control
+---
 
-**Do commit:**
-- ✅ `translatronx.config.ts`
-- ✅ All translation files (`*.json`, `*.yaml`)
-- ✅ `.gitignore` entry for `.translatronx/`
+## 📝 Context Files
 
-**Don't commit:**
-- ❌ `.translatronx/` directory (state files)
-- ❌ API keys (use environment variables)
+Context files provide additional information to the LLM about each translation key, resulting in more accurate and contextually appropriate translations.
 
-**Recommended `.gitignore`:**
-```gitignore
-.translatronx/
-*.sqlite
-*.sqlite-journal
-```
+### Context File Structure
 
-### 2. Source File Organization
+Context files mirror your source file structure:
 
-**Good:**
-```
-locales/
-  ├── en.json          # Single source of truth
-  ├── fr.json          # Generated
-  ├── de.json          # Generated
-  └── es.json          # Generated
+**Source File (`en.json`):**
+```json
+{
+  "greeting": "Hello, {name}!",
+  "auth": {
+    "login": "Sign in",
+    "logout": "Sign out"
+  }
+}
 ```
 
-**Better:**
-```
-locales/
-  ├── source/
-  │   └── en.json      # Source (manually edited)
-  └── generated/
-      ├── fr.json      # Generated (auto-managed)
-      ├── de.json
-      └── es.json
+**Context File (`en.context.json`):**
+```json
+{
+  "greeting": {
+    "value": "Hello, {name}!",
+    "context": "Greeting shown when user logs in. {name} is the user's display name.",
+    "notes": "Keep it friendly and welcoming",
+    "maxLength": 50,
+    "tone": "casual"
+  },
+  "auth": {
+    "login": {
+      "value": "Sign in",
+      "context": "Button text for user authentication. Should be concise and action-oriented."
+    },
+    "logout": {
+      "value": "Sign out",
+      "context": "Button text for ending user session."
+    }
+  }
+}
 ```
 
-### 3. Incremental Adoption
+### Context Metadata Fields
 
-Start small, expand gradually:
+Each key in a context file can have:
 
-```typescript
-// Phase 1: Single language
-targetLanguages: [
-  { language: 'French', shortCode: 'fr' }
-]
-
-// Phase 2: Add more languages
-targetLanguages: [
-  { language: 'French', shortCode: 'fr' },
-  { language: 'German', shortCode: 'de' },
-  { language: 'Spanish', shortCode: 'es' }
-]
-
-// Phase 3: Regional variants
-targetLanguages: [
-  { language: 'French (France)', shortCode: 'fr-FR' },
-  { language: 'French (Canada)', shortCode: 'fr-CA' },
-  { language: 'Spanish (Spain)', shortCode: 'es-ES' },
-  { language: 'Spanish (Mexico)', shortCode: 'es-MX' }
-]
-```
-
-### 4. Cost Optimization
-
-**Minimize costs:**
-- Use smaller models for simple strings (`gpt-4o-mini`)
-- Increase `batchSize` for fewer API calls
-- Use deduplication (enabled by default)
-- Set appropriate `temperature` (0.3 recommended)
-
-**Cost estimation:**
+- **`value`** (required): The source text (for validation)
+- **`context`** (optional): Descriptive text for the LLM
+- **`notes`** (optional): Additional notes
+- **`maxLength`** (optional): Maximum character length
+- **`tone`** (optional): Desired tone (e.g., "formal", "casual", "technical")
+
+### Context File Workflow
+
+1. **Generate template:**
+   ```bash
+   npx translatronx context generate
+   ```
+
+2. **Add context to keys:**
+   Edit the generated `en.context.json` file
+
+3. **Validate:**
+   ```bash
+   npx translatronx context validate
+   ```
+
+4. **Enable in config:**
+   ```typescript
+   extractors: [{
+     type: 'json',
+     pattern: './locales/en.json',
+     contextFile: {
+       enabled: true,
+       pattern: './locales/en.context.json'
+     }
+   }]
+   ```
+
+5. **Run sync:**
+   ```bash
+   npx translatronx sync
+   ```
+
+### Benefits of Context Files
+
+- **Better Translation Quality** - LLMs understand the purpose and usage of each string
+- **Consistency** - Maintain consistent terminology across your app
+- **Tone Control** - Specify formal vs. casual tone per string
+- **Length Constraints** - Ensure translations fit UI constraints
+- **Optional** - Works with or without context files
+- **Backward Compatible** - No breaking changes to existing workflows
+
+---
+
+## 🔧 Advanced Usage
+
+### Manual Edits Protection
+
+translatronx automatically detects and protects manual edits:
+
+1. Translate your strings:
+   ```bash
+   npx translatronx sync
+   ```
+
+2. Manually edit a translation in `fr.json`:
+   ```json
+   {
+     "welcome": "Bienvenue chez nous!"  // Manual edit
+   }
+   ```
+
+3. Run sync again:
+   ```bash
+   npx translatronx sync
+   ```
+
+4. Your manual edit is preserved! The ledger marks it as `MANUAL` status.
+
+To force retranslation of manual edits:
 ```bash
-# Dry run to estimate cost
-translatronx sync --dry-run
+npx translatronx sync --force
 ```
 
-### 5. Quality Assurance
+---
 
-**Multi-stage validation:**
+### Multiple Providers with Fallback
 
 ```typescript
-validation: {
-  preservePlaceholders: true,
-  maxLengthRatio: 3,
-  preventSourceLeakage: true,
-  brandNames: ['YourBrand', 'ProductName']
-}
+export default defineConfig({
+  providers: [
+    {
+      name: 'primary',
+      type: 'openai',
+      model: 'gpt-4o-mini',
+      fallback: 'backup'
+    },
+    {
+      name: 'backup',
+      type: 'anthropic',
+      model: 'claude-3-5-sonnet-20241022'
+    }
+  ]
+});
 ```
 
-**Manual review workflow:**
-1. Run `translatronx sync`
-2. Review generated files
-3. Manually edit if needed
-4. Commit changes
-5. Future syncs preserve manual edits
+If the primary provider fails, translatronx automatically uses the backup.
 
-### 6. Prompt Optimization
+---
 
-**Effective prompts:**
+### Custom Validation Rules
 
 ```typescript
-prompts: {
-  customContext: `
-    Context: E-commerce checkout flow
-    Audience: International shoppers
-    Tone: Clear, reassuring, action-oriented
-  `,
-  formatting: 'casual',
-  glossary: {
-    'Cart': 'Panier',
-    'Checkout': 'Passer commande',
-    'Shipping': 'Livraison'
+export default defineConfig({
+  validation: {
+    customRules: [
+      (source, target) => {
+        // Ensure translations don't exceed source length by more than 50%
+        if (target.length > source.length * 1.5) {
+          return { isValid: false, error: 'Translation too long' };
+        }
+        return { isValid: true };
+      }
+    ]
   }
-}
+});
 ```
 
-### 7. Monitoring & Debugging
+---
+
+### Importing Existing Translations
 
-**Enable verbose mode:**
-```bash
-translatronx sync --verbose
-```
+If you have existing translations you want to import:
 
-**Check status regularly:**
 ```bash
-translatronx status
+npx translatronx import --source ./old-translations/fr.json --target fr
 ```
 
-**Review run history:**
-```bash
-# Ledger stores run history
-sqlite3 .translatronx/ledger.sqlite "SELECT * FROM run_history ORDER BY started_at DESC LIMIT 5;"
-```
+This imports your existing translations and marks them as `MANUAL` in the ledger, protecting them from being overwritten.
 
-## 📚 API Reference
+---
 
-### `defineConfig(config: translatronxConfig)`
+## 💡 Best Practices
 
-Define and validate translatronx configuration.
+### 1. Use Context Files for Important Strings
 
-```typescript
-import { defineConfig } from 'translatronx';
+Add context to strings where:
+- The meaning is ambiguous (e.g., "Bank" - financial institution or river bank?)
+- Tone matters (e.g., error messages should be helpful, not scary)
+- Length constraints exist (e.g., button text must be short)
+- Cultural nuances matter (e.g., greetings, politeness levels)
 
-export default defineConfig({
-  // ... configuration
-});
-```
+### 2. Keep Source Files Clean
 
-### `loadConfig(configPath?: string)`
+- Use clear, descriptive keys: `auth.loginButton` not `btn1`
+- Avoid abbreviations in source text
+- Use consistent placeholder format: `{variable}` not `{{variable}}` or `$variable`
 
-Load configuration from file.
+### 3. Leverage Glossaries
 
-```typescript
-import { loadConfig } from 'translatronx';
+Create a glossary for:
+- Brand names
+- Product names
+- Technical terms
+- Domain-specific terminology
 
-const config = await loadConfig('./custom.config.ts');
-```
+### 4. Run Translations in CI/CD
 
-### `TranslationCompiler`
+Automate translations on source file changes:
+- Ensures translations are always up-to-date
+- Catches issues early
+- Reduces manual work
 
-Main orchestrator for translation compilation.
+### 5. Review Generated Translations
 
-```typescript
-import { TranslationCompiler } from 'translatronx';
+While LLMs are good, they're not perfect:
+- Review critical strings (legal, security, payments)
+- Have native speakers spot-check
+- Use the `status` command to track coverage
 
-const compiler = new TranslationCompiler(config);
-```
+### 6. Use Incremental Workflow
 
-**Methods:**
+Don't retranslate everything:
+- Let translatronx track changes
+- Only force retranslation when necessary
+- Trust the ledger system
 
-#### `sync(options?: SyncOptions): Promise<RunStatistics>`
+---
 
-Synchronize translations.
+## 📖 API Reference
+
+### Programmatic Usage
 
 ```typescript
-const stats = await compiler.sync({
-  force: false,
-  verbose: false
-});
-```
+import { TranslationCompiler, loadConfig } from 'translatronx';
 
-#### `retryFailed(options?: RetryOptions): Promise<RetryStatistics>`
+async function main() {
+  // Load configuration
+  const config = await loadConfig();
 
-Retry failed translations.
+  // Create compiler
+  const compiler = new TranslationCompiler(config);
 
-```typescript
-const stats = await compiler.retryFailed({
-  lang: 'fr',
-  dryRun: false
-});
-```
+  // Run sync
+  const stats = await compiler.sync({ verbose: true });
+
+  console.log(`Translated ${stats.translatedUnits} strings`);
+  console.log(`Cost: $${stats.costEstimateUsd.toFixed(4)}`);
 
-#### `close(): void`
+  // Close compiler
+  compiler.close();
+}
 
-Close ledger connection.
+main();
+```
+
+### Configuration API
 
 ```typescript
-compiler.close();
+import { defineConfig } from 'translatronx';
+
+export default defineConfig({
+  // Type-safe configuration
+  sourceLanguage: 'en',
+  targetLanguages: [
+    { language: 'French', shortCode: 'fr' }
+  ],
+  // ... rest of config
+});
 ```
 
-### Types
+### Custom Extractors
 
 ```typescript
-interface RunStatistics {
-  runId: string;
-  startedAt: Date;
-  finishedAt?: Date;
-  totalUnits: number;
-  translatedUnits: number;
-  failedUnits: number;
-  skippedUnits: number;
-  tokensIn: number;
-  tokensOut: number;
-  costEstimateUsd: number;
-  model: string;
-}
+import { type Extractor, type SourceUnit } from 'translatronx';
 
-interface RetryStatistics {
-  recoveredUnits: number;
-  remainingFailed: number;
-  tokensIn: number;
-  tokensOut: number;
+class CustomExtractor implements Extractor {
+  async extract(sourceFiles: string[], config: ExtractorConfig): Promise<SourceUnit[]> {
+    // Your custom extraction logic
+    return [];
+  }
 }
 ```
 
+---
+
 ## 🤝 Contributing
 
-Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
 ### Development Setup
 
@@ -1126,8 +1280,8 @@ MIT © Shanthosh
 
 ## 📞 Support
 
-- **Issues:** [GitHub Issues](https://github.com/msalways/translatronx/issues)
-- **Discussions:** [GitHub Discussions](https://github.com/msalways/translatronx/discussions)
+- **Issues:** [GitHub Issues](https://github.com/msalways/translatron/issues)
+- **Discussions:** [GitHub Discussions](https://github.com/msalways/translatron/discussions)
 - **Email:** shanthubolt@gmail.com
 
 ---