English | 繁體中文

TOST (Translategemma) - Offline Screen Translator

TOST (TranslateGemma Online-free Screen Translator) is a zero-latency, privacy-first offline desktop screen translation tool. Snip any bounding box on your desktop display and receive instant, high-fidelity Traditional Chinese (繁體中文) translations via native OS notifications and clipboard auto-sync. Completely self-hosted and offline—no telemetry, no cloud API fees, and zero data leakage.

---

Table of Contents

• Key Features
• Technical Architecture
• Repository Structure
• Prerequisites
• Installation & Quick Start
  • Option A: Automated Scripts (Windows / Linux)
  • Option B: Manual Developer Setup (Source Code)
• Configuration & Settings
• Usage Guide
• Building Standalone Executables
• Trademarks & License Notices
• Acknowledgements

---

Key Features

• 🔒 100% Air-Gapped Privacy: Both Optical Character Recognition (OCR) and LLM inference execute entirely on your local machine. No images or text snippets ever leave your system.
• ⚡ Lightweight & High-Throughput OCR: Powered by RapidOCR (ONNX Runtime engine) for near-instant text localization and extraction across complex screen backgrounds.
• 🤖 Context-Aware Translation: Employs fine-tuned/quantized Google Gemma (via Ollama) yielding fluent, idiomatic Traditional Chinese translations without hallucinations or conversational filler.
• 🖥️ Native Cross-Platform Notifications: Integrated with Windows 10/11 Action Center toasts (win11toast) and Linux desktop daemon notifications (notify-send).
• 📋 Seamless Clipboard Synchronization: Every translation result is automatically copied to the system clipboard for immediate pasting (Ctrl + V).
• 🎛️ Unobtrusive System Tray Daemon: Runs quietly in the background via pystray with a persistent screen overlay engine for rapid, repeated snipping without window flickering.
• ⌨️ Global Keyboard Shortcut: Default trigger Shift + Alt + Z allows instant access from any active window or game.

---

Technical Architecture

flowchart TD
    User([User Shortcut: Shift + Alt + Z]) --> Snipper[ScreenSnipper Overlay\nTkinter Canvas]
    Snipper -->|Selected Bounding Box| Cropper[Crop Image Matrix\nPillow]
    Cropper --> OCR[RapidOCR Engine\nONNX Runtime]
    OCR -->|Extracted Plaintext| PromptEngine[Prompt Sanitizer\nZero-Shot System Prompt]
    PromptEngine --> OllamaClient[Local Ollama API\n127.0.0.1:11434]
    OllamaClient --> GemmaModel[Google Gemma 4B GGUF\nQuantized Q2_K/Q4_K]
    GemmaModel -->|Traditional Chinese Text| ResponseHandler[Response Dispatcher]
    ResponseHandler --> Clipboard[Clipboard Synchronizer\npyperclip]
    ResponseHandler --> Notifier[OS Notification Engine\nwin11toast / notify-send]
    Clipboard --> Output([User Receives Toast & Paste Ready])
    Notifier --> Output

Loading

---

Repository Structure

TOST/
├── models/
│   ├── Modelfile             # Ollama model definition & system prompt template
│   └── (translategemma*.gguf)# Local quantized model binary (user downloaded)
├── src/
│   ├── app.py                # Main application entrypoint & system tray controller
│   ├── ocr_handler.py        # RapidOCR ONNX wrapper & text formatting logic
│   ├── snipper.py            # High-performance Tkinter cross-monitor snipping overlay
│   └── utils.py              # OS abstraction layer (notifications, DPI geometry)
├── .gitignore                # Git exclusions (virtualenvs, models, build caches)
├── AGENTS.md                 # Agentic workflow instructions
├── build.bat                 # PyInstaller one-file compilation script for Windows
├── build.sh                  # PyInstaller compilation script for Linux
├── LICENSE                   # Open-source MIT License
├── NOTICE                    # Mandatory Google Gemma terms notice
├── README.md                 # English documentation
├── README_zh.md              # Traditional Chinese documentation
├── requirements.txt          # Python package dependencies
├── run.bat                   # Quick launcher script for Windows
├── run.sh                    # Quick launcher script for Linux
├── setup.bat                 # Automated Ollama model registration script for Windows
├── setup.sh                  # Automated Ollama model registration script for Linux
└── THIRD_PARTY_NOTICES.md    # Third-party dependency licenses and attributions

---

Prerequisites

1. Python: Version 3.10 or higher installed and added to PATH.
2. Ollama: Download and install the local LLM runtime from ollama.com.
3. Model Weights: Download a quantized Gemma GGUF model:
   • Recommended: mradermacher/translategemma-4b-it-GGUF (e.g., translategemma-4b-it.Q2_K.gguf or Q4_K_M.gguf).
   • Place the .gguf file inside the models/ directory.

---

Installation & Quick Start

Option A: Automated Scripts (Windows / Linux)

Windows

:: 1. Place the downloaded GGUF file into the models/ folder
:: 2. Register the model with Ollama
setup.bat

:: 3. Launch the application
run.bat

Linux

# 1. Grant execution permissions
chmod +x *.sh

# 2. Register the model with Ollama
./setup.sh

# 3. Launch the application
./run.sh

---

Option B: Manual Developer Setup (Source Code)

# 1. Clone the repository
git clone https://github.com/Max97k/TOST.git
cd TOST

# 2. Create and activate a Python virtual environment
# Windows:
python -m venv .venv
.venv\Scripts\activate

# Linux:
python3 -m venv .venv
source .venv/bin/activate

# 3. Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

# 4. Import the custom Gemma model into Ollama
cd models
# Ensure Modelfile points to your downloaded GGUF filename
ollama create translategemma -f Modelfile
cd ..

# 5. Launch the application
# Windows:
python src/app.py

# Linux:
python3 src/app.py

---

Configuration & Settings

Parameter	Default Value	Location / Source	Description
MODEL_NAME	translategemma	src/app.py	Target Ollama model identifier to query.
Global Hotkey	Shift + Alt + Z	src/app.py	Keyboard combination to invoke the screen selection overlay.
Ollama Host	http://127.0.0.1:11434	Environment / Default	Host address where local Ollama daemon is listening (OLLAMA_HOST).
System Prompt	Strict translation instructions	models/Modelfile	Guarantees zero explanatory chit-chat, returning purely Traditional Chinese.
Notification Timeout	5 seconds	src/utils.py	Display duration for desktop toast notifications.

---

Usage Guide

1. Background Tray: Upon launch, TOST minimizes into your system tray (Taskbar notification area on Windows or the top/bottom panel on Linux).
2. Trigger Snipping: Press Shift + Alt + Z anywhere on your desktop. A translucent crosshair overlay appears across your monitor(s).
3. Select Region: Left-click and drag a rectangle around any English text (in documents, browser tabs, video subtitles, games, or IDE windows).
4. Instant Translation:
   • A desktop toast notification presents the translated Traditional Chinese text.
   • The translated string is automatically pushed to your clipboard.
5. Paste: Press Ctrl + V in your target editor or chat window.
6. Exit: Right-click the system tray icon and select Exit.

Linux Note: If global hotkeys fail to register due to Wayland or X11 security restrictions, you can trigger screen capture directly by right-clicking the system tray icon and clicking Snip.

---

Building Standalone Executables

To package the application into a standalone executable binary using PyInstaller:

• Windows: Run build.bat (Generates dist/Translategemma.exe).
• Linux: Run ./build.sh (Generates dist/Translategemma/Translategemma).

---

Trademarks & License Notices

Source Code License

This project is open-source software licensed under the MIT License.

Model Terms & Trademarks

• Google® and Gemma™ are trademarks of Google LLC.
• The Translategemma model weights and derived weights are subject to the Gemma Terms of Use. Use of the Gemma weights acknowledges and agrees to these terms.
• Ollama™ is a trademark of Ollama Inc.
• Windows® is a registered trademark of Microsoft Corporation in the United States and other countries.
• Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.
• For all third-party libraries and licenses (RapidOCR, Pillow, win11toast, pystray), refer to THIRD_PARTY_NOTICES.md.

---

Acknowledgements

• Google - Gemma: For open-weight model architectures.
• mradermacher: For quantized GGUF weights optimized for local CPU/GPU inference.
• RapidAI / RapidOCR: For the ultra-fast ONNX-based OCR framework.