interpreter-v2 0.1.0

Offline screen translator for Japanese retro games

Interpreter

Offline screen translator for Japanese retro games. Captures text from any window, performs OCR, translates to English, and displays subtitles in a floating overlay.

Features

• Fully offline - No cloud APIs, no internet required after setup
• Free - No API costs or subscriptions
• Private - Text never leaves your machine
• Optimized for retro games - Uses MeikiOCR, trained specifically on Japanese game text
• Two overlay modes - Banner (subtitle bar) or inplace (text over game)
• Translation caching - Fuzzy matching avoids re-translating similar text

Requirements

• Python 3.11+
• macOS (Windows/Linux support planned)

Installation

1. Install uv (modern Python package manager):

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Clone and install:

   git clone https://github.com/bquenin/interpreter.git
   cd interpreter
   uv sync
   

3. Models are downloaded automatically on first run (~1.5GB total).

Usage

# List available windows
uv run interpreter --list-windows

# Run with default config
uv run interpreter

# Run with specific window
uv run interpreter --window "Tales"

# Start in inplace mode (text over game)
uv run interpreter --overlay-mode inplace

# Debug mode (show OCR confidence scores)
uv run interpreter --debug

Controls

Key	Action
m	Cycle overlay mode: off → banner → inplace
-	Decrease font size
=	Increase font size
Ctrl+C	Quit

In banner mode, you can drag the overlay to reposition it.

Overlay Modes

Banner Mode (default)

A subtitle bar at the bottom of the screen displaying translated text. Draggable, opaque background, centered text.

Inplace Mode

Transparent overlay positioned over the game window. Translated text appears directly over the original Japanese text at OCR-detected positions. Click-through so you can interact with the game.

Configuration

Edit config.yml:

# Window to capture (partial title match)
window_title: "Tales"

# Refresh rate in seconds
refresh_rate: 0.5

# OCR confidence threshold (0.0-1.0)
# Filters out garbage text by average per-line confidence
ocr_confidence: 0.6

# Subtitle appearance
font_size: 24
font_color: "#FFFFFF"
background_color: "#404040"

How It Works

1. Screen Capture - Captures the target window at the configured refresh rate
2. OCR - MeikiOCR extracts Japanese text (optimized for pixel fonts)
3. Translation - Sugoi V4 translates Japanese to English
4. Display - Shows translated text in the selected overlay mode

Troubleshooting

Window not found

Use --list-windows to see available windows. The window title is a partial match.

Poor OCR accuracy

Try adjusting ocr_confidence in config. Lower values include more text (but may include garbage), higher values are stricter.

Slow performance

First run downloads models (~1.5GB). Subsequent runs use cached models from ~/.cache/huggingface/.

What's New in v2

• Inplace overlay mode - Text appears directly over game text
• Mode cycling - Press m to switch between off/banner/inplace
• Font size adjustment - Press -/= to resize on the fly
• Translation caching - Fuzzy matching reduces redundant translations
• Improved OCR - Punctuation excluded from confidence calculation
• Better window capture - Excludes overlapping windows, auto-detects fullscreen
• Multi-display support - Overlay appears on the same display as the game