Upload 10 files

.gitignore

@@ -0,0 +1,106 @@
+# ChineseScreenTranslator .gitignore
+# Author: algorembrant
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+parts/
+var/
+sdist/
+wheels/
+pip-wheel-metadata/
+.installed.cfg
+*.egg-info
+MANIFEST
+
+# Virtual environments
+venv/
+env/
+.venv/
+.env/
+ENV/
+.conda/
+Pipfile.lock
+
+# IDE / Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Logs
+*.log
+logs/
+
+# Config and user data (do not commit personal config)
+~/.chinese_screen_translator/
+config.json
+history.json
+
+# Downloaded ML models (large files - use Git LFS or exclude)
+models/
+*.bin
+*.safetensors
+*.pt
+*.pth
+*.ckpt
+*.onnx
+
+# EasyOCR model cache
+.EasyOCR/
+
+# Screenshots / temp images
+*.png
+*.jpg
+*.jpeg
+*.bmp
+*.tiff
+screenshots/
+temp/
+tmp/
+
+# OS artifacts
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Distribution / packaging
+*.tar.gz
+*.zip
+*.whl
+
+# Test artifacts
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb
+
+# PyInstaller
+*.spec
+dist/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 algorembrant
+
+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.

README.md

@@ -0,0 +1,327 @@
+---
+language:
+  - zh
+  - en
+tags:
+  - translation
+  - ocr
+  - screen-capture
+  - chinese
+  - easyocr
+  - marianmt
+license: mit
+library_name: transformers
+pipeline_tag: translation
+model-index:
+  - name: ChineseScreenTranslator
+    results:
+      - task:
+          type: translation
+          name: Chinese to English Screen OCR Translation
+        metrics:
+          - type: bleu
+            value: N/A
+            name: BLEU
+---
+
+# ChineseScreenTranslator
+
+[![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
+[![EasyOCR](https://img.shields.io/badge/OCR-EasyOCR-orange?style=flat-square)](https://github.com/JaidedAI/EasyOCR)
+[![HuggingFace](https://img.shields.io/badge/HuggingFace-Helsinki--NLP-FFD21E?style=flat-square&logo=huggingface&logoColor=black)](https://huggingface.co/Helsinki-NLP/opus-mt-zh-en)
+[![Google Translate](https://img.shields.io/badge/Backend-Google%20Translate-4285F4?style=flat-square&logo=googletranslate&logoColor=white)](https://translate.google.com)
+[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey?style=flat-square)](https://github.com)
+[![Author](https://img.shields.io/badge/Author-algorembrant-e94560?style=flat-square)](https://github.com/algorembrant)
+
+A screen region selection tool that automatically detects and translates Chinese text (Simplified, Traditional, Cantonese, Classical) to English in real time, powered by EasyOCR and neural machine translation.
+
+---
+
+## Features
+
+| Feature | Details |
+|---|---|
+| Screen Selection | Click-and-drag rubber-band region selector |
+| OCR Engine | EasyOCR - Simplified + Traditional Chinese |
+| Translation | Google Translate, Microsoft, or offline Helsinki-NLP |
+| Chinese Variants | Simplified, Traditional, Cantonese, Classical, Mixed |
+| Hotkey Trigger | Global configurable hotkey (default: Ctrl+Shift+S) |
+| Image Preprocessing | Upscale, contrast enhance, sharpen for accuracy |
+| History | Persistent JSON history with search and export |
+| Clipboard | Auto-copy or one-click copy |
+| Offline Mode | Helsinki-NLP MarianMT (opus-mt-zh-en) |
+| GPU Support | CUDA acceleration for OCR and offline translation |
+| Settings UI | Built-in settings window |
+
+---
+
+## Screenshots
+
+```
++--------------------------------------+
+|  ChineseScreenTranslator  v1.0.0     |
+|  Detected Chinese Text               |
+|  +----------------------------------+|
+|  | 你好，欢迎使用本翻译工具。         ||
+|  +----------------------------------+|
+|  English Translation                 |
+|  +----------------------------------+|
+|  | Hello, welcome to this           ||
+|  | translation tool.                ||
+|  +----------------------------------+|
+|  [Copy Translation] [Copy Source]    |
++--------------------------------------+
+```
+
+---
+
+## Requirements
+
+### System Requirements
+
+| Component | Minimum | Recommended |
+|---|---|---|
+| Python | 3.9 | 3.11+ |
+| RAM | 4 GB | 8 GB+ |
+| Disk Space | 1 GB | 2 GB (models + deps) |
+| GPU (optional) | CUDA 11.8 | CUDA 12.1 |
+| OS | Windows 10 / Ubuntu 20.04 / macOS 12 | Windows 11 / Ubuntu 22.04 |
+
+### First Run Downloads
+
+| Component | Size | Purpose |
+|---|---|---|
+| EasyOCR detection model | ~50 MB | Text region detection |
+| EasyOCR ch_sim model | ~90 MB | Simplified Chinese recognition |
+| EasyOCR ch_tra model | ~90 MB | Traditional Chinese recognition |
+| Helsinki-NLP opus-mt-zh-en | ~300 MB | Offline translation (optional) |
+
+---
+
+## Installation
+
+### Step 1 - Clone the repository
+
+```bash
+git clone https://github.com/algorembrant/ChineseScreenTranslator.git
+cd ChineseScreenTranslator
+```
+
+### Step 2 - Create a virtual environment (recommended)
+
+```bash
+python -m venv venv
+
+# Windows
+venv\Scripts\activate
+
+# Linux / macOS
+source venv/bin/activate
+```
+
+### Step 3 - Install PyTorch
+
+Choose the command that matches your hardware:
+
+| Hardware | Command |
+|---|---|
+| CPU only (any OS) | `pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu` |
+| NVIDIA GPU CUDA 11.8 | `pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118` |
+| NVIDIA GPU CUDA 12.1 | `pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121` |
+| macOS (Apple Silicon) | `pip install torch torchvision` |
+
+### Step 4 - Install remaining dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### Step 5 - Run the application
+
+```bash
+python translator.py
+```
+
+The first launch downloads OCR models (~230 MB total). This only happens once.
+
+---
+
+## Usage
+
+### Basic Usage
+
+| Action | How |
+|---|---|
+| Start application | `python translator.py` |
+| Trigger screen capture | Press `Ctrl+Shift+S` |
+| Select region | Click and drag on screen |
+| View translation | Result window appears automatically |
+| Copy translation | Click "Copy Translation" button |
+| View history | Press `Ctrl+Shift+H` |
+| Quit | Press `Ctrl+Shift+Q` or close window |
+
+### Keyboard Shortcuts
+
+| Shortcut | Action |
+|---|---|
+| `Ctrl+Shift+S` | Open screen region selector |
+| `Ctrl+Shift+C` | Copy last translation to clipboard |
+| `Ctrl+Shift+H` | Show/hide translation history |
+| `Ctrl+Shift+Q` | Quit application |
+| `Escape` | Cancel selection overlay |
+
+### Command Line Options
+
+| Option | Example | Description |
+|---|---|---|
+| `--hotkey` | `--hotkey "ctrl+alt+x"` | Set custom global hotkey |
+| `--lang` | `--lang traditional` | Force OCR language mode |
+| `--backend` | `--backend offline` | Set translation backend |
+| `--offline` | `--offline` | Use offline MarianMT model |
+| `--gpu` | `--gpu` | Enable CUDA GPU acceleration |
+| `--upscale` | `--upscale 3` | Upscale factor for small text |
+| `--confidence` | `--confidence 0.5` | OCR confidence threshold |
+| `--no-preprocess` | `--no-preprocess` | Disable image preprocessing |
+| `--export-history` | `--export-history out.json` | Export history on exit |
+| `--verbose` | `--verbose` | Enable DEBUG logging |
+| `--version` | `--version` | Show version and exit |
+| `--help` | `--help` | Show full help |
+
+### Translation Backends
+
+| Backend | Speed | Requires | Quality |
+|---|---|---|---|
+| `google` (default) | Fast | Internet | Excellent |
+| `microsoft` | Fast | Internet + API key | Excellent |
+| `offline` | Moderate | ~300 MB model | Good |
+
+For Microsoft Translator, add your Azure Cognitive Services key to `~/.chinese_screen_translator/config.json`:
+
+```json
+{
+  "microsoft_api_key": "YOUR_KEY_HERE",
+  "microsoft_region": "eastus"
+}
+```
+
+### Supported Chinese Variants
+
+| Variant | Mode | Notes |
+|---|---|---|
+| Simplified Chinese (普通话 / 简体) | `--lang simplified` | Mainland China standard |
+| Traditional Chinese (繁體中文) | `--lang traditional` | Taiwan, Hong Kong |
+| Cantonese / Yue (廣東話) | `--lang traditional` | Use traditional mode |
+| Classical Chinese (文言文) | `--lang auto` | Auto-detected |
+| Mixed Chinese-English | `--lang auto` | Handled by both models |
+| Vertical Chinese text | `--lang auto` | EasyOCR handles automatically |
+
+---
+
+## Configuration
+
+Config file location: `~/.chinese_screen_translator/config.json`
+
+```json
+{
+  "hotkey": "ctrl+shift+s",
+  "lang": "auto",
+  "backend": "google",
+  "use_gpu": false,
+  "upscale_factor": 2,
+  "confidence_threshold": 0.30,
+  "preprocess": true,
+  "auto_copy": false,
+  "show_confidence": true,
+  "max_history": 500,
+  "microsoft_api_key": "",
+  "microsoft_region": "eastus",
+  "offline_model_dir": "~/.chinese_screen_translator/models"
+}
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| `easyocr` not found | `pip install easyocr` then install PyTorch |
+| Models not downloading | Check internet connection; proxy may block HuggingFace CDN |
+| Hotkeys not working on Linux | Run as root: `sudo python translator.py` |
+| Low OCR accuracy | Increase `--upscale 3`, zoom in on text, improve lighting |
+| `keyboard` error on macOS | Grant Accessibility permissions in System Preferences |
+| Out of memory | Use CPU mode (no `--gpu`), reduce `--upscale` |
+| No text detected | Lower `--confidence 0.2`, ensure text is clear and large enough |
+| Google Translate blocked | Use `--backend offline` or set up Microsoft API key |
+
+---
+
+## Project Structure
+
+```
+ChineseScreenTranslator/
+  translator.py          Main application (single file)
+  requirements.txt       Python dependencies
+  README.md              This file
+  .gitignore             Git ignore rules
+  .gitattributes         Git / HuggingFace LFS config
+  LICENSE                MIT License
+```
+
+---
+
+## Architecture
+
+```
+Hotkey / Button
+     |
+     v
+ScreenOverlay (tkinter fullscreen transparent)
+     |  click + drag
+     v
+_capture_screenshot (mss / PIL)
+     |
+     v
+ImagePreprocessor
+  - Upscale (Lanczos)
+  - Contrast enhance
+  - Sharpen
+     |
+     v
+OCREngine (EasyOCR)
+  - ch_sim reader
+  - ch_tra reader
+  - Auto-detect or forced mode
+     |
+     v
+TranslationEngine
+  - Google Translate (deep-translator)
+  - Microsoft Translator
+  - Helsinki-NLP MarianMT (offline)
+     |
+     v
+ResultWindow (tkinter)
+HistoryManager (JSON persistence)
+```
+
+---
+
+## License
+
+MIT License. See `LICENSE` for details.
+
+---
+
+## Author
+
+**algorembrant**
+
+---
+
+## Acknowledgments
+
+- [EasyOCR](https://github.com/JaidedAI/EasyOCR) - OCR engine by JaidedAI
+- [Helsinki-NLP](https://huggingface.co/Helsinki-NLP) - MarianMT translation models
+- [deep-translator](https://github.com/nidhaloff/deep-translator) - Translation backends
+- [mss](https://github.com/BoboTiG/python-mss) - Fast screen capture

ci.yml

@@ -0,0 +1,82 @@
+# .github/workflows/ci.yml
+# ChineseScreenTranslator CI
+# Author: algorembrant
+
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint-and-test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.9", "3.11"]
+      fail-fast: false
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install PyTorch (CPU)
+        run: |
+          pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install flake8 pyflakes
+
+      - name: Lint with flake8
+        run: |
+          flake8 translator.py --max-line-length=100 --ignore=E501,W503 --count --statistics
+
+      - name: Syntax check
+        run: |
+          python -m py_compile translator.py
+          echo "Syntax OK"
+
+      - name: Import check (no GUI display required)
+        run: |
+          python -c "
+          import sys
+          # Mock tkinter display for headless CI
+          import os
+          os.environ.setdefault('DISPLAY', ':99')
+          print('Import check passed')
+          print(f'Python {sys.version}')
+          "
+
+  release:
+    needs: lint-and-test
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create release archive
+        run: |
+          zip -r ChineseScreenTranslator.zip \
+            translator.py \
+            requirements.txt \
+            README.md \
+            LICENSE \
+            .gitattributes \
+            .gitignore
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ChineseScreenTranslator-release
+          path: ChineseScreenTranslator.zip
+          retention-days: 30

list_langs.py

@@ -0,0 +1,10 @@
+from deep_translator import GoogleTranslator
+import json
+
+try:
+    langs = GoogleTranslator().get_supported_languages(as_dict=True)
+    with open("supported_langs.json", "w", encoding="utf-8") as f:
+        json.dump(langs, f, indent=2)
+    print("Languages saved to supported_langs.json")
+except Exception as e:
+    print(f"Error: {e}")

requirements.txt

@@ -0,0 +1,52 @@
+# ChineseScreenTranslator - Python Dependencies
+# Author: algorembrant
+# Version: 1.0.0
+#
+# INSTALL ORDER (important):
+# 1. Install PyTorch first (see note below)
+# 2. pip install -r requirements.txt
+#
+# PyTorch (NOT included here - install separately based on your hardware):
+#
+#   CPU only (Windows/Linux):
+#       pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
+#
+#   CUDA 11.8 (NVIDIA GPU):
+#       pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
+#
+#   CUDA 12.1 (NVIDIA GPU):
+#       pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
+#
+#   macOS (Apple Silicon / Intel):
+#       pip install torch torchvision
+#
+# After PyTorch, install everything else:
+#   pip install -r requirements.txt
+
+# ── Image Processing ──────────────────────────────────────────────────────────
+Pillow>=10.0.0
+mss>=9.0.0
+numpy>=1.24.0
+opencv-python>=4.8.0
+
+# ── OCR ───────────────────────────────────────────────────────────────────────
+easyocr>=1.7.0
+
+# ── Translation (Online) ──────────────────────────────────────────────────────
+deep-translator>=1.11.0
+
+# ── Translation (Offline / Optional) ─────────────────────────────────────────
+# Uncomment for offline Helsinki-NLP support:
+# transformers>=4.35.0
+# sentencepiece>=0.1.99
+# sacremoses>=0.0.53
+
+# ── Hotkeys ───────────────────────────────────────────────────────────────────
+keyboard>=0.13.5
+
+# ── Clipboard ─────────────────────────────────────────────────────────────────
+pyperclip>=1.8.2
+
+# ── Utilities ─────────────────────────────────────────────────────────────────
+requests>=2.31.0
+urllib3>=2.0.0

supported_langs.json

@@ -0,0 +1,135 @@
+{
+  "afrikaans": "af",
+  "albanian": "sq",
+  "amharic": "am",
+  "arabic": "ar",
+  "armenian": "hy",
+  "assamese": "as",
+  "aymara": "ay",
+  "azerbaijani": "az",
+  "bambara": "bm",
+  "basque": "eu",
+  "belarusian": "be",
+  "bengali": "bn",
+  "bhojpuri": "bho",
+  "bosnian": "bs",
+  "bulgarian": "bg",
+  "catalan": "ca",
+  "cebuano": "ceb",
+  "chichewa": "ny",
+  "chinese (simplified)": "zh-CN",
+  "chinese (traditional)": "zh-TW",
+  "corsican": "co",
+  "croatian": "hr",
+  "czech": "cs",
+  "danish": "da",
+  "dhivehi": "dv",
+  "dogri": "doi",
+  "dutch": "nl",
+  "english": "en",
+  "esperanto": "eo",
+  "estonian": "et",
+  "ewe": "ee",
+  "filipino": "tl",
+  "finnish": "fi",
+  "french": "fr",
+  "frisian": "fy",
+  "galician": "gl",
+  "georgian": "ka",
+  "german": "de",
+  "greek": "el",
+  "guarani": "gn",
+  "gujarati": "gu",
+  "haitian creole": "ht",
+  "hausa": "ha",
+  "hawaiian": "haw",
+  "hebrew": "iw",
+  "hindi": "hi",
+  "hmong": "hmn",
+  "hungarian": "hu",
+  "icelandic": "is",
+  "igbo": "ig",
+  "ilocano": "ilo",
+  "indonesian": "id",
+  "irish": "ga",
+  "italian": "it",
+  "japanese": "ja",
+  "javanese": "jw",
+  "kannada": "kn",
+  "kazakh": "kk",
+  "khmer": "km",
+  "kinyarwanda": "rw",
+  "konkani": "gom",
+  "korean": "ko",
+  "krio": "kri",
+  "kurdish (kurmanji)": "ku",
+  "kurdish (sorani)": "ckb",
+  "kyrgyz": "ky",
+  "lao": "lo",
+  "latin": "la",
+  "latvian": "lv",
+  "lingala": "ln",
+  "lithuanian": "lt",
+  "luganda": "lg",
+  "luxembourgish": "lb",
+  "macedonian": "mk",
+  "maithili": "mai",
+  "malagasy": "mg",
+  "malay": "ms",
+  "malayalam": "ml",
+  "maltese": "mt",
+  "maori": "mi",
+  "marathi": "mr",
+  "meiteilon (manipuri)": "mni-Mtei",
+  "mizo": "lus",
+  "mongolian": "mn",
+  "myanmar": "my",
+  "nepali": "ne",
+  "norwegian": "no",
+  "odia (oriya)": "or",
+  "oromo": "om",
+  "pashto": "ps",
+  "persian": "fa",
+  "polish": "pl",
+  "portuguese": "pt",
+  "punjabi": "pa",
+  "quechua": "qu",
+  "romanian": "ro",
+  "russian": "ru",
+  "samoan": "sm",
+  "sanskrit": "sa",
+  "scots gaelic": "gd",
+  "sepedi": "nso",
+  "serbian": "sr",
+  "sesotho": "st",
+  "shona": "sn",
+  "sindhi": "sd",
+  "sinhala": "si",
+  "slovak": "sk",
+  "slovenian": "sl",
+  "somali": "so",
+  "spanish": "es",
+  "sundanese": "su",
+  "swahili": "sw",
+  "swedish": "sv",
+  "tajik": "tg",
+  "tamil": "ta",
+  "tatar": "tt",
+  "telugu": "te",
+  "thai": "th",
+  "tigrinya": "ti",
+  "tsonga": "ts",
+  "turkish": "tr",
+  "turkmen": "tk",
+  "twi": "ak",
+  "ukrainian": "uk",
+  "urdu": "ur",
+  "uyghur": "ug",
+  "uzbek": "uz",
+  "vietnamese": "vi",
+  "welsh": "cy",
+  "xhosa": "xh",
+  "yiddish": "yi",
+  "yoruba": "yo",
+  "zulu": "zu"
+}

test_results.json

@@ -0,0 +1,6 @@
+{
+  "original": "在尊嚴和權利上",
+  "auto": "在尊嚴和權利上",
+  "zht": "in dignity and rights",
+  "zhc": "in dignity and rights"
+}

test_translate.py

@@ -0,0 +1,18 @@
+from deep_translator import GoogleTranslator
+import json
+
+text = "在尊嚴和權利上"
+results = {"original": text}
+
+try:
+    results["auto"] = GoogleTranslator(source='auto', target='en').translate(text)
+    
+    results["zht"] = GoogleTranslator(source='zh-TW', target='en').translate(text)
+
+    results["zhc"] = GoogleTranslator(source='zh-CN', target='en').translate(text)
+
+except Exception as e:
+    results["error"] = str(e)
+
+with open("test_results.json", "w", encoding="utf-8") as f:
+    json.dump(results, f, indent=2, ensure_ascii=False)

translator.py

@@ -0,0 +1,1688 @@
+#!/usr/bin/env python3
+"""
+ChineseScreenTranslator v1.0.0
+================================
+Author  : algorembrant
+License : MIT
+Version : 1.0.0
+
+A screen region selection tool that automatically detects and translates
+Chinese text (Simplified, Traditional, Cantonese, Classical) to English
+using OCR (EasyOCR) and neural machine translation.
+
+USAGE COMMANDS
+--------------
+Run (default, hotkey mode):
+    python translator.py
+
+Run with custom hotkey:
+    python translator.py --hotkey "ctrl+shift+t"
+
+Run in offline translation mode (Helsinki-NLP MarianMT):
+    python translator.py --offline
+
+Force Simplified Chinese OCR:
+    python translator.py --lang simplified
+
+Force Traditional Chinese OCR:
+    python translator.py --lang traditional
+
+Auto-detect Chinese script (default):
+    python translator.py --lang auto
+
+Enable GPU acceleration for OCR/translation (requires CUDA):
+    python translator.py --gpu
+
+Set translation backend:
+    python translator.py --backend google
+    python translator.py --backend microsoft
+    python translator.py --backend offline
+
+Set confidence threshold (0.0 - 1.0, default 0.3):
+    python translator.py --confidence 0.5
+
+Enable verbose/debug logging:
+    python translator.py --verbose
+
+Export history to file on exit:
+    python translator.py --export-history history.json
+
+Set image upscale factor for small text (1-4, default 2):
+    python translator.py --upscale 3
+
+Disable image preprocessing:
+    python translator.py --no-preprocess
+
+Show version and exit:
+    python translator.py --version
+
+Show full help:
+    python translator.py --help
+
+KEYBOARD SHORTCUTS (global, while app is running)
+--------------------------------------------------
+Alt+S           : Open screen region selector
+Ctrl+Shift+C    : Copy last translation to clipboard
+Ctrl+Shift+H    : Show/hide translation history
+Ctrl+Shift+Q    : Quit application
+Escape          : Cancel selection or close overlay
+
+SUPPORTED CHINESE VARIANTS
+---------------------------
+- Simplified Chinese    (Mandarin, 简体中文)
+- Traditional Chinese   (Mandarin, 繁體中文)
+- Cantonese / Yue       (廣東話, 粵語)
+- Classical Chinese     (文言文, Literary Chinese)
+- Mixed Chinese-English (Chinglish / code-switching text)
+- Vertical Chinese text (auto-handled by EasyOCR)
+
+TRANSLATION BACKENDS
+--------------------
+1. Google Translate     (online, fast, default)
+2. Microsoft Translate  (online, fallback, requires API key in config)
+3. Helsinki-NLP MarianMT (offline, opus-mt-zh-en, downloaded on first use ~300MB)
+
+EXTERNAL SETUP REQUIRED
+-----------------------
+PyTorch (required for EasyOCR):
+    CPU-only:
+        pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
+    CUDA 11.8:
+        pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
+    CUDA 12.1:
+        pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
+
+EasyOCR models are downloaded automatically on first run:
+    - ch_sim model  : ~90 MB
+    - ch_tra model  : ~90 MB
+    - detection model: ~50 MB
+    Total: ~230 MB on first launch
+
+Microsoft Translator (optional):
+    Get a free API key from Azure Cognitive Services and add to config.json:
+    { "microsoft_api_key": "YOUR_KEY_HERE", "microsoft_region": "eastus" }
+"""
+
+# ── Standard Library ──────────────────────────────────────────────────────────
+import os
+import sys
+import json
+import logging
+import threading
+import time
+import argparse
+import textwrap
+from pathlib import Path
+from datetime import datetime
+from typing import Optional, Tuple, List, Dict, Any
+from queue import Queue, Empty
+
+# ── GUI ───────────────────────────────────────────────────────────────────────
+import tkinter as tk
+from tkinter import ttk, scrolledtext, messagebox, filedialog
+
+# ── Image Processing ──────────────────────────────────────────────────────────
+try:
+    from PIL import Image, ImageTk, ImageDraw, ImageFilter, ImageEnhance, ImageOps, ImageGrab
+    PIL_AVAILABLE = True
+except ImportError:
+    PIL_AVAILABLE = False
+    print("[FATAL] Pillow not installed. Run: pip install Pillow")
+    sys.exit(1)
+
+try:
+    import mss
+    import mss.tools
+    MSS_AVAILABLE = True
+except ImportError:
+    MSS_AVAILABLE = False
+
+try:
+    import numpy as np
+    NUMPY_AVAILABLE = True
+except ImportError:
+    NUMPY_AVAILABLE = False
+    print("[FATAL] NumPy not installed. Run: pip install numpy")
+    sys.exit(1)
+
+# ── OCR Engine ────────────────────────────────────────────────────────────────
+try:
+    import easyocr
+    EASYOCR_AVAILABLE = True
+except ImportError:
+    EASYOCR_AVAILABLE = False
+    print("[WARN] EasyOCR not installed. Run: pip install easyocr")
+
+# ── Online Translation ────────────────────────────────────────────────────────
+try:
+    from deep_translator import GoogleTranslator, MicrosoftTranslator
+    DEEP_TRANSLATOR_AVAILABLE = True
+except ImportError:
+    DEEP_TRANSLATOR_AVAILABLE = False
+    print("[WARN] deep-translator not installed. Run: pip install deep-translator")
+
+# ── Offline Translation ───────────────────────────────────────────────────────
+OFFLINE_TRANSLATION_AVAILABLE = False
+try:
+    from transformers import MarianMTModel, MarianTokenizer
+    import torch
+    OFFLINE_TRANSLATION_AVAILABLE = True
+except ImportError:
+    pass
+
+# ── Clipboard ─────────────────────────────────────────────────────────────────
+try:
+    import pyperclip
+    CLIPBOARD_AVAILABLE = True
+except ImportError:
+    CLIPBOARD_AVAILABLE = False
+
+# ── Global Hotkeys ────────────────────────────────────────────────────────────
+try:
+    import keyboard as kb
+    KEYBOARD_AVAILABLE = True
+except ImportError:
+    KEYBOARD_AVAILABLE = False
+    print("[WARN] keyboard not installed. Run: pip install keyboard")
+
+# ── Constants ─────────────────────────────────────────────────────────────────
+APP_NAME    = "ChineseScreenTranslator"
+APP_VERSION = "1.0.0"
+APP_AUTHOR  = "algorembrant"
+CONFIG_FILE = Path.home() / ".chinese_screen_translator" / "config.json"
+HISTORY_FILE = Path.home() / ".chinese_screen_translator" / "history.json"
+LOG_FILE    = Path.home() / ".chinese_screen_translator" / "app.log"
+
+OFFLINE_MODEL_ZH_EN   = "Helsinki-NLP/opus-mt-zh-en"
+OFFLINE_MODEL_ZHT_EN  = "Helsinki-NLP/opus-mt-zht-en"
+
+COLORS = {
+    "bg_dark"       : "#1a1a2e",
+    "bg_mid"        : "#16213e",
+    "bg_light"      : "#0f3460",
+    "accent"        : "#e94560",
+    "accent_hover"  : "#c73652",
+    "text_primary"  : "#eaeaea",
+    "text_secondary": "#a0a0b0",
+    "success"       : "#4ecca3",
+    "warning"       : "#f6c90e",
+    "border"        : "#2a2a4a",
+    "selection"     : "rgba(233,69,96,0.3)",
+}
+
+# ── Logging Setup ─────────────────────────────────────────────────────────────
+def setup_logging(verbose: bool = False) -> logging.Logger:
+    LOG_FILE.parent.mkdir(parents=True, exist_ok=True)
+    level = logging.DEBUG if verbose else logging.INFO
+    fmt = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+    logging.basicConfig(
+        level=level,
+        format=fmt,
+        handlers=[
+            logging.FileHandler(LOG_FILE, encoding="utf-8"),
+            logging.StreamHandler(sys.stdout),
+        ],
+    )
+    return logging.getLogger(APP_NAME)
+
+logger = logging.getLogger(APP_NAME)
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# CONFIG
+# ════════════════════════════════════════════════════════════════════════════
+class Config:
+    """Persistent JSON configuration manager."""
+
+    DEFAULTS: Dict[str, Any] = {
+        "hotkey"              : "alt+s",
+        "lang"                : "auto",
+        "backend"             : "google",
+        "use_gpu"             : False,
+        "upscale_factor"      : 2,
+        "confidence_threshold": 0.30,
+        "preprocess"          : True,
+        "window_opacity"      : 0.25,
+        "result_font_size"    : 13,
+        "max_history"         : 500,
+        "microsoft_api_key"   : "",
+        "microsoft_region"    : "eastus",
+        "auto_copy"           : False,
+        "show_confidence"     : True,
+        "offline_model_dir"   : str(Path.home() / ".chinese_screen_translator" / "models"),
+    }
+
+    def __init__(self):
+        self._data: Dict[str, Any] = dict(self.DEFAULTS)
+        CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
+        self.load()
+
+    def load(self):
+        if CONFIG_FILE.exists():
+            try:
+                with open(CONFIG_FILE, "r", encoding="utf-8") as f:
+                    saved = json.load(f)
+                # Migration: if legacy hotkey is found, update to new default
+                if saved.get("hotkey") == "ctrl+shift+s":
+                    saved["hotkey"] = "alt+s"
+                self._data.update(saved)
+            except Exception as e:
+                logger.warning(f"Config load failed: {e}. Using defaults.")
+
+    def save(self):
+        try:
+            with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+                json.dump(self._data, f, indent=2, ensure_ascii=False)
+        except Exception as e:
+            logger.error(f"Config save failed: {e}")
+
+    def get(self, key: str, default=None):
+        return self._data.get(key, self.DEFAULTS.get(key, default))
+
+    def set(self, key: str, value: Any):
+        self._data[key] = value
+        self.save()
+
+    def apply_args(self, args: argparse.Namespace):
+        """Override config with CLI arguments."""
+        mapping = {
+            "hotkey"    : "hotkey",
+            "lang"      : "lang",
+            "backend"   : "backend",
+            "gpu"       : "use_gpu",
+            "upscale"   : "upscale_factor",
+            "confidence": "confidence_threshold",
+            "offline"   : None,
+        }
+        if getattr(args, "hotkey", None):
+            self.set("hotkey", args.hotkey)
+        if getattr(args, "lang", None):
+            self.set("lang", args.lang)
+        if getattr(args, "backend", None):
+            self.set("backend", args.backend)
+        if getattr(args, "gpu", False):
+            self.set("use_gpu", True)
+        if getattr(args, "upscale", None):
+            self.set("upscale_factor", args.upscale)
+        if getattr(args, "confidence", None):
+            self.set("confidence_threshold", args.confidence)
+        if getattr(args, "offline", False):
+            self.set("backend", "offline")
+        if getattr(args, "no_preprocess", False):
+            self.set("preprocess", False)
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# IMAGE PREPROCESSOR
+# ════════════════════════════════════════════════════════════════════════════
+class ImagePreprocessor:
+    """Enhance screenshots for better Chinese OCR accuracy."""
+
+    def __init__(self, config: Config):
+        self.cfg = config
+
+    def preprocess(self, img: Image.Image) -> Image.Image:
+        """Apply preprocessing pipeline to improve OCR quality."""
+        if not self.cfg.get("preprocess"):
+            return img
+
+        # 1. Upscale for small text
+        factor = self.cfg.get("upscale_factor", 2)
+        if factor > 1:
+            w, h = img.size
+            img = img.resize((w * factor, h * factor), Image.LANCZOS)
+
+        # 2. Convert to RGB (drop alpha channel if present)
+        if img.mode == "RGBA":
+            bg = Image.new("RGB", img.size, (255, 255, 255))
+            bg.paste(img, mask=img.split()[3])
+            img = bg
+        elif img.mode != "RGB":
+            img = img.convert("RGB")
+
+        # 3. Adaptive contrast enhancement
+        enhancer = ImageEnhance.Contrast(img)
+        img = enhancer.enhance(1.5)
+
+        # 4. Mild sharpening
+        img = img.filter(ImageFilter.SHARPEN)
+
+        # 5. Brightness normalization
+        enhancer = ImageEnhance.Brightness(img)
+        img = enhancer.enhance(1.1)
+
+        return img
+
+    @staticmethod
+    def pil_to_numpy(img: Image.Image) -> np.ndarray:
+        return np.array(img)
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# OCR ENGINE
+# ════════════════════════════════════════════════════════════════════════════
+class OCREngine:
+    """
+    EasyOCR-based OCR engine supporting all Chinese script variants.
+    Lazy-loads readers to avoid startup delay.
+    """
+
+    def __init__(self, config: Config):
+        self.cfg = config
+        self._reader_sim: Optional[Any]  = None
+        self._reader_tra: Optional[Any]  = None
+        self._initialized               = False
+        self._init_lock                 = threading.Lock()
+        self.preprocessor               = ImagePreprocessor(config)
+
+    def _get_reader(self, script: str) -> Any:
+        """Return (and lazy-init) the appropriate EasyOCR reader."""
+        if not EASYOCR_AVAILABLE:
+            raise RuntimeError(
+                "EasyOCR not installed. Run:\n"
+                "  pip install easyocr\n"
+                "  pip install torch torchvision --index-url "
+                "https://download.pytorch.org/whl/cpu"
+            )
+        use_gpu = self.cfg.get("use_gpu", False)
+        with self._init_lock:
+            if script == "traditional":
+                if self._reader_tra is None:
+                    logger.info("Loading Traditional Chinese OCR model...")
+                    self._reader_tra = easyocr.Reader(
+                        ["ch_tra", "en"], gpu=use_gpu, verbose=False
+                    )
+                return self._reader_tra
+            else:  # simplified (default)
+                if self._reader_sim is None:
+                    logger.info("Loading Simplified Chinese OCR model...")
+                    self._reader_sim = easyocr.Reader(
+                        ["ch_sim", "en"], gpu=use_gpu, verbose=False
+                    )
+                return self._reader_sim
+
+    def extract_text(
+        self, img: Image.Image
+    ) -> Tuple[str, float, str]:
+        """
+        Extract Chinese text from image.
+        Returns (text, avg_confidence, detected_script).
+        """
+        img = self.preprocessor.preprocess(img)
+        img_np = self.preprocessor.pil_to_numpy(img)
+
+        lang_mode = self.cfg.get("lang", "auto")
+        threshold = self.cfg.get("confidence_threshold", 0.30)
+
+        if lang_mode == "traditional":
+            return self._run_ocr(img_np, "traditional", threshold)
+        elif lang_mode == "simplified":
+            return self._run_ocr(img_np, "simplified", threshold)
+        else:
+            # Auto-detect: run both, pick higher confidence
+            text_sim, conf_sim, _ = self._run_ocr(img_np, "simplified", threshold)
+            text_tra, conf_tra, _ = self._run_ocr(img_np, "traditional", threshold)
+            if conf_tra > conf_sim and text_tra.strip():
+                return text_tra, conf_tra, "traditional"
+            return text_sim, conf_sim, "simplified"
+
+    def _run_ocr(
+        self, img_np: np.ndarray, script: str, threshold: float
+    ) -> Tuple[str, float, str]:
+        reader = self._get_reader(script)
+        results = reader.readtext(img_np, detail=1, paragraph=False)
+
+        lines: List[str] = []
+        confidences: List[float] = []
+
+        for (_, text, conf) in results:
+            if conf >= threshold and text.strip():
+                lines.append(text.strip())
+                confidences.append(conf)
+
+        combined = " ".join(lines)
+        avg_conf = float(np.mean(confidences)) if confidences else 0.0
+        return combined, avg_conf, script
+
+    def preload(self):
+        """Preload both readers in background threads."""
+        def _load_sim():
+            try:
+                self._get_reader("simplified")
+                logger.info("Simplified Chinese OCR model ready.")
+            except Exception as e:
+                logger.error(f"Simplified OCR load error: {e}")
+
+        def _load_tra():
+            try:
+                self._get_reader("traditional")
+                logger.info("Traditional Chinese OCR model ready.")
+            except Exception as e:
+                logger.error(f"Traditional OCR load error: {e}")
+
+        threading.Thread(target=_load_sim, daemon=True).start()
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# TRANSLATION ENGINE
+# ════════════════════════════════════════════════════════════════════════════
+class TranslationEngine:
+    """
+    Multi-backend Chinese-to-English translation engine.
+    Backends: Google, Microsoft, Helsinki-NLP (offline).
+    """
+
+    def __init__(self, config: Config):
+        self.cfg              = config
+        self._offline_model   = None
+        self._offline_tok     = None
+        self._offline_lock    = threading.Lock()
+
+    def translate(
+        self, text: str, source_lang: str = "auto"
+    ) -> Tuple[str, str]:
+        """
+        Translate text to English.
+        Returns (translated_text, backend_used).
+        Raises RuntimeError if all backends fail.
+        """
+        if not text or not text.strip():
+            return "", "none"
+
+        backend = self.cfg.get("backend", "google")
+
+        if backend == "offline":
+            return self._translate_offline(text)
+
+        # Online backends with fallback chain
+        for attempt_backend in [backend, "google", "offline"]:
+            try:
+                if attempt_backend == "google":
+                    return self._translate_google(text, source_lang), "google"
+                elif attempt_backend == "microsoft":
+                    return self._translate_microsoft(text, source_lang), "microsoft"
+                elif attempt_backend == "offline":
+                    return self._translate_offline(text)
+            except Exception as e:
+                msg = str(e)
+                if "not installed" in msg:
+                    logger.warning(f"Backend '{attempt_backend}' unavailable: {msg}")
+                else:
+                    logger.warning(f"Backend '{attempt_backend}' failed: {e}")
+                continue
+
+        raise RuntimeError("All translation backends failed.")
+
+    def _translate_google(self, text: str, source_lang: str = "auto") -> str:
+        if not DEEP_TRANSLATOR_AVAILABLE:
+            raise RuntimeError("deep-translator not installed.")
+        
+        # Map internal script names to Google Translate codes
+        lang_map = {
+            "simplified": "zh-CN",
+            "traditional": "zh-TW",
+            "auto": "auto"
+        }
+        src = lang_map.get(source_lang, "auto")
+        
+        translator = GoogleTranslator(source=src, target="en")
+        # Google Translate has a 5000 char limit per request
+        if len(text) > 4500:
+            chunks = self._chunk_text(text, 4500)
+            return " ".join(translator.translate(c) for c in chunks)
+        return translator.translate(text)
+
+    def _translate_microsoft(self, text: str, source_lang: str = "auto") -> str:
+        if not DEEP_TRANSLATOR_AVAILABLE:
+            raise RuntimeError("deep-translator not installed.")
+        api_key = self.cfg.get("microsoft_api_key", "")
+        region  = self.cfg.get("microsoft_region", "eastus")
+        if not api_key:
+            raise ValueError("Microsoft API key not configured.")
+        
+        # Map internal script names to Microsoft codes (uses same zh-Hans/zh-Hant vs zh-CN/zh-TW)
+        # deep-translator's Microsoft backend handles 'auto'
+        lang_map = {
+            "simplified": "zh-Hans",
+            "traditional": "zh-Hant",
+            "auto": "auto"
+        }
+        src = lang_map.get(source_lang, "auto")
+        
+        translator = MicrosoftTranslator(
+            api_key=api_key, region=region, source=src, target="en"
+        )
+        return translator.translate(text)
+
+    def _translate_offline(self, text: str) -> Tuple[str, str]:
+        if not OFFLINE_TRANSLATION_AVAILABLE:
+            raise RuntimeError(
+                "transformers/torch not installed for offline mode.\n"
+                "Run: pip install transformers torch"
+            )
+        with self._offline_lock:
+            if self._offline_model is None:
+                logger.info(f"Loading offline model '{OFFLINE_MODEL_ZH_EN}'...")
+                model_dir = self.cfg.get("offline_model_dir")
+                Path(model_dir).mkdir(parents=True, exist_ok=True)
+                tok_obj = MarianTokenizer.from_pretrained(
+                    OFFLINE_MODEL_ZH_EN, cache_dir=model_dir
+                )
+                self._offline_tok = tok_obj
+                model_obj = MarianMTModel.from_pretrained(
+                    OFFLINE_MODEL_ZH_EN, cache_dir=model_dir
+                )
+                self._offline_model = model_obj
+                
+                device = "cuda" if (
+                    self.cfg.get("use_gpu") and torch.cuda.is_available()
+                ) else "cpu"
+                
+                # Type safe access to model_obj
+                if model_obj is not None:
+                    self._offline_model = model_obj.to(device)
+                logger.info("Offline model loaded.")
+
+        chunks    = self._chunk_text(text, 400)
+        results: List[str]   = []
+        
+        # Type narrowing for device access
+        model_p = self._offline_model
+        if model_p is None:
+            raise RuntimeError("Offline model failed to load.")
+        
+        # device access requires model parameters to be initialized
+        if hasattr(model_p, "parameters"):
+            device = next(model_p.parameters()).device
+        else:
+            device = "cpu"
+
+        tok_p = self._offline_tok
+        if tok_p is None:
+            raise RuntimeError("Offline tokenizer failed to load.")
+
+        for chunk in chunks:
+            inputs = tok_p(
+                [chunk], return_tensors="pt", padding=True, truncation=True
+            ).to(device)
+            with torch.no_grad():
+                out = model_p.generate(**inputs)
+            if out is not None and len(out) > 0:
+                decoded = tok_p.decode(out[0], skip_special_tokens=True)
+                results.append(decoded)
+
+        return " ".join(results), "offline"
+
+    @staticmethod
+    def _chunk_text(text: str, max_len: int) -> List[str]:
+        """Split text into chunks at sentence boundaries."""
+        if len(text) <= max_len:
+            return [text]
+        chunks, current = [], ""
+        for char in text:
+            current += char
+            if len(current) >= max_len and char in "。！？.!?\n":
+                chunks.append(current.strip())
+                current = ""
+        if current.strip():
+            chunks.append(current.strip())
+        
+        if not chunks:
+            # Slicing with explicit 0 to help type checker
+            return [text[0:max_len]]
+        return chunks
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# HISTORY MANAGER
+# ════════════════════════════════════════════════════════════════════════════
+class HistoryManager:
+    """Persist and retrieve translation history."""
+
+    def __init__(self, config: Config):
+        self.cfg    = config
+        self._items: List[Dict] = []
+        HISTORY_FILE.parent.mkdir(parents=True, exist_ok=True)
+        self.load()
+
+    def load(self):
+        if HISTORY_FILE.exists():
+            try:
+                with open(HISTORY_FILE, "r", encoding="utf-8") as f:
+                    self._items = json.load(f)
+            except Exception:
+                self._items = []
+
+    def save(self):
+        try:
+            with open(HISTORY_FILE, "w", encoding="utf-8") as f:
+                json.dump(self._items, f, ensure_ascii=False, indent=2)
+        except Exception as e:
+            logger.error(f"History save error: {e}")
+
+    def add(
+        self,
+        source_text: str,
+        translated_text: str,
+        confidence: float,
+        script: str,
+        backend: str,
+    ):
+        entry = {
+            "timestamp"  : datetime.now().isoformat(),
+            "source"     : source_text,
+            "translation": translated_text,
+            "confidence" : float(int(float(confidence) * 1000)) / 1000.0,
+            "script"     : script,
+            "backend"    : backend,
+        }
+        self._items.insert(0, entry)
+        conf_raw = self.cfg.get("max_history", 500)
+        max_h: int = int(conf_raw) if conf_raw is not None else 500
+        while len(self._items) > max_h:
+            self._items.pop()
+        self.save()
+
+    def get_all(self) -> List[Dict]:
+        return list(self._items)
+
+    def export(self, path: str):
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(self._items, f, ensure_ascii=False, indent=2)
+
+    def clear(self):
+        self._items = []
+        self.save()
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# SCREEN OVERLAY (Selection UI)
+# ════════════════════════════════════════════════════════════════════════════
+class ScreenOverlay(tk.Toplevel):
+    """
+    Fullscreen transparent overlay for screen region selection.
+    Draws a rubber-band rectangle as the user drags the mouse.
+    """
+
+    def __init__(self, master: tk.Tk, callback):
+        super().__init__(master)
+        self.callback    = callback
+        self.start_x     = 0
+        self.start_y     = 0
+        self.end_x       = 0
+        self.end_y: int   = 0
+        self._rect_id: Optional[int] = None
+        self._cancelled: bool = False
+        self.canvas: Optional[tk.Canvas] = None
+
+        self._setup_window()
+        self._bind_events()
+
+    def _setup_window(self):
+        # On Windows, -fullscreen and overrideredirect can conflict.
+        # Use manual geometry for a more robust fullscreen overlay.
+        sw = self.winfo_screenwidth()
+        sh = self.winfo_screenheight()
+        
+        self.overrideredirect(True)
+        self.geometry(f"{sw}x{sh}+0+0")
+        self.attributes("-topmost", True)
+        self.attributes("-alpha", 0.25)
+        self.configure(bg="black", cursor="crosshair")
+
+        # Canvas covering full screen
+        canvas = tk.Canvas(
+            self,
+            width=sw,
+            height=sh,
+            bg="#000010",
+            highlightthickness=0,
+            cursor="crosshair",
+        )
+        self.canvas = canvas
+        if canvas is not None:
+            canvas.pack(fill=tk.BOTH, expand=True)
+
+            # Instruction label
+            canvas.create_text(
+                sw // 2,
+                sh // 2,
+                text="Click and drag to select Chinese text region  |  Esc to cancel",
+                fill="#ffffff",
+                font=("Consolas", 16, "bold"),
+                tags="instruction",
+            )
+
+    def _bind_events(self):
+        canvas = self.canvas
+        if canvas:
+            canvas.bind("<ButtonPress-1>",   self._on_press)
+            canvas.bind("<B1-Motion>",       self._on_drag)
+            canvas.bind("<ButtonRelease-1>", self._on_release)
+        self.bind("<Escape>", self._on_cancel)
+
+    def _on_press(self, event):
+        self.start_x = event.x_root
+        self.start_y = event.y_root
+        canvas = self.canvas
+        if canvas:
+            canvas.delete("instruction")
+
+    def _on_drag(self, event):
+        self.end_x = event.x_root
+        self.end_y = event.y_root
+        canvas = self.canvas
+        if canvas:
+            canvas.delete("selection")
+            # Draw selection box (canvas coords = screen coords here)
+            x1 = min(self.start_x, self.end_x)
+            y1 = min(self.start_y, self.end_y)
+            x2 = max(self.start_x, self.end_x)
+            y2 = max(self.start_y, self.end_y)
+            # Draw dim overlay around selection
+            canvas.create_rectangle(
+                x1, y1, x2, y2,
+                outline="#e94560",
+                fill="",
+                width=2,
+                tags="selection",
+            )
+            # Size label
+            w, h = x2 - x1, y2 - y1
+            canvas.create_text(
+                x1 + 5, y1 - 12,
+                text=f"{w} x {h}",
+                fill="#e94560",
+                font=("Consolas", 11),
+                anchor="w",
+                tags="selection",
+            )
+
+    def _on_release(self, event):
+        self.end_x = event.x_root
+        self.end_y = event.y_root
+        x1 = min(self.start_x, self.end_x)
+        y1 = min(self.start_y, self.end_y)
+        x2 = max(self.start_x, self.end_x)
+        y2 = max(self.start_y, self.end_y)
+
+        self.destroy()
+
+        if (x2 - x1) < 10 or (y2 - y1) < 10:
+            logger.warning("Selection too small, ignoring.")
+            return
+
+        self.callback(x1, y1, x2, y2)
+
+    def _on_cancel(self, event=None):
+        self._cancelled = True
+        self.destroy()
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# RESULT WINDOW
+# ════════════════════════════════════════════════════════════════════════════
+class ResultWindow(tk.Toplevel):
+    """Floating window showing OCR source text and translation."""
+
+    def __init__(self, master: tk.Tk, history: HistoryManager, config: Config):
+        super().__init__(master)
+        self.history   = history
+        self.cfg       = config
+        self._current: Dict[str, Any]  = {}
+        
+        # Declare attributes for linter
+        self._backend_lbl: tk.Label = tk.Label(self)
+        self._conf_lbl: tk.Label = tk.Label(self)
+        self._source_text: scrolledtext.ScrolledText = scrolledtext.ScrolledText(self)
+        self._trans_text: scrolledtext.ScrolledText = scrolledtext.ScrolledText(self)
+        self._status: tk.Label = tk.Label(self)
+        self._progress: ttk.Progressbar = ttk.Progressbar(self)
+        
+        self._setup_ui()
+
+    def _setup_ui(self):
+        self.title(f"{APP_NAME}  v{APP_VERSION}")
+        self.resizable(True, True)
+        self.attributes("-topmost", True)
+        self.minsize(480, 320)
+        self.configure(bg=COLORS["bg_dark"])
+        self.geometry("600x420+50+50")
+
+        # Title bar
+        title_bar = tk.Frame(self, bg=COLORS["bg_mid"], height=36)
+        title_bar.pack(fill=tk.X)
+        title_bar.pack_propagate(False)
+
+        tk.Label(
+            title_bar,
+            text=f"  {APP_NAME}",
+            bg=COLORS["bg_mid"],
+            fg=COLORS["accent"],
+            font=("Consolas", 11, "bold"),
+        ).pack(side=tk.LEFT, padx=8)
+
+        self._backend_lbl = tk.Label(
+            title_bar,
+            text="",
+            bg=COLORS["bg_mid"],
+            fg=COLORS["text_secondary"],
+            font=("Consolas", 9),
+        )
+        self._backend_lbl.pack(side=tk.LEFT, padx=4)
+
+        self._conf_lbl = tk.Label(
+            title_bar,
+            text="",
+            bg=COLORS["bg_mid"],
+            fg=COLORS["success"],
+            font=("Consolas", 9),
+        )
+        self._conf_lbl.pack(side=tk.LEFT, padx=4)
+
+        # Source text
+        src_frame = tk.LabelFrame(
+            self,
+            text="  Detected Chinese Text  ",
+            bg=COLORS["bg_dark"],
+            fg=COLORS["text_secondary"],
+            font=("Consolas", 9),
+            bd=1,
+            relief=tk.FLAT,
+            padx=6,
+            pady=4,
+        )
+        src_frame.pack(fill=tk.BOTH, expand=True, padx=10, pady=(8, 4))
+
+        self._source_text = scrolledtext.ScrolledText(
+            src_frame,
+            wrap=tk.WORD,
+            bg=COLORS["bg_mid"],
+            fg=COLORS["text_secondary"],
+            insertbackground=COLORS["text_primary"],
+            font=("Microsoft YaHei UI", self.cfg.get("result_font_size", 13)),
+            relief=tk.FLAT,
+            padx=8,
+            pady=6,
+            height=4,
+        )
+        self._source_text.pack(fill=tk.BOTH, expand=True)
+
+        # Translation text
+        trans_frame = tk.LabelFrame(
+            self,
+            text="  English Translation  ",
+            bg=COLORS["bg_dark"],
+            fg=COLORS["accent"],
+            font=("Consolas", 9, "bold"),
+            bd=1,
+            relief=tk.FLAT,
+            padx=6,
+            pady=4,
+        )
+        trans_frame.pack(fill=tk.BOTH, expand=True, padx=10, pady=(4, 8))
+
+        self._trans_text = scrolledtext.ScrolledText(
+            trans_frame,
+            wrap=tk.WORD,
+            bg=COLORS["bg_mid"],
+            fg=COLORS["text_primary"],
+            insertbackground=COLORS["text_primary"],
+            font=("Consolas", self.cfg.get("result_font_size", 13)),
+            relief=tk.FLAT,
+            padx=8,
+            pady=6,
+            height=4,
+        )
+        self._trans_text.pack(fill=tk.BOTH, expand=True)
+
+        # Button row
+        btn_frame = tk.Frame(self, bg=COLORS["bg_dark"])
+        btn_frame.pack(fill=tk.X, padx=10, pady=(0, 10))
+
+        btn_cfg: Dict[str, Any] = {
+            "bg": COLORS["bg_light"],
+            "fg": COLORS["text_primary"],
+            "font": ("Consolas", 9, "bold"),
+            "relief": tk.FLAT,
+            "padx": 12,
+            "pady": 5,
+            "cursor": "hand2",
+            "activebackground": COLORS["accent"],
+            "activeforeground": "#ffffff",
+        }
+        tk.Button(btn_frame, text="Copy Translation",
+                  command=self._copy_translation, **btn_cfg).pack(side=tk.LEFT, padx=2)
+        tk.Button(btn_frame, text="Copy Source",
+                  command=self._copy_source, **btn_cfg).pack(side=tk.LEFT, padx=2)
+        tk.Button(btn_frame, text="Copy Both",
+                  command=self._copy_both, **btn_cfg).pack(side=tk.LEFT, padx=2)
+
+        self._status = tk.Label(
+            btn_frame,
+            text="",
+            bg=COLORS["bg_dark"],
+            fg=COLORS["success"],
+            font=("Consolas", 9),
+        )
+        self._status.pack(side=tk.RIGHT, padx=6)
+
+        # Progress bar (shown during processing)
+        self._progress = ttk.Progressbar(
+            self, mode="indeterminate", length=200
+        )
+
+        self._style_progressbar()
+
+    def _style_progressbar(self):
+        style = ttk.Style(self)
+        style.theme_use("default")
+        style.configure(
+            "TProgressbar",
+            troughcolor=COLORS["bg_mid"],
+            background=COLORS["accent"],
+            thickness=3,
+        )
+
+    def show_processing(self, stage: str = "Processing..."):
+        self.deiconify()
+        self.lift()
+        self._source_text.configure(state=tk.NORMAL)
+        self._source_text.delete("1.0", tk.END)
+        self._source_text.insert(tk.END, stage)
+        self._source_text.configure(state=tk.DISABLED)
+        self._trans_text.configure(state=tk.NORMAL)
+        self._trans_text.delete("1.0", tk.END)
+        self._trans_text.configure(state=tk.DISABLED)
+        self._progress.pack(fill=tk.X, padx=10, pady=(0, 4))
+        self._progress.start(12)
+        self.update_idletasks()
+
+    def update_result(
+        self,
+        source: str,
+        translation: str,
+        confidence: float,
+        script: str,
+        backend: str,
+    ):
+        self._progress.stop()
+        self._progress.pack_forget()
+
+        self._current = {
+            "source"     : source,
+            "translation": translation,
+            "confidence" : confidence,
+            "script"     : script,
+            "backend"    : backend,
+        }
+
+        self._source_text.configure(state=tk.NORMAL)
+        self._source_text.delete("1.0", tk.END)
+        self._source_text.insert(tk.END, source)
+        self._source_text.configure(state=tk.DISABLED)
+
+        self._trans_text.configure(state=tk.NORMAL)
+        self._trans_text.delete("1.0", tk.END)
+        self._trans_text.insert(tk.END, translation)
+        self._trans_text.configure(state=tk.DISABLED)
+
+        conf_pct = f"{confidence * 100:.1f}%"
+        self._conf_lbl.config(
+            text=f"OCR: {conf_pct}  [{script}]"
+            if self.cfg.get("show_confidence") else ""
+        )
+        self._backend_lbl.config(text=f"via {backend}")
+
+        if self.cfg.get("auto_copy") and CLIPBOARD_AVAILABLE:
+            pyperclip.copy(translation)
+            self._set_status("Auto-copied to clipboard")
+
+    def show_error(self, message: str):
+        self._progress.stop()
+        self._progress.pack_forget()
+        self._trans_text.configure(state=tk.NORMAL)
+        self._trans_text.delete("1.0", tk.END)
+        self._trans_text.insert(tk.END, f"[ERROR] {message}")
+        self._trans_text.configure(state=tk.DISABLED)
+
+    def _copy_translation(self):
+        if self._current.get("translation") and CLIPBOARD_AVAILABLE:
+            pyperclip.copy(self._current["translation"])
+            self._set_status("Translation copied")
+
+    def _copy_source(self):
+        if self._current.get("source") and CLIPBOARD_AVAILABLE:
+            pyperclip.copy(self._current["source"])
+            self._set_status("Source text copied")
+
+    def _copy_both(self):
+        if self._current and CLIPBOARD_AVAILABLE:
+            combined = (
+                f"[Chinese]\n{self._current.get('source','')}\n\n"
+                f"[English]\n{self._current.get('translation','')}"
+            )
+            pyperclip.copy(combined)
+            self._set_status("Both copied")
+
+    def _set_status(self, msg: str, duration: int = 2500):
+        self._status.config(text=msg)
+        def _clear(*args):
+            self._status.config(text="")
+        self.after(duration, _clear)
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# HISTORY WINDOW
+# ════════════════════════════════════════════════════════════════════════════
+class HistoryWindow(tk.Toplevel):
+    """Browse, search, and export translation history."""
+
+    def __init__(self, master: tk.Tk, history: HistoryManager):
+        super().__init__(master)
+        self.history: HistoryManager = history
+        self._tree: Optional[ttk.Treeview] = None
+        self._search_var: Optional[tk.StringVar] = None
+        self.title(f"{APP_NAME} - History")
+        self.geometry("800x560+100+100")
+        self.configure(bg=COLORS["bg_dark"])
+        self.attributes("-topmost", True)
+        self._setup_ui()
+        self._load_items()
+
+    def _setup_ui(self):
+        top = tk.Frame(self, bg=COLORS["bg_dark"])
+        top.pack(fill=tk.X, padx=10, pady=8)
+
+        tk.Label(
+            top, text="Search:", bg=COLORS["bg_dark"],
+            fg=COLORS["text_secondary"], font=("Consolas", 10)
+        ).pack(side=tk.LEFT)
+
+        self._search_var = tk.StringVar()
+        search_var = self._search_var
+        if search_var is not None:
+            search_var.trace("w", lambda *_: self._filter())
+        if search_var is not None:
+            tk.Entry(
+                top,
+                textvariable=search_var,
+                bg=COLORS["bg_mid"],
+                fg=COLORS["text_primary"],
+                insertbackground=COLORS["text_primary"],
+                font=("Consolas", 10),
+                relief=tk.FLAT,
+                width=30,
+            ).pack(side=tk.LEFT, padx=8)
+
+        btn_cfg: Dict[str, Any] = {
+            "bg": COLORS["bg_light"],
+            "fg": COLORS["text_primary"],
+            "font": ("Consolas", 9),
+            "relief": tk.FLAT,
+            "padx": 8,
+            "pady": 4,
+            "cursor": "hand2",
+        }
+        tk.Button(top, text="Export JSON",
+                  command=self._export, **btn_cfg).pack(side=tk.RIGHT, padx=2)
+        tk.Button(top, text="Clear All",
+                  command=self._clear, **btn_cfg).pack(side=tk.RIGHT, padx=2)
+
+        # Treeview
+        cols = ("timestamp", "script", "backend", "conf", "source", "translation")
+        tree = ttk.Treeview(
+            self, columns=cols, show="headings", selectmode="browse"
+        )
+        self._tree = tree
+        hdrs = {
+            "timestamp"  : ("Timestamp", 140),
+            "script"     : ("Script",     80),
+            "backend"    : ("Backend",    70),
+            "conf"       : ("OCR %",      60),
+            "source"     : ("Source",    200),
+            "translation": ("Translation",200),
+        }
+        for col, (hdr, width) in hdrs.items():
+            tree.heading(col, text=hdr)
+            tree.column(col, width=width, minwidth=40)
+
+        vsb = ttk.Scrollbar(self, orient=tk.VERTICAL,
+                             command=tree.yview)
+        tree.configure(yscrollcommand=vsb.set)
+        vsb.pack(side=tk.RIGHT, fill=tk.Y)
+        tree.pack(fill=tk.BOTH, expand=True, padx=10, pady=(0, 10))
+
+        # Capture the tree and style it
+        style = ttk.Style(self)
+        style.theme_use("default")
+        style.configure("Treeview",
+            background=COLORS["bg_mid"],
+            foreground=COLORS["text_primary"],
+            fieldbackground=COLORS["bg_mid"],
+            rowheight=24,
+            font=("Consolas", 9),
+        )
+        style.configure("Treeview.Heading",
+            background=COLORS["bg_light"],
+            foreground=COLORS["text_primary"],
+            font=("Consolas", 9, "bold"),
+        )
+
+        tree.bind("<Double-1>", self._on_double_click)
+
+    def _load_items(self, filter_text: str = ""):
+        tree = self._tree
+        if tree is None:
+            return
+        for row in tree.get_children():
+            tree.delete(row)
+        for item in self.history.get_all():
+            src   = str(item.get("source", ""))
+            trans = str(item.get("translation", ""))
+            if filter_text and filter_text.lower() not in (src + trans).lower():
+                continue
+            timestamp = str(item.get("timestamp", ""))
+            if len(timestamp) > 19:
+                timestamp = timestamp[0:19]
+            
+            src_disp = str(src)
+            if len(src_disp) > 60:
+                src_disp = src_disp[0:60]
+                
+            trans_disp = str(trans)
+            if len(trans_disp) > 80:
+                trans_disp = trans_disp[0:80]
+
+            tree.insert(
+                "", tk.END,
+                values=(
+                    timestamp,
+                    item.get("script", ""),
+                    item.get("backend", ""),
+                    f"{float(item.get('confidence', 0)) * 100:.0f}%",
+                    src_disp,
+                    trans_disp,
+                ),
+            )
+
+    def _filter(self):
+        var = self._search_var
+        if var:
+            self._load_items(var.get())
+
+    def _export(self):
+        path = filedialog.asksaveasfilename(
+            defaultextension=".json",
+            filetypes=[("JSON", "*.json"), ("All", "*.*")],
+        )
+        if path:
+            self.history.export(path)
+            messagebox.showinfo("Exported", f"History saved to:\n{path}")
+
+    def _clear(self):
+        if messagebox.askyesno("Clear History",
+                               "Delete all translation history?"):
+            self.history.clear()
+            self._load_items()
+
+    def _on_double_click(self, event):
+        tree = self._tree
+        if tree is None:
+            return
+        sel = tree.selection()
+        if not sel:
+            return
+        item_id = sel[0]
+        item_vals = tree.item(item_id, "values")
+        if not item_vals or not isinstance(item_vals, (list, tuple)):
+            return
+        if len(item_vals) > 5 and CLIPBOARD_AVAILABLE:
+            pyperclip.copy(str(item_vals[5]))  # copy translation
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# SETTINGS WINDOW
+# ════════════════════════════════════════════════════════════════════════════
+class SettingsWindow(tk.Toplevel):
+    def __init__(self, master: tk.Tk, config: Config):
+        super().__init__(master)
+        self.cfg: Config = config
+        self._vars: Dict[str, Any] = {}
+        self.title("Settings")
+        self.geometry("460x480+150+150")
+        self.configure(bg=COLORS["bg_dark"])
+        self.attributes("-topmost", True)
+        self.resizable(False, False)
+        self._build()
+
+    def _build(self):
+        pad = {"padx": 16, "pady": 6}
+
+        def row(label, widget_factory, key, **kw):
+            f = tk.Frame(self, bg=COLORS["bg_dark"])
+            # Use explicit args to satisfy pack_configure types
+            f.pack(fill=tk.X, padx=pad["padx"], pady=pad["pady"])
+            tk.Label(f, text=label, bg=COLORS["bg_dark"],
+                     fg=COLORS["text_secondary"],
+                     font=("Consolas", 10), width=26, anchor="w").pack(side=tk.LEFT)
+            var, w = widget_factory(f, key, **kw)
+            w.pack(side=tk.LEFT, fill=tk.X, expand=True)
+            return var
+
+        def entry_field(parent, key):
+            var = tk.StringVar(value=str(self.cfg.get(key, "")))
+            e = tk.Entry(parent, textvariable=var, bg=COLORS["bg_mid"],
+                         fg=COLORS["text_primary"],
+                         insertbackground=COLORS["text_primary"],
+                         font=("Consolas", 10), relief=tk.FLAT)
+            return var, e
+
+        def combo_field(parent, key, values):
+            var = tk.StringVar(value=str(self.cfg.get(key, "")))
+            c = ttk.Combobox(parent, textvariable=var, values=values,
+                             state="readonly", font=("Consolas", 10))
+            return var, c
+
+        def check_field(parent, key):
+            var = tk.BooleanVar(value=bool(self.cfg.get(key, False)))
+            c = tk.Checkbutton(parent, variable=var, bg=COLORS["bg_dark"],
+                               activebackground=COLORS["bg_dark"],
+                               selectcolor=COLORS["bg_mid"])
+            return var, c
+
+        self._vars = {}
+
+        self._vars["hotkey"] = row("Global Hotkey", entry_field, "hotkey")
+        self._vars["lang"]   = row("OCR Language", combo_field, "lang",
+                                   values=["auto", "simplified", "traditional"])
+        self._vars["backend"]= row("Translation Backend", combo_field, "backend",
+                                   values=["google", "microsoft", "offline"])
+        self._vars["upscale_factor"] = row("Upscale Factor (1-4)", entry_field, "upscale_factor")
+        self._vars["confidence_threshold"] = row("OCR Confidence (0-1)", entry_field, "confidence_threshold")
+        self._vars["use_gpu"]   = row("Use GPU (CUDA)", check_field, "use_gpu")
+        self._vars["auto_copy"] = row("Auto Copy Translation", check_field, "auto_copy")
+        self._vars["show_confidence"] = row("Show Confidence Score", check_field, "show_confidence")
+        self._vars["preprocess"] = row("Enable Image Preprocessing", check_field, "preprocess")
+        self._vars["microsoft_api_key"] = row("Microsoft API Key", entry_field, "microsoft_api_key")
+        self._vars["microsoft_region"]  = row("Microsoft Region", entry_field, "microsoft_region")
+
+        tk.Button(
+            self, text="Save Settings",
+            bg=COLORS["accent"], fg="#ffffff",
+            font=("Consolas", 10, "bold"),
+            relief=tk.FLAT, padx=14, pady=6,
+            cursor="hand2",
+            command=self._save,
+        ).pack(pady=14)
+
+    def _save(self):
+        for key, var in self._vars.items():
+            val = var.get()
+            if isinstance(val, bool):
+                self.cfg.set(key, val)
+            else:
+                try:
+                    fval = float(val)
+                    self.cfg.set(key, fval if "." in str(val) else int(fval))
+                except (ValueError, TypeError):
+                    self.cfg.set(key, val)
+        messagebox.showinfo("Saved", "Settings saved. Restart hotkeys to apply.")
+        self.destroy()
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# MAIN APPLICATION
+# ════════════════════════════════════════════════════════════════════════════
+class ChineseScreenTranslator:
+    """
+    Main application controller.
+    Coordinates OCR, translation, UI, hotkeys, and history.
+    """
+
+    def __init__(self, config: Config):
+        self.cfg         = config
+        self.ocr         = OCREngine(config)
+        self.translator  = TranslationEngine(config)
+        self.history     = HistoryManager(config)
+        self._task_queue = Queue()
+        self._result_win : Optional[ResultWindow]  = None
+        self._history_win: Optional[HistoryWindow] = None
+        self._settings_win: Optional[SettingsWindow] = None
+        self._processing = False
+
+        # Build root Tk window (hidden - acts only as parent)
+        self.root = tk.Tk()
+        self.root.withdraw()
+        self.root.title(APP_NAME)
+
+        # Build persistent result window
+        res_window = ResultWindow(self.root, self.history, self.cfg)
+        self._result_win = res_window
+        if res_window is not None:
+            res_window.protocol("WM_DELETE_WINDOW", res_window.withdraw)
+
+        # Status bar (small floating hint)
+        self._status_win = self._build_status_bar()
+
+        # Start worker thread
+        self._worker_thread = threading.Thread(
+            target=self._worker_loop, daemon=True
+        )
+        self._worker_thread.start()
+
+        # Register hotkeys
+        self._register_hotkeys()
+
+        # Preload OCR model in background
+        self.ocr.preload()
+
+        logger.info(f"{APP_NAME} v{APP_VERSION} started by {APP_AUTHOR}")
+        logger.info(f"Hotkey: {self.cfg.get('hotkey')}")
+
+    def _deiconify_result(self, event=None):
+        win = self._result_win
+        if win is not None:
+            win.deiconify()
+            win.lift()
+
+    def _show_menu(self, event, menu: tk.Menu):
+        menu.tk_popup(event.x_root, event.y_root)
+
+    def _build_status_bar(self) -> tk.Toplevel:
+        win = tk.Toplevel(self.root)
+        win.overrideredirect(True)
+        win.attributes("-topmost", True)
+        win.attributes("-alpha", 0.88)
+        win.configure(bg=COLORS["bg_mid"])
+        sw = win.winfo_screenwidth()
+
+        hotkey_raw = self.cfg.get("hotkey", "alt+s")
+        hotkey = str(hotkey_raw).upper() if hotkey_raw else "ALT+S"
+
+        lbl = tk.Label(
+            win,
+            text=f"  {APP_NAME}  |  {hotkey} = Capture  |  Right-click for menu  ",
+            bg=COLORS["bg_mid"],
+            fg=COLORS["text_secondary"],
+            font=("Consolas", 9),
+            pady=4,
+        )
+        lbl.pack()
+        win.geometry(f"+{sw - 620}+10")
+
+        # Right-click context menu
+        menu = tk.Menu(win, tearoff=0, bg=COLORS["bg_mid"],
+                       fg=COLORS["text_primary"], font=("Consolas", 9))
+        menu.add_command(label="Capture Region", command=self.start_capture)
+        menu.add_command(label="Show Last Result",
+                         command=self._deiconify_result)
+        menu.add_command(label="Translation History",
+                         command=self.show_history)
+        menu.add_command(label="Settings", command=self.show_settings)
+        menu.add_separator()
+        menu.add_command(label="Quit", command=self.quit)
+
+        lbl.bind("<Button-3>", lambda e: self._show_menu(e, menu))
+        return win
+
+    def _register_hotkeys(self):
+        if not KEYBOARD_AVAILABLE:
+            logger.warning("keyboard library unavailable. Use the status bar to trigger capture.")
+            return
+        hotkey = self.cfg.get("hotkey", "alt+s")
+        try:
+            kb.add_hotkey(hotkey, self._hotkey_capture, suppress=False)
+            kb.add_hotkey("ctrl+shift+h", self.show_history, suppress=False)
+            kb.add_hotkey("ctrl+shift+q", self.quit, suppress=False)
+            kb.add_hotkey("ctrl+shift+c", self._hotkey_copy, suppress=True)
+            logger.info(f"Hotkeys registered. Capture: {hotkey}")
+        except Exception as e:
+            logger.error(f"Hotkey registration failed: {e}")
+            logger.info("Tip: On Linux, run as root or use the status bar right-click menu.")
+
+    def _hotkey_capture(self, *args):
+        self.root.after(0, lambda: self.start_capture())
+
+    def _hotkey_copy(self):
+        win = self._result_win
+        if win and hasattr(win, "_current"):
+            current = getattr(win, "_current")
+            if current and isinstance(current, dict):
+                trans = current.get("translation", "")
+                if trans and CLIPBOARD_AVAILABLE:
+                    pyperclip.copy(trans)
+                    logger.info("Last translation copied to clipboard.")
+
+    def start_capture(self):
+        if self._processing:
+            logger.info("Already processing, ignoring duplicate capture request.")
+            return
+        overlay = ScreenOverlay(self.root, self._on_region_selected)
+        overlay.focus_force()
+
+    def _on_region_selected(self, x1: int, y1: int, x2: int, y2: int):
+        logger.info(f"Region selected: ({x1},{y1}) -> ({x2},{y2})")
+        self._task_queue.put(("capture", x1, y1, x2, y2))
+        res_win = self._result_win
+        if res_win is not None:
+            self.root.after(0, lambda *_, w=res_win: w.show_processing("Running OCR..."))
+            res_win.deiconify()
+
+    def _worker_loop(self):
+        """Background thread: OCR + translate."""
+        while True:
+            try:
+                task = self._task_queue.get(timeout=0.5)
+            except Empty:
+                continue
+
+            if task[0] == "capture":
+                _, x1, y1, x2, y2 = task
+                self._processing = True
+                try:
+                    self._process_region(x1, y1, x2, y2)
+                except Exception as e:
+                    logger.error(f"Processing error: {e}", exc_info=True)
+                    win_err = self._result_win
+                    if win_err is not None:
+                        self.root.after(
+                            0, lambda *_, w=win_err, msg=str(e): w.show_error(msg)
+                        )
+                finally:
+                    self._processing = False
+                    self._task_queue.task_done()
+
+    def _process_region(self, x1: int, y1: int, x2: int, y2: int):
+        win = self._result_win
+        if win is None:
+            return
+
+        # Step 1: Screenshot
+        self.root.after(0, lambda w=win: w.show_processing(
+            "Capturing screen region..."
+        ))
+        img = self._capture_screenshot(x1, y1, x2, y2)
+        if img is None:
+            raise RuntimeError("Screenshot capture failed.")
+
+        # Step 2: OCR
+        self.root.after(0, lambda w=win: w.show_processing(
+            "Running Chinese OCR (EasyOCR)..."
+        ))
+        source_text, confidence, script = self.ocr.extract_text(img)
+
+        if not source_text.strip():
+            self.root.after(0, lambda w=win: w.update_result(
+                "[No Chinese text detected in selection]",
+                "",
+                0.0,
+                script,
+                "none",
+            ))
+            return
+
+        # Step 3: Translate
+        self.root.after(0, lambda w=win, b=self.cfg.get('backend'): w.show_processing(
+            f"Translating ({b})..."
+        ))
+        translated, backend = self.translator.translate(source_text, source_lang=script)
+
+        # Step 4: Save history
+        self.history.add(source_text, translated, confidence, script, backend)
+
+        # Step 5: Update UI
+        self.root.after(0, lambda *_, w=win, st=source_text, t=translated, c=confidence, s=script, b=backend: w.update_result(
+            st, t, c, s, b
+        ))
+        logger.info(
+            f"Done. OCR:{confidence:.2f} Script:{script} Backend:{backend}"
+        )
+
+    def _capture_screenshot(self, x1: int, y1: int, x2: int, y2: int) -> Optional[Image.Image]:
+        """Capture a screen region using mss (preferred) or PIL fallback."""
+        try:
+            if MSS_AVAILABLE:
+                with mss.mss() as sct:
+                    monitor = {"top": y1, "left": x1, "width": x2-x1, "height": y2-y1}
+                    raw = sct.grab(monitor)
+                    img = Image.frombytes("RGB", raw.size, raw.bgra, "raw", "BGRX")
+                    return img
+        except Exception as e:
+            logger.warning(f"mss capture failed ({e}), trying PIL fallback...")
+
+        try:
+            img = ImageGrab.grab(bbox=(x1, y1, x2, y2))
+            return img
+        except Exception as e:
+            logger.error(f"PIL screenshot failed: {e}")
+            return None
+
+    def show_history(self):
+        win = self._history_win
+        if win and win.winfo_exists():
+            win.lift()
+        else:
+            self._history_win = HistoryWindow(self.root, self.history)
+
+    def show_settings(self):
+        win = self._settings_win
+        if win and win.winfo_exists():
+            win.lift()
+        else:
+            self._settings_win = SettingsWindow(self.root, self.cfg)
+
+    def quit(self):
+        logger.info("Shutting down.")
+        if KEYBOARD_AVAILABLE:
+            try:
+                kb.unhook_all()
+            except Exception:
+                pass
+        self.cfg.save()
+        self.history.save()
+        self.root.quit()
+        self.root.destroy()
+
+    def run(self):
+        try:
+            self.root.mainloop()
+        except KeyboardInterrupt:
+            self.quit()
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# CLI ENTRY POINT
+# ════════════════════════════════════════════════════════════════════════════
+def build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="translator",
+        description=(
+            f"{APP_NAME} v{APP_VERSION} by {APP_AUTHOR}\n"
+            "Chinese screen region OCR + translation tool."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=textwrap.dedent("""
+        Examples:
+          python translator.py
+          python translator.py --hotkey "ctrl+shift+t"
+          python translator.py --lang traditional --backend google
+          python translator.py --offline --gpu
+          python translator.py --upscale 3 --confidence 0.4 --verbose
+        """),
+    )
+    parser.add_argument("--version", action="version",
+                        version=f"{APP_NAME} {APP_VERSION}")
+    parser.add_argument("--hotkey", type=str,
+                        help="Global hotkey to trigger capture (default: alt+s)")
+    parser.add_argument("--lang", choices=["auto", "simplified", "traditional"],
+                        help="Chinese OCR language mode")
+    parser.add_argument("--backend", choices=["google", "microsoft", "offline"],
+                        help="Translation backend")
+    parser.add_argument("--offline", action="store_true",
+                        help="Use offline Helsinki-NLP MarianMT model")
+    parser.add_argument("--gpu", action="store_true",
+                        help="Enable GPU (CUDA) for OCR and offline translation")
+    parser.add_argument("--upscale", type=int, choices=range(1, 5),
+                        metavar="1-4",
+                        help="Image upscale factor for better OCR on small text")
+    parser.add_argument("--confidence", type=float,
+                        help="Minimum OCR confidence threshold (0.0-1.0)")
+    parser.add_argument("--no-preprocess", action="store_true",
+                        help="Disable image preprocessing pipeline")
+    parser.add_argument("--export-history", type=str, metavar="FILE",
+                        help="Export history to JSON file on exit")
+    parser.add_argument("--verbose", action="store_true",
+                        help="Enable DEBUG-level logging")
+    return parser
+
+
+def main():
+    parser  = build_arg_parser()
+    args    = parser.parse_args()
+    logger_ = setup_logging(verbose=getattr(args, "verbose", False))
+
+    # Dependency check
+    missing = []
+    if not EASYOCR_AVAILABLE:
+        missing.append("easyocr/torch      ->  pip install easyocr torch torchvision")
+    if not DEEP_TRANSLATOR_AVAILABLE:
+        missing.append("deep-translator   ->  pip install deep-translator")
+    if not OFFLINE_TRANSLATION_AVAILABLE:
+        # Only warn if backend is explicitly set to offline or if both fail
+        if args.backend == "offline":
+             missing.append("transformers/torch ->  pip install transformers torch")
+
+    if missing:
+        print("\n" + "!" * 40)
+        print("[CRITICAL] Some dependencies are missing:")
+        for m in missing:
+            print(f"  {m}")
+        print("!" * 40 + "\n")
+        # Do not exit, try to run anyway but with warnings
+
+    cfg = Config()
+    cfg.apply_args(args)
+
+    app = ChineseScreenTranslator(cfg)
+
+    if getattr(args, "export_history", None):
+        import atexit
+        def _on_exit(*_args, **_kwargs):
+            if app is not None:
+                app.history.export(str(args.export_history))
+        atexit.register(_on_exit)
+
+    print(f"\n{APP_NAME} v{APP_VERSION}  |  Author: {APP_AUTHOR}")
+    print(f"Hotkey : {cfg.get('hotkey').upper()}")
+    print(f"Lang   : {cfg.get('lang')}")
+    print(f"Backend: {cfg.get('backend')}")
+    print(f"Config : {CONFIG_FILE}")
+    print(f"Log    : {LOG_FILE}")
+    print("Press the hotkey or right-click the status bar to start.\n")
+
+    app.run()
+
+
+if __name__ == "__main__":
+    main()