Interpreter reads Japanese game text straight off the screen

Window level OCR aimed at pixel fonts, not general documents

Interpreter is a desktop overlay translator for Japanese retro games. Rather than asking the player to look a phrase up in a browser, it watches a window, reads the Japanese text out of the pixels, translates it into English and draws the result over the same window. The scope is deliberately narrow. The bundled OCR model was trained on Japanese game text and is tuned for the pixel fonts that older console and arcade titles use, so it is a poor fit for a PDF, a messaging app or a blog post. The audience is the person holding a Japanese cartridge, a controller and no interest in learning kanji. What you get in exchange is a tool that makes no cloud calls at all once the models are on disk, which matters if you would rather game text and screenshots never left your machine.

Four stages from captured pixels to a subtitle bar

The pipeline has four stages, and their order explains most of the behaviour you will notice in use. Screen capture comes first, pulling the target window at a configured refresh rate. MeikiOCR then extracts the Japanese text, with pixel-font characters as its specialty, although an external owocr server can be used instead if you prefer another engine. Sugoi V4 performs the Japanese to English translation. A display layer puts the result on screen in one of two overlay modes. Every stage runs locally. The dependency list supports that claim: onnxruntime and ctranslate2 do the inference work, and the only network oriented package in the list is requests, which the project uses for model downloads. Translation caching uses fuzzy matching, so a repeated line such as a fixed menu label is not sent through the translator on every frame. Capture cards are also listed as sources, which lets a console feed video to the PC and have the banner float on the desktop.

install.sh leaves a launcher named interpreter-v2 on your path

Installation is one piped script on macOS and Linux:

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

The installer places the application, its own Python runtime and the downloaded models under your user profile. Windows follows a PowerShell equivalent described in the installation instructions. Supported systems are Windows 10 version 1903 or newer, macOS, and Linux on X11, XWayland or Wayland, and the project asks for at least 6 GB of free disk space for dependencies and first run model downloads. After the install, start the launcher:

interpreter-v2

That opens the GUI, where you choose the window to capture and configure the rest. Only a small launcher and your config.yml stay in the user profile, so the bulk of the install is easy to find and to remove later. On macOS the first capture raises the camera permission prompt for the terminal that launched the application, which is the capture API asking for screen recording rights.

Banner mode versus inplace overlay under Wayland

Banner mode, the default, draws a subtitle bar across the bottom of the screen with a draggable position, an opaque background and centred text. Inplace mode is a transparent, click-through overlay that places the translation directly above the original Japanese text at the positions OCR reported, so the game stays playable. Video sources are restricted to banner mode because there is no on-screen window to draw over. Exclusion zones and the OCR confidence value are remembered per device as well as per window. The compositor is the deciding factor on Linux. On Wayland the inplace overlay works only with fullscreen windows, because the security model prevents a process from learning where other windows sit.

Linux installs fail on missing libraries, not on broken code

Linux support carries most of the installation risk, and the failure modes are specific enough to check before you start. Global hotkeys require membership of the input group, and the installer shows instructions for that. Native Wayland capture needs the PipeWire runtime plus a ScreenCast capable desktop portal, for example xdg-desktop-portal-kde on Plasma. A KDE message reading Unsupported compositing type means KWin cannot provide a capture stream with its current compositing backend. The project points at this diagnostic command and the KWin logs, with an X11 session as a possible workaround:

qdbus6 org.kde.KWin /KWin org.kde.KWin.supportInformation

Two library traps cause a hard abort rather than a degraded run. The Qt platform plugin xcb needs libxcb-cursor0 on Debian, Ubuntu and Mint or xcb-util-cursor on Fedora and Arch, otherwise the GUI stops with Could not load the Qt platform plugin "xcb". Qt Multimedia needs the PulseAudio client library libpulse.so.0, provided by libpulse0 on Debian, Ubuntu and Mint, including on PipeWire desktops, and the PulseAudio server itself is not required.

Sugoi V4 by default, a local LLM endpoint if you want more

Sugoi V4 ships as the built-in translation engine and needs no setup. If you would rather run a larger language model, the Translation panel can send text to an Ollama server or to any OpenAI compatible endpoint such as LM Studio, a llama.cpp server, vLLM, OpenRouter or OpenAI. The application sends only the OCR text and displays the reply. The recommended pull is a Japanese media translation model that needs about 10 GB of VRAM:

ollama pull hf.co/sugoitoolkit/Sugoi-14B-Ultra-GGUF:Q4_K_M

On the project's own benchmark it scores 12 chrF++ points higher than the built-in Sugoi V4 across every game, and the numbers live in benchmark/translation/RESULTS.md. Hardware is the deciding factor for everyone else. The documentation says gemma3:4b at 3.3 GB is roughly on par with the built-in model, while anything under 2B mostly produces romaji or nonsense. In the interface you set Engine to LLM endpoint, leave the provider on Ollama and the URL on http://127.0.0.1:11434, click Refresh to list models, then Test to see the round trip time of a sample line before applying.

Moving a four gigabyte install with INTERPRETER_HOME

The default footprint is about 3 GB of application files plus 1.1 GB of models downloaded on first run. If the system drive is tight, the installer accepts an INTERPRETER_HOME pointing at a folder on another drive:

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

The application, its Python runtime and the models all land in that folder, and the location is recorded in ~/.interpreter/install-dir so later upgrades and the uninstaller find it without setting the variable again. Running the installer again with a different INTERPRETER_HOME removes the application from the old location and reinstalls it in the new one, and the models are downloaded again on first run, with the installer printing where the old ones are so they can be deleted. Removal is a separate script:

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

It removes the launcher, the config files and the cached models.

MIT terms, tagged releases and a bounded Python range

The project is released under the MIT licence, which permits reuse and modification under its notice and warranty clauses. The distribution is version 2.23.2 with releases tagged v2.23.0 on 2026-09-12, v2.23.1 and v2.23.2 both on 2026-09-18, and the last push was on 2026-10-06. The package metadata pins the runtime to Python 3.11 or 3.12 through requires-python, and the source tree carries a .python-version file and a uv.lock, so reproducing an environment means matching that range rather than installing the newest interpreter available. The GUI is PySide6, capture on Linux comes through python-xlib on X11 and pipewire-capture on Wayland, and macOS and Windows use Quartz and pygetwindow respectively. There is a tests directory and a CI workflow in .github, and the project asks contributors to remove account details, phone numbers, ID numbers, cookies, tokens and order data from any logs they attach.

Editorial conclusion

Adopt Interpreter if you play Japanese retro titles and want translated dialogue without an internet connection or a cloud account, and stay on Linux only if you can sort out PipeWire, the portal and the xcb cursor library. Do not adopt it for prose translation, for text that does not render in pixel fonts, or if you need a maintained 12306 style release cadence with documented installer changes. Before you install, verify that your GPU can run the chosen translation model, that your Wayland compositor exposes a ScreenCast portal if you use Wayland, and that the version you pull matches the tag whose release notes you actually read.

Frequently asked questions

Official sources

1. bquenin/interpreter on GitHub
2. Issues
3. License: MIT
4. README
5. Releases