snbt-tr 1.0.0__tar.gz

snbt_tr-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ronnikols
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

snbt_tr-1.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+recursive-include resources *

snbt_tr-1.0.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: snbt-tr
+Version: 1.0.0
+Summary: Advanced SNBT quest localizer using AI key pools
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyQt6>=6.4.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: aiofiles>=23.1.0
+Dynamic: license-file
+
+<p align="center">
+  <img src="resources/logo.png" alt="SNBT AI Localizer Logo" width="200" height="200">
+</p> # SNBT AI Localizer
+
+English | [Русский](README_RU.md)
+
+Advanced asynchronous translator for Minecraft FTB Quests files (`.snbt`) with support for multiple local and cloud translation engines, featuring a 4-tab GUI and intelligent SQLite caching system.
+
+## Installation
+
+### Recommended Methods
+| Platform       | Command                          |
+|----------------|----------------------------------|
+| Arch Linux AUR | `yay -S snbt-tr`                 |
+| Flatpak        | `flatpak install org.mineai.snbt-tr` |
+| pipx           | `pipx install snbt-tr`           |
+| PyPI           | `pip install snbt-tr`            |
+
+### Manual Installation
+```bash
+git clone https://github.com/ronnikols/SNBT-AI-Localizer.git
+cd SNBT-AI-Localizer
+pip install -r requirements.txt
+```
+
+## Usage
+
+### Launch Methods
+- `snbt-tr` - Launches the interactive CLI setup wizard
+- `snbt-tr --gui` - Launches the PyQt6 GUI with dual-tab interface
+- `snbt-tr [options]` - Unattended batch execution
+
+### Examples
+```bash
+snbt-tr --list-models -p groq
+snbt-tr -d /path/to/quests -p groq -k YOUR_API_KEY
+snbt-tr --mix -d /path/to/quests
+snbt-tr --clear-cache
+snbt-tr --fastdir
+```
+
+## Features
+
+### 4-Tab GUI Architecture
+- **Workspace Tab**: Primary translation interface with provider/model selection, API key pool management (up to 10 keys), custom context input, target language dropdown, batch processing controls (Start/Pause/Stop), and live logging output
+- **Translation Memory Tab**: Visual cache manager with:
+  - Real-time search across original and translated text with 300ms debounce
+  - Modpack combobox filter for isolating translations by modpack
+  - Target language filter synchronized with Workspace tab
+  - 4-column QTableWidget (Original, Translation, Modpack, Added) with auto-stretch column width layout
+  - Inline editing of translations directly in the table
+  - Bulk operations: Load More (pagination), Delete Selected, Save Changes, Clear Cache
+- **Settings Tab**: Configuration management for providers, models, API keys, and application settings
+- **Credits Tab**: Displays project credits and acknowledgments
+
+### Asynchronous Processing
+- Non-blocking I/O with `asyncio` and `httpx.AsyncClient`
+- Configurable concurrency (1-10 threads)
+- Adaptive chunking:
+  - 5 items per chunk for Ollama (local inference)
+  - Configurable batch size (default: 50) for cloud providers
+- Automatic delays between chunks to prevent rate limiting
+
+### Fault Tolerance
+- Round-Robin multi-key pool with automatic load balancing
+- Invalid keys (HTTP 401/403) are permanently removed from the pool
+- Rate-limited keys (HTTP 429) enter exponential backoff (0.2s to 64s)
+- Fallback to single-item translation on chunk failure
+- Mixed Provider Mode: Auto-detects provider from key prefix and uses saved defaults
+- Binary split fallback for parse errors with recursive chunk splitting
+
+### Smart Caching System
+- SQLite-based cache with WAL mode for concurrent access
+- Per-language tables (`cache_{lang_code}`) to prevent cross-contamination
+- Modpack isolation: Translations can be filtered and managed by modpack
+- Thread-safe operations with locking
+- Real-time persistence between chunks
+- Defensive sanitization: Automatic cleanup of nested dictionaries in SNBT and protection against malformed JSON in responses
+
+### 🛡️ Pluralization Guard
+**Prevents redundant API calls for highly similar strings with a 90% similarity threshold**
+
+The Pluralization Guard is a sophisticated fuzzy-matching system that automatically detects and reuses translations for similar phrases, preventing duplicate API calls and saving costs. It works by:
+
+1. **Exact Match Check**: First attempts to find an exact match in the cache
+2. **Length Filtering**: Searches for candidates within ±15% length of the input text
+3. **Number Preservation**: Ensures strings with different numbers (e.g., "item 1" vs "item 2") are NOT matched
+4. **Fuzzy Matching**: Uses `difflib.SequenceMatcher` with a **90% similarity threshold**
+5. **Tail Preservation**: Maintains Minecraft formatting codes at the end of strings (e.g., "hello§a" → cached "привет" + "§a")
+
+**Example:**
+- Input: `"Get 5 diamonds"` → Cache miss
+- Input: `"Get 6 diamonds"` → **Cache hit!** (90%+ similarity, same structure)
+- Input: `"Get diamond"` → Cache miss (different number count)
+- Input: `"Get 5 diamonds§a"` → **Cache hit!** (matches "Get 5 diamonds" + preserves "§a")
+
+This prevents charging for translations of:
+- Plural variations: "apple" → "apples"
+- Number variations: "item 1" → "item 2" (if structure matches)
+- Minor formatting differences: "text" → "text§a"
+
+### Minecraft Formatting Protection
+- Regex shielding for namespace tags (`#c:ender_pearl_dusts`), UUIDs, and entity IDs
+- Temporary placeholder substitution (`__TAG_N__`) during translation
+- Preserves all Minecraft-specific formatting codes
+
+## Supported Providers
+
+| Provider | Default Model | Free Tier | Notes |
+|----------|----------------|-----------|-------|
+| Groq Cloud (Fast) | llama-3.3-70b-versatile | Yes | Low-latency inference |
+| NVIDIA NIM | nvidia/nemotron-4-340b-instruct | Yes | Enterprise-grade models |
+| OpenRouter (Cloud AI) | google/gemma-4-31b:free | Yes | 100+ free models |
+| Google Gemini (Free API) | models/gemini-3.1-flash-lite | Yes | Google's latest free model |
+| Sambanova | DeepSeek-V3.1 | No | High-performance inference |
+| OpenAI | gpt-4o-mini | No | Optimized for speed |
+| Mistral AI | mistral-large-latest | Yes | Open-source frontier models |
+| Anthropic (Claude) | claude-3-5-sonnet-20241022 | No | High-quality responses |
+| Cohere | command-r-plus | No | Production-ready |
+| Ollama (Local / Free) | qwen2.5:7b | Yes | Self-hosted, no API key |
+| Google Translate (Free) | N/A | Yes | Traditional MT, no API key |
+| Local LLM / Custom | (Custom) | Yes | Custom local models |
+
+## Feedback & Community
+For feedback, suggestions, and bug reports, please contact us via:
+- **Telegram**: [https://t.me/ronnikols](https://t.me/ronnikols)
+
+## License
+MIT License - see [LICENSE](LICENSE) for details.

snbt_tr-1.0.0/README.md

@@ -0,0 +1,129 @@
+<p align="center">
+  <img src="resources/logo.png" alt="SNBT AI Localizer Logo" width="200" height="200">
+</p> # SNBT AI Localizer
+
+English | [Русский](README_RU.md)
+
+Advanced asynchronous translator for Minecraft FTB Quests files (`.snbt`) with support for multiple local and cloud translation engines, featuring a 4-tab GUI and intelligent SQLite caching system.
+
+## Installation
+
+### Recommended Methods
+| Platform       | Command                          |
+|----------------|----------------------------------|
+| Arch Linux AUR | `yay -S snbt-tr`                 |
+| Flatpak        | `flatpak install org.mineai.snbt-tr` |
+| pipx           | `pipx install snbt-tr`           |
+| PyPI           | `pip install snbt-tr`            |
+
+### Manual Installation
+```bash
+git clone https://github.com/ronnikols/SNBT-AI-Localizer.git
+cd SNBT-AI-Localizer
+pip install -r requirements.txt
+```
+
+## Usage
+
+### Launch Methods
+- `snbt-tr` - Launches the interactive CLI setup wizard
+- `snbt-tr --gui` - Launches the PyQt6 GUI with dual-tab interface
+- `snbt-tr [options]` - Unattended batch execution
+
+### Examples
+```bash
+snbt-tr --list-models -p groq
+snbt-tr -d /path/to/quests -p groq -k YOUR_API_KEY
+snbt-tr --mix -d /path/to/quests
+snbt-tr --clear-cache
+snbt-tr --fastdir
+```
+
+## Features
+
+### 4-Tab GUI Architecture
+- **Workspace Tab**: Primary translation interface with provider/model selection, API key pool management (up to 10 keys), custom context input, target language dropdown, batch processing controls (Start/Pause/Stop), and live logging output
+- **Translation Memory Tab**: Visual cache manager with:
+  - Real-time search across original and translated text with 300ms debounce
+  - Modpack combobox filter for isolating translations by modpack
+  - Target language filter synchronized with Workspace tab
+  - 4-column QTableWidget (Original, Translation, Modpack, Added) with auto-stretch column width layout
+  - Inline editing of translations directly in the table
+  - Bulk operations: Load More (pagination), Delete Selected, Save Changes, Clear Cache
+- **Settings Tab**: Configuration management for providers, models, API keys, and application settings
+- **Credits Tab**: Displays project credits and acknowledgments
+
+### Asynchronous Processing
+- Non-blocking I/O with `asyncio` and `httpx.AsyncClient`
+- Configurable concurrency (1-10 threads)
+- Adaptive chunking:
+  - 5 items per chunk for Ollama (local inference)
+  - Configurable batch size (default: 50) for cloud providers
+- Automatic delays between chunks to prevent rate limiting
+
+### Fault Tolerance
+- Round-Robin multi-key pool with automatic load balancing
+- Invalid keys (HTTP 401/403) are permanently removed from the pool
+- Rate-limited keys (HTTP 429) enter exponential backoff (0.2s to 64s)
+- Fallback to single-item translation on chunk failure
+- Mixed Provider Mode: Auto-detects provider from key prefix and uses saved defaults
+- Binary split fallback for parse errors with recursive chunk splitting
+
+### Smart Caching System
+- SQLite-based cache with WAL mode for concurrent access
+- Per-language tables (`cache_{lang_code}`) to prevent cross-contamination
+- Modpack isolation: Translations can be filtered and managed by modpack
+- Thread-safe operations with locking
+- Real-time persistence between chunks
+- Defensive sanitization: Automatic cleanup of nested dictionaries in SNBT and protection against malformed JSON in responses
+
+### 🛡️ Pluralization Guard
+**Prevents redundant API calls for highly similar strings with a 90% similarity threshold**
+
+The Pluralization Guard is a sophisticated fuzzy-matching system that automatically detects and reuses translations for similar phrases, preventing duplicate API calls and saving costs. It works by:
+
+1. **Exact Match Check**: First attempts to find an exact match in the cache
+2. **Length Filtering**: Searches for candidates within ±15% length of the input text
+3. **Number Preservation**: Ensures strings with different numbers (e.g., "item 1" vs "item 2") are NOT matched
+4. **Fuzzy Matching**: Uses `difflib.SequenceMatcher` with a **90% similarity threshold**
+5. **Tail Preservation**: Maintains Minecraft formatting codes at the end of strings (e.g., "hello§a" → cached "привет" + "§a")
+
+**Example:**
+- Input: `"Get 5 diamonds"` → Cache miss
+- Input: `"Get 6 diamonds"` → **Cache hit!** (90%+ similarity, same structure)
+- Input: `"Get diamond"` → Cache miss (different number count)
+- Input: `"Get 5 diamonds§a"` → **Cache hit!** (matches "Get 5 diamonds" + preserves "§a")
+
+This prevents charging for translations of:
+- Plural variations: "apple" → "apples"
+- Number variations: "item 1" → "item 2" (if structure matches)
+- Minor formatting differences: "text" → "text§a"
+
+### Minecraft Formatting Protection
+- Regex shielding for namespace tags (`#c:ender_pearl_dusts`), UUIDs, and entity IDs
+- Temporary placeholder substitution (`__TAG_N__`) during translation
+- Preserves all Minecraft-specific formatting codes
+
+## Supported Providers
+
+| Provider | Default Model | Free Tier | Notes |
+|----------|----------------|-----------|-------|
+| Groq Cloud (Fast) | llama-3.3-70b-versatile | Yes | Low-latency inference |
+| NVIDIA NIM | nvidia/nemotron-4-340b-instruct | Yes | Enterprise-grade models |
+| OpenRouter (Cloud AI) | google/gemma-4-31b:free | Yes | 100+ free models |
+| Google Gemini (Free API) | models/gemini-3.1-flash-lite | Yes | Google's latest free model |
+| Sambanova | DeepSeek-V3.1 | No | High-performance inference |
+| OpenAI | gpt-4o-mini | No | Optimized for speed |
+| Mistral AI | mistral-large-latest | Yes | Open-source frontier models |
+| Anthropic (Claude) | claude-3-5-sonnet-20241022 | No | High-quality responses |
+| Cohere | command-r-plus | No | Production-ready |
+| Ollama (Local / Free) | qwen2.5:7b | Yes | Self-hosted, no API key |
+| Google Translate (Free) | N/A | Yes | Traditional MT, no API key |
+| Local LLM / Custom | (Custom) | Yes | Custom local models |
+
+## Feedback & Community
+For feedback, suggestions, and bug reports, please contact us via:
+- **Telegram**: [https://t.me/ronnikols](https://t.me/ronnikols)
+
+## License
+MIT License - see [LICENSE](LICENSE) for details.

snbt_tr-1.0.0/config.py

@@ -0,0 +1,366 @@
+import os
+import sys
+import argparse
+import logging
+from pathlib import Path
+from typing import List, Dict, Optional
+from core import is_valid_custom_instance, PROVIDER_DEFAULTS
+
+try:
+    from PyQt6.QtCore import QSettings
+except ImportError:
+    QSettings = None
+
+PROVIDER_ALIASES = {
+    "google": "Google Translate (Free)",
+    "google_free": "Google Translate (Free)",
+    "gemini": "Google Gemini (Free API)",
+    "ollama": "Ollama (Local / Free)",
+    "groq": "Groq Cloud (Fast)",
+    "openrouter": "OpenRouter (Cloud AI)",
+    "nvidia": "NVIDIA NIM",
+    "nim": "NVIDIA NIM",
+    "sambanova": "Sambanova",
+    "mixed": "Mixed Providers",
+    "mix": "Mixed Providers",
+    "openai": "OpenAI",
+    "mistral": "Mistral AI",
+    "anthropic": "Anthropic (Claude)",
+    "claude": "Anthropic (Claude)",
+    "cohere": "Cohere",
+    "local": "Local LLM / Custom",
+    "custom": "Local LLM / Custom",
+}
+
+PROVIDER_ENDPOINTS = {
+    "Google Gemini (Free API)": "https://generativelanguage.googleapis.com/v1beta/openai/models",
+    "Groq Cloud (Fast)": "https://api.groq.com/openai/v1/models",
+    "OpenRouter (Cloud AI)": "https://openrouter.ai/api/v1/models",
+    "NVIDIA NIM": "https://integrate.api.nvidia.com/v1/models",
+    "Ollama (Local / Free)": "http://localhost:11434/v1/models",
+    "Sambanova": "https://api.sambanova.ai/v1/models",
+    "OpenAI": "https://api.openai.com/v1/models",
+    "Mistral AI": "https://api.mistral.ai/v1/models",
+    "Anthropic (Claude)": "https://api.anthropic.com/v1/messages",
+    "Cohere": "https://api.cohere.ai/v1/chat",
+    "Local LLM / Custom": "",
+}
+
+LANG_ALIASES = {
+    "ru": ("Russian", "ru_ru"),
+    "en": ("English", "en_us"),
+    "es": ("Spanish", "es_es"),
+    "zh": ("Chinese Simplified", "zh_cn"),
+    "zh-cn": ("Chinese Simplified", "zh_cn"),
+    "zh-tw": ("Chinese Traditional", "zh_tw"),
+    "de": ("German", "de_de"),
+    "fr": ("French", "fr_fr"),
+    "pt": ("Portuguese", "pt_br"),
+    "pt-br": ("Portuguese", "pt_br"),
+    "ja": ("Japanese", "ja_jp"),
+    "ko": ("Korean", "ko_kr"),
+}
+
+ENV_KEY_MAP = {
+    "Google Gemini (Free API)": "GEMINI_API_KEY",
+    "Groq Cloud (Fast)": "GROQ_API_KEY",
+    "OpenRouter (Cloud AI)": "OPENROUTER_API_KEY",
+    "NVIDIA NIM": "NVIDIA_API_KEY",
+    "Sambanova": "SAMBANOVA_API_KEY",
+    "OpenAI": "OPENAI_API_KEY",
+    "Mistral AI": "MISTRAL_API_KEY",
+    "Anthropic (Claude)": "ANTHROPIC_API_KEY",
+    "Cohere": "COHERE_API_KEY",
+    "Local LLM / Custom": "",
+}
+
+SETTINGS_KEY_MAP = {
+    "Google Gemini (Free API)": "gemini_api_key",
+    "Groq Cloud (Fast)": "groq_api_key",
+    "OpenRouter (Cloud AI)": "openrouter_api_key",
+    "NVIDIA NIM": "nvidia_api_key",
+    "Sambanova": "sambanova_api_key",
+    "OpenAI": "openai_api_key",
+    "Mistral AI": "mistral_api_key",
+    "Anthropic (Claude)": "anthropic_api_key",
+    "Cohere": "cohere_api_key",
+    "Local LLM / Custom": "",
+}
+
+class ConfigManager:
+    AVAILABLE_PROVIDERS = [
+        "Groq Cloud (Fast)",
+        "NVIDIA NIM",
+        "OpenRouter (Cloud AI)",
+        "Google Gemini (Free API)",
+        "Sambanova",
+        "OpenAI",
+        "Mistral AI",
+        "Anthropic (Claude)",
+        "Cohere",
+        "Google Translate (Free)",
+        "Ollama (Local / Free)",
+        "Local LLM / Custom"
+    ]
+
+    def __init__(self):
+        self.quest_dir: Optional[Path] = None
+        self.target_lang: str = "ru_ru"
+        self.concurrency: int = 2
+        self.provider: str = "Google Translate (Free)"
+        self.model: Optional[str] = None
+        self.custom_context: str = ""
+        self.policy: str = "Complement (Дополнить)"
+        self.resource_pack_mode: bool = False
+        self.api_keys_pool: Dict[str, List[str]] = {prov: [] for prov in PROVIDER_ALIASES.values()}
+        self.custom_instances_paths: List[str] = []
+        self.batch_size: int = 50
+        self.min_batch_size: int = 1
+        self.max_concurrent_requests: int = 10
+
+        self.load_from_settings()
+
+    def _settings(self):
+        if QSettings is None:
+            return None
+        return QSettings("MineAI", "SNBT-Localizer")
+
+    def load_from_settings(self):
+        s = self._settings()
+        if s is None:
+            return
+
+        self.provider = s.value("provider", self.provider)
+        self.model = s.value("model", self.model)
+        if self.provider and self.provider != "Mixed Providers":
+            provider_model = s.value(f"model_{self.provider}", "")
+            if provider_model:
+                self.model = provider_model
+        self.target_lang = s.value("target_lang", self.target_lang)
+        self.concurrency = int(s.value("concurrency_limit", self.concurrency))
+        self.custom_context = s.value("custom_context", self.custom_context)
+        self.policy = s.value("policy", self.policy)
+
+        raw = s.value("custom_instances_paths", "")
+        if raw:
+            self.custom_instances_paths = [p.strip() for p in str(raw).splitlines() if p.strip()]
+
+        self.batch_size = int(s.value("batch_size", 50))
+        self.min_batch_size = int(s.value("min_batch_size", 1))
+        self.max_concurrent_requests = int(s.value("max_concurrent_requests", 10))
+        self.resource_pack_mode = s.value("resource_pack_mode", self.resource_pack_mode)
+        if isinstance(self.resource_pack_mode, str):
+            self.resource_pack_mode = self.resource_pack_mode.lower() == "true"
+        quest_dir_value = s.value("quest_dir", "")
+        self.quest_dir = Path(quest_dir_value) if quest_dir_value else None
+
+        for prov in PROVIDER_ALIASES.values():
+            raw = s.value(f"api_keys_pool_{prov}", "")
+            if raw:
+                lines = [line.strip() for line in str(raw).splitlines() if line.strip()]
+                seen = set()
+                unique = []
+                for k in lines:
+                    if k not in seen:
+                        seen.add(k)
+                        unique.append(k)
+                self.api_keys_pool[prov] = unique[:10]
+            if prov not in self.api_keys_pool:
+                self.api_keys_pool[prov] = []
+
+    def save_to_settings(self):
+        s = self._settings()
+        if s is None:
+            return
+
+        s.setValue("provider", self.provider)
+        s.setValue("model", self.model or "")
+        if self.provider and self.provider != "Mixed Providers":
+            s.setValue(f"model_{self.provider}", self.model or "")
+        s.setValue("target_lang", self.target_lang)
+        s.setValue("concurrency_limit", self.concurrency)
+        s.setValue("custom_context", self.custom_context)
+        s.setValue("policy", self.policy)
+        s.setValue("custom_instances_paths", "\n".join(self.custom_instances_paths))
+
+        for prov, keys in self.api_keys_pool.items():
+            s.setValue(f"api_keys_pool_{prov}", "\n".join(keys))
+
+        s.setValue("batch_size", self.batch_size)
+        s.setValue("min_batch_size", self.min_batch_size)
+        s.setValue("max_concurrent_requests", self.max_concurrent_requests)
+        s.setValue("resource_pack_mode", self.resource_pack_mode)
+        s.setValue("quest_dir", str(self.quest_dir) if self.quest_dir else "")
+        s.sync()
+
+    def parse_cli_args(self, args: Optional[List[str]] = None):
+        parser = argparse.ArgumentParser(prog='snbt-tr', add_help=False)
+        parser.add_argument("-h", "--help", action="help", help="Show this help message and exit")
+        parser.add_argument("-p", "--provider", help="Provider alias (google, gemini, groq, openrouter, nvidia, nim, sambanova)")
+        parser.add_argument("-m", "--model", help="Model name (default: provider default)")
+        parser.add_argument("-k", "--key", help="API key(s), comma-separated (env/QSettings fallback)")
+        parser.add_argument("-l", "--lang", default="ru", help="Language code (default: ru)")
+        parser.add_argument("-d", "--dir", default=".", help="Path to quests directory (default: .)")
+        parser.add_argument("-c", "--context", default="", help="Custom translation context")
+        parser.add_argument("--policy", default="complement", choices=["complement", "overwrite", "skip"],
+                            help="Existing files policy: complement, overwrite, skip (default: complement)")
+        parser.add_argument("--concurrency", type=int, default=2,
+                            help="Number of parallel translation threads (1-10, default: 3)")
+        parser.add_argument("--list-models", action="store_true", help="List available models for provider and exit")
+        parser.add_argument("--fastdir", "--fd", action="store_true", help="Scan launcher paths for instances and exit")
+        parser.add_argument("--clear-cache", "--clear", action="store_true", help="Clear translation cache and exit")
+        parser.add_argument("--debug", action="store_true", help="Enable debug logging to console")
+        parser.add_argument('--mix', action='store_true', help='Enable Mixed Provider mode using QSettings key pool')
+        parser.add_argument('--gui', action='store_true', help='Launch Graphical User Interface (GUI)')
+        parser.add_argument("--batch-size", type=int, default=50,
+                            help="Batch size for translation (default: 50)")
+        parser.add_argument("--min-batch-size", type=int, default=1,
+                            help="Minimum batch size before failing (default: 1)")
+        parser.add_argument("--max-concurrent-requests", type=int, default=10,
+                            help="Max concurrent API requests (default: 10)")
+        parser.add_argument("--resource-pack", "-r", action="store_true", help="Enable Resource Pack Mode for JSON translation")
+
+        parsed = parser.parse_args(args)
+
+        if parsed.provider:
+            alias = parsed.provider.lower()
+            if alias in PROVIDER_ALIASES:
+                self.provider = PROVIDER_ALIASES[alias]
+            else:
+                logging.getLogger("snbt_localizer.cli").error(f"Unknown provider alias: {parsed.provider}")
+                self.provider = "Google Translate (Free)"
+                sys.exit(1)
+
+        if parsed.mix:
+            self.provider = "Mixed Providers"
+
+        if parsed.model:
+            self.model = parsed.model
+
+        if parsed.lang:
+            lang_input = parsed.lang.lower()
+            if lang_input in LANG_ALIASES:
+                self.target_lang = LANG_ALIASES[lang_input][1]
+            else:
+                for alias, (name, code) in LANG_ALIASES.items():
+                    if lang_input == code or lang_input == name.lower():
+                        self.target_lang = code
+                        break
+                else:
+                    logging.getLogger("snbt_localizer.cli").error(f"Unknown language: {parsed.lang}")
+                    sys.exit(1)
+
+        if parsed.dir:
+            self.quest_dir = Path(parsed.dir)
+
+        if parsed.context:
+            self.custom_context = parsed.context
+
+        if parsed.policy:
+            mapping = {
+                "complement": "Complement (Дополнить)",
+                "overwrite": "Overwrite (Перезаписать)",
+                "skip": "Skip (Пропустить)",
+            }
+            self.policy = mapping.get(parsed.policy, "Complement (Дополнить)")
+
+        if parsed.concurrency:
+            self.concurrency = max(1, min(parsed.concurrency, 10))
+
+        if parsed.batch_size:
+            self.batch_size = max(1, parsed.batch_size)
+        if parsed.min_batch_size:
+            self.min_batch_size = max(1, parsed.min_batch_size)
+        if parsed.max_concurrent_requests:
+            self.max_concurrent_requests = max(1, parsed.max_concurrent_requests)
+
+
+        if parsed.key:
+            keys = [k.strip() for k in parsed.key.split(",") if k.strip()]
+            seen = set()
+            unique = []
+            for k in keys:
+                if k not in seen:
+                    seen.add(k)
+                    unique.append(k)
+            self.api_keys_pool[self.provider] = unique[:10]
+
+        return parsed
+
+    def get_api_keys(self, provider: Optional[str] = None) -> List[str]:
+        prov = provider or self.provider
+        return self.api_keys_pool.get(prov, [])
+
+    def set_api_keys(self, provider: str, keys: List[str]):
+        seen = set()
+        unique = []
+        for k in keys:
+            k = k.strip()
+            if k and k not in seen:
+                seen.add(k)
+                unique.append(k)
+        self.api_keys_pool[provider] = unique[:10]
+
+    def smart_parse_key(self, entry: str) -> tuple[str, str]:
+        entry = entry.strip()
+        if "\\" in entry:
+            parts = entry.split("\\", 1)
+            key = parts[0].strip()
+            model = parts[1].strip() if parts[1].strip() else ""
+            if model:
+                return key, model
+            # Trailing backslash with no model - use key part for prefix detection
+            entry = key
+        
+        if entry.startswith("gsk_"):
+            return entry, "llama-3.3-70b-versatile"
+        if entry.startswith("nvapi-"):
+            return entry, "nvidia/nemotron-3-ultra"
+        if entry.startswith("sk-or-"):
+            return entry, "meta-llama/llama-3.3-70b-instruct:free"
+        
+        raise ValueError(f"Unknown key format or provider prefix: {entry[:10]}...")
+
+    def get_all_available_keys(self) -> list[tuple[str, str, str]]:
+        result = []
+        for provider in self.AVAILABLE_PROVIDERS:
+            keys = self.get_api_keys(provider)
+            if not keys:
+                continue
+            
+            saved_model = ""
+            if QSettings is not None:
+                settings = QSettings("MineAI", "SNBT-Localizer")
+                saved_model = settings.value(f"model_{provider}", "") or ""
+            
+            default_model = PROVIDER_DEFAULTS.get(provider, "")
+            model = saved_model if saved_model else default_model
+            
+            for key in keys:
+                result.append((provider, key, model))
+        
+        return result
+
+    def resolve_language(self, lang_input: str) -> tuple:
+        lang_input = lang_input.lower()
+        if lang_input in LANG_ALIASES:
+            return LANG_ALIASES[lang_input]
+        for alias, (name, code) in LANG_ALIASES.items():
+            if lang_input == code or lang_input == name.lower():
+                return (name, code)
+        raise ValueError(f"Unknown language: {lang_input}")
+
+    def add_custom_path(self, path: str):
+        path = str(Path(path).resolve())
+        if path not in self.custom_instances_paths:
+            self.custom_instances_paths.append(path)
+            self.save_to_settings()
+
+    def prune_invalid_paths(self):
+        valid_paths = []
+        for p in self.custom_instances_paths:
+            if is_valid_custom_instance(Path(p)):
+                valid_paths.append(p)
+        if valid_paths != self.custom_instances_paths:
+            self.custom_instances_paths = valid_paths
+            self.save_to_settings()