interpreter-v2 2.2.1

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+ (Python 3.14 not yet supported)
• Windows 10 version 1903+, macOS, or Linux (X11/XWayland)
• Git (Windows: install Git for Windows)

Installation

One-liner Install

macOS/Linux:

curl -LsSf https://raw.githubusercontent.com/bquenin/interpreter/main/install.sh | bash

Windows (PowerShell):

powershell -c "irm https://raw.githubusercontent.com/bquenin/interpreter/main/install.ps1 | iex"

Then run with interpreter-v2.

Upgrading

To update to the latest version, run the install script again:

macOS/Linux:

curl -LsSf https://raw.githubusercontent.com/bquenin/interpreter/main/install.sh | bash

Windows (PowerShell):

powershell -c "irm https://raw.githubusercontent.com/bquenin/interpreter/main/install.ps1 | iex"

Usage

# List available windows
interpreter-v2 --list-windows

# Run with default config
interpreter-v2

# Run with specific window
interpreter-v2 --window "Tales"

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

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

Controls

Default hotkeys (configurable in config.yml):

Key	Action
Space	Toggle overlay on/off
m	Switch mode: banner ↔ inplace
-	Decrease font size
=	Increase font size
q	Quit

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

Custom Hotkeys

You can customize hotkeys in config.yml:

hotkeys:
  toggle_overlay: "space"   # Toggle overlay on/off
  switch_mode: "m"          # Switch between banner/inplace
  increase_font: "="        # Increase font size
  decrease_font: "-"        # Decrease font size
  quit: "q"                 # Quit application

Supported key values:

• Single characters: a-z, 0-9, `, -, =, etc.
• Function keys: f1-f12
• Special keys: space, escape, enter, tab, backspace, delete, insert, home, end, page_up, page_down, up, down, left, right

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