KotoDane

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend*

What I Built

Kotodane (言種, "word seed"): a Japanese reading tutor where manga grows into kanji as you learn, and the AI never talks over your head.

I built it for my friend Neeraj. He's learning Japanese so he can read his favorite manga, and one day watch anime with no subtitles. He knows hiragana, katakana and about 50 kanji. Open a real manga page and it's a wall of symbols he can't read.

Google Lens can translate that page, but it forgets him the moment it's done. It doesn't know what he knows, and a translation doesn't teach him to read. So I built something that remembers.

What happens when he crops a speech bubble:

1. OCR reads it. manga-ocr, an open model built for manga fonts and vertical text.
2. The text adapts to him. Kanji he knows stay as kanji. Everything else shows as hiragana. Learn a new kanji, and the same page grows.
3. He taps a word and a local LLM explains it in simple Japanese, using only words and kanji he already knows, plus a short English hint.
4. A guardrail keeps the AI at his level. If the model uses a word he hasn't learned, the app catches it and asks again.

The best part: his progress is visible. The same page looks different after a week of study.

Demo

Before reading bubbble...

After the bubble is rendered..

There's no hosted link on purpose. Kotodane is private and local-first: his study history and the pages he reads never leave his laptop. The repo includes sample data so you can try it yourself.

Code
Github Repo:-

CodewithAdi7 / KotoDane

Local-first Japanese reading tutor built on open-source AI. Read manga with kanji that grow as you learn, powered by manga-ocr and a local LLM that explains at your level.

Kotodane (言種)

Read what you love. Watch the kanji grow.

Kotodane ("word seed") is a local-first Japanese reading tutor for beginner learners. Paste Japanese text or crop a bubble from a manga page, read it with kanji masking, look up words, and get level-checked explanations and practice sentences. Study data stays in a local SQLite database, and everything runs on your own machine: no cloud APIs, no accounts, no API keys.

Why I built it

I built Kotodane for a friend who is learning Japanese so he can read his favorite manga and, one day, watch anime without subtitles. He knows hiragana, katakana and a few dozen kanji, and a real manga page is a wall of symbols he can't read yet.

Tools like Google Lens can translate a page, but they forget you as soon as they're done. They don't know what you know, and a translation doesn't teach…

View on GitHub

How I Built It

Role	Open-source piece	License
Eyes	manga-ocr	[license]
Teacher	[qwen3:4b] running locally via Ollama	[license]
Tokenizing	fugashi + unidic-lite	[license]
Dictionary	JMdict / KANJIDIC2 via jamdict	EDRDG license

Backend: FastAPI + SQLite. Frontend: React + Vite. Everything runs on a normal laptop.

The idea I'm proudest of is the level-locked loop. Most AI tutors talk at whatever level the model feels like. Kotodane keeps a knowledge model of what my friend has learned, and uses it to constrain the LLM:

tap a word → LLM explains → tokenizer checks every word against what he knows
          → too many unknown words? retry with "avoid: ..." feedback
          → passes (or best of 3 tries) → shown in his personal kanji display

The LLM does the language work, and plain code enforces the learner's level.

Built with GitHub Copilot. I split the project into small phases (setup, tokenizer, dictionary, database, UI, OCR, LLM, guardrail), and gave Copilot one phase per session with a clear "done when" test. Keeping each session small made it faster and made bugs easy to isolate.

Honest limits: OCR struggles with stylized fonts, so the text is editable before it's processed. Kanji masking works on whole words for now.

Why Does Open Innovation Matter?

-Privacy. A learner's mistakes, history and reading material are personal. With local open models, none of it leaves his machine.
-No meter running. The guardrail loop can call the model several times per tap. On a paid API that's a bill and a rate limit. Locally it's free, so I could design around retries.
-The right tool exists because someone built it. manga-ocr was made for exactly this problem. A general closed API wouldn't have handled vertical manga text well.
-It's swappable and inspectable. A better Japanese model next month means changing one setting. And anyone can read, fork and improve the code, which is the spirit of Hacktoberfest.

Technology Used
-used codex and github copilot to write the full code locally on my system.
-used a local open source model qwen3:4b via ollama at the core of this app.

Prize Categories

Used Github Copilot for reviewing the code and fixing some bugs