Install
- Chrome, Edge, Brave, Vivaldi, Opera: Chrome Web Store
- Firefox, desktop and Android: Firefox Add-ons. The
.xpi on GitHub releases is unsigned and won't install.
- Safari, iPhone, iPad: the free Userscripts app plus
https://yomureader.com/yomu.user.js. Steps.
- Games and desktop apps: よむ Desktop for Windows, macOS and Linux.
Store versions can lag a GitHub release by a few days while the stores review it.
Use it
- Open something Japanese you want to read or watch.
- Hover the word you don't know. Tap on a phone.
- Save the words worth keeping, then review them in Study or send them to Anki, JPDB or Jiten.
Hold a word in a link or button to look it up. A quick tap keeps the website’s action.
Words saved without a connected service go to the Default deck in Study.
In Study, open Stats to check your review progress. Refresh keeps the current figures visible while loading.
Furigana stays readable without changing the page’s font or spacing. Readings that cannot fit remain available in word lookup.
On filtered YouTube recommendation lists, Load more appears after two automatic batches or an unfinished visible loader. Tap it to continue loading videos.
Hiding the よむ subtitle overlay leaves YouTube’s native captions available. The native Play button resumes from a word lookup, and the seek bar follows the resized player.
Subtitles keep a steady baseline as readings appear, with a dark background for the Japanese line, readings and translation. Site dialogs and word lookup stay above them. The subtitle style button changes the font and background.
Words can still be looked up without a coloured underline. Search and comment fields keep their normal typing behavior.
OCR text and corner marks on ordinary page images scroll with the image. Decorative blurred copies do not get a second mark.
The よむ button and its menu keep their screen size during pinch zoom. The menu closes when you pan or change the visible viewport.
No account and no setup. How to learn Japanese with よむ is one page.
Readings follow the page’s typeface and scale with its text. Their colour matches the word they annotate. With a study source, known and due words lose their readings; missed words keep them.
On another website, the Settings action opens Study settings directly. If a reading would cover nearby text, open that word’s lookup to see it.
Privacy
Settings, dictionaries and saved words stay on your device. No ads, no analytics, nothing sold. よむ contacts a service only when a feature needs it:
- The word you look up goes to Jiten, JPDB and Bunpro for its meaning, pitch accent and frequency.
- Page parsing stays on-device with the local parser and an enabled word dictionary. Otherwise, page text can go to Jiten or JPDB.
- Recommended dictionaries come from Yomu's mirror. WTY JA-JA comes from its project on Hugging Face, Kanjium pitch accents from FooSoft's Yomichan repackaging on GitHub, and Jitendex and Jiten from their own projects.
- Audio sources, OCR (Google Lens by default), translation and any review service you connect get only what that feature needs.
The privacy policy lists every service.
Development
npm ci
npm run check
npm ci installs the committed dependency versions without rewriting the lockfile, as CI does.
Common commands:
npm run dev # userscript/docs dev harness
npm run dev:vite # plain Vite/new-tab dev server
npm run build # production userscript + hosted assets
npm run verify # userscript metadata and size checks
npm run qa # build + smoke/a11y/complexity checks
Greasy Fork's upload budget is 2,000,000 raw bytes for dist/yomu.user.js; npm run verify enforces the hard limit and warns when the bundle gets tight.
Repository layout
src/reader/, src/academy/, and src/gaming/ contain product source code.academy/index.html is the Vite URL entry for /academy/; it is a shell, not a second Academy implementation.public/ contains static build inputs. docs/public/ is the GitHub Pages deployment mirror generated by the build/sync scripts. Only the parts of that mirror with no other committed home are tracked; docs/public/academy/ in particular is rebuilt from public/academy/ by npm run build:academy, so run it before npm run docs:build on a fresh clone.workers/ contains separately deployed Cloudflare Worker entrypoints; tests/, scripts/, and config/ contain the verification harness.video/ is the Remotion project that renders feature clips (cd video && npm run frames && npm run render). It has its own package.json so the userscript bundle never sees its dependencies, and it is not part of npm run check. See video/README.md.- Research corpora, reference checkouts, agent state, QA screenshots, session reports and worktrees stay local and ignored.
npm run check:repository fails if one is tracked, if a binary under docs/ is too big or not allowlisted, or if AGENTS.md names a missing path. The archived originals under docs/academy/recovery/recovered-assets/ are tracked on purpose: tests compare the shipped art with them byte for byte.
npm run build:extension also needs the UserScript Compiler, which lives in its own repository. Clone it into the ignored tools/ directory and install its dependencies once:
git clone https://github.com/HRussellZFAC023/UserScript-Compiler.git tools/UserScript-Compiler && npm --prefix tools/UserScript-Compiler ci
Set USERSCRIPT_COMPILER_CLI to that checkout's src/cli.mjs instead if you keep it somewhere else.
GitHub Actions cover CI, userscript bundling, docs deployment, extension builds, and release publishing.
CI runs typecheck, tests, build, and userscript metadata verification.Build Userscript builds dist/yomu.user.js and commits it back to main when the bundle changes.Deploy Docs builds the VitePress docs and publishes GitHub Pages.Release publishes the compiled userscript and browser-extension artifacts when a v* tag is pushed or the workflow is run manually.
GreasyFork does not provide a general write API for unattended publishing. After the first logged-in publish, configure GreasyFork to sync updates from:
https://raw.githubusercontent.com/HRussellZFAC023/yomu-reader/main/dist/yomu.user.js
That sync updates the userscript and its metadata header, but not the listing's Additional info prose. When a feature release changes product scope or positioning, update that field in the signed-in GreasyFork editor and verify both the public .meta.js and .user.js after the main-branch sync.
Support
If よむ helps you read more Japanese, a star helps other learners find it.
Credits
よむ is MIT-licensed. The dictionaries, kanji data and projects it builds on, with their licences, are on the credits page.
