yet another tool to help Japanese language learners read text in video games
- annotate kanji with furigana
- color code proper nouns (like NHK News Web Easy)
- look up words on mouse hover, or open Jisho or Wikipedia
- automatically collect vocabulary with context
- (optional) English subtitles via machine translation
before:
after:
This is a work in progress and is rough around the edges.
- Windows, Linux, or Mac (tested on Windows 10, Ubuntu 22.04, and macOS Montery)
- Python 3.10.x (tested with 3.10.9)
- either Tesseract or a Google Cloud Vision API account
- (optional) DeepL API account for machine translated subtitles
- (Linux only) scrot, python3-tk, python3-dev. X11 only for now, Wayland may not work
on Windows, the following worked:
- install Python 3.10.x
- install
zoritori
via pip (optionally via pipx)
on Mac and Linux, I ran into numerous issues installing via pip/pipx, so for now use the development process:
- install Python 3.10.9 (recommended via pyenv)
- install Poetry
- clone this repo
- install dependencies via
poetry install
- when running
zoritori
, usepoetry run python -m zoritori ...
(see below for command line args)
for all platforms:
- download the example config file from here
- if using Tesseract, follow these instructions to install it, then configure it by specifying the path to the
tesseract
binary inconfig.ini
- if using Google Cloud Vision, follow these steps to create a project and download a credentials JSON file. then add that as an environment variable. Windows:
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\json"
, Mac/Linux:export GOOGLE_APPLICATION_CREDENTIALS=/path/to/json
- start:
zoritori -e <tesseract|google> -c /path/to/config.ini
- an invisible window (with title "zoritori") should appear. make sure this window has focus
- identify the region of the screen containing text you want to read
- using your mouse, (left) click and drag a rectangle around the text
- after a moment, you should see furigana over any kanji in the region, and proper nouns highlighted (blue, orange, and green boxes). hovering over words inside the region should display a dictionary result, if one is found
key | Description |
---|---|
T | toggle translation |
C | manual refresh |
J | open Jisho search for word under cursor |
W | open Japanese Wikipedia search for word under cursor |
E | open English Wikipedia search for word under cursor |
R + mouse-drag | select main region when in click through mode |
Q + mouse-drag | select one time lookup when in click through mode |
After selecting a region, zoritori
will watch that area for changes, and refresh if any are detected. If you want to select a new region, just click and drag again. If you want to keep your original region, but want to do a one-time look up a word outside the region, right click and drag around the word.
By default, the transparent overlay won't send clicks through to underlying applications, including your game. It will steal focus if you click anywhere on the screen. On Windows only (for now) you can enable click through mode in the config.ini
file or command-line parameters. On Mac and Linux, this is not supported at the moment.
When click through mode is enabled, use R (without mouse clicking) to drag select a region, and use Q to select a region for a one-time lookup.
Tesseract is free, open source, and works offline. Unfortunately, in my experience it has less accurate recognition, and sometimes returns very messy bounding box data, making it difficult to accurately place furigana.
Google Cloud Vision has per usage costs, but should be free for low usage, and is closed source and requires an Internet connection (the selected region is sent as an image to Google for processing)
By default nothing is saved. But if you want to save vocabulary words, add a folder name in the config.ini
file or command-line parameters.
With only NotesFolder
set, all vocabulary will be saved in one folder. Fullscreen screenshots are saved each time OCR runs, along with a markdown file that include new vocabulary found, for later review.
With only NotesRoot
set, vocabulary will be saved as above but inside individual folders for each session (once for each time you start zoritori
) to make review less cumbersome.
With both NotesFolder
and NotesRoot
set, NotesFolder
behavior takes precedence (everything saved in one folder).