hibi-nihongo-note

Inspiration

Japanese learners who use Traditional Chinese often have to switch between separate grammar websites, vocabulary apps, dictionaries, mock exams, and personal notes. The available resources are also frequently written for English speakers or organized around isolated facts rather than a clear learning path.

We wanted to create a single, calm learning space where Traditional Chinese speakers could study Japanese from N5 to N2, understand why an answer is correct, and build a reliable daily study habit. The goal was not merely to generate a large question bank, but to make every lesson and exercise traceable, reviewable, and useful to an actual learner.

What it does

hibi-nihongo-note is a Japanese learning and JLPT preparation platform designed specifically for Traditional Chinese speakers.

It currently provides:

• A structured N5 and N2(work in process) curriculum with 118 lessons covering kana, vocabulary, kanji, grammar, reading, and listening
• More than 16,000 production-ready practice questions
• Vocabulary exercises for meaning, reading, conjugation, word class, and transitivity
• Grammar exercises with stable question IDs and traceable source frameworks
• 150 original reading passages with comprehension questions
• Listening practice using reviewed MP3 recordings and browser-based Japanese text-to-speech
• Two full-range N4 mock examinations
• Search, bookmarks, lesson progress, practice history, and custom practice sessions
• Immediate guest access with progress stored locally in the browser
• Optional Google sign-in for synchronizing progress and bookmarks across devices
• A contextual issue-reporting system that automatically includes the current page, lesson, exam, or question ID

The platform is designed to work without an account. Cloud synchronization is optional rather than mandatory.

How we built it

The frontend was built with React, TypeScript, Vite, and React Router. Lessons are written in Markdown with structured front matter, allowing the educational content to remain readable and version-controlled independently from the interface.

We used Codex Sol Ultra as an AI implementation partner to accelerate scaffolding, refactoring, test creation, and content-system development. Human review remained essential for defining requirements, identifying linguistic problems, and deciding whether generated content was safe for learners.

The practice system combines individually written questions with structured generators for vocabulary, kanji, grammar, reading, and listening. Every generated question keeps provenance information such as its source lesson, framework, or scenario.

Firebase provides:

• Hosting
• Optional Google authentication
• Per-user Firestore synchronization
• Security rules and App Check
• Restricted anonymous issue submission

We also built validation and auditing tools that check:

• Lesson metadata and prerequisite ordering
• Vocabulary structure and conjugations
• Duplicate or ambiguous answers
• Question-option integrity
• Reading context and listening assets
• Published question counts
• Firebase rules
• Public, guest, and private deployment configurations

Potentially unsafe generated content can be quarantined and excluded from both production totals and the learner interface.

Challenges we ran into

The largest challenge was not building the interface—it was maintaining linguistic correctness at scale.

A grammatically valid sentence does not always produce a fair multiple-choice question. Several answers may be technically possible unless the situation, speaker, listener, social relationship, and intended nuance are clearly defined.

This became especially important for:

• Japanese honorific language and the distinction between in-group and out-group members
• Giving and receiving expressions such as あげる, くれる, and もらう
• Conditional forms such as と, たら, なら, and ば
• Reverse translation questions where one Traditional Chinese meaning may correspond to several Japanese words
• Distractors that are structurally different but still valid in the original context

We therefore had to move beyond simple answer matching and introduce semantic relationships, learner-visible uniqueness checks, stable question IDs, review states, regression tests, and quarantine rules.

Another challenge was supporting both anonymous local use and optional cloud synchronization. We needed a conflict-resolution strategy that preserved the newest progress record without unexpectedly overwriting local study data.

Finally, large AI-assisted changes were difficult to audit. We learned to divide content review into small, fixed batches and record exactly which questions were inspected and which source-level changes affected questions outside the batch.

Accomplishments that we're proud of

We are proud that hibi-nihongo-note has evolved from an AI-generated prototype into a testable educational content system.

Some of the accomplishments include:

To build a complete learning path from N5 to N4 for learners of Traditional Chinese, and to continuously expand to N2. Publishing 118 structured lessons and more than 16,000 production questions Creating original reading and listening materials rather than copying existing learning websites Supporting both account-free learning and optional cross-device synchronization Building a custom practice system that can combine lessons and skills Establishing automated checks for ambiguous reverse-translation questions Adding explicit review states so generated, structurally validated, linguistically reviewed, and native-reviewed content are not treated as equivalent Quarantining unreviewed honorific questions instead of exposing them simply to increase the question count Creating an auditable batch-review workflow for gradually improving individual questions Maintaining deployment, content, practice, and Firebase security validation in the same repository

The most important accomplishment is that the project now has mechanisms for recognizing uncertainty instead of presenting every generated answer as unquestionably correct.

What we learned

We learned that AI can produce software and educational content quickly, but speed makes quality-control architecture more important—not less important.

For language-learning software:

A valid sentence is not automatically a valid question A marked answer is not automatically the only correct answer Grammar labels alone cannot represent pragmatics or social relationships Translation questions must be evaluated from the learner-visible prompt, not only from internal course identifiers Large question counts have little value without provenance and review status Content validation must be treated with the same seriousness as code testing Human judgment is still necessary for naturalness, nuance, register, and pedagogy

We also learned that small, fixed review batches are much more effective than attempting to “review the entire question bank.” They create measurable progress, clearer regressions, and a repeatable standard for future contributors.

What's next for hibi-nihongo-note

The immediate priority is question refinement rather than question expansion.

We are reviewing the existing question bank in fixed batches, beginning with grammar areas where perspective and context are especially important. The next batch focuses on N4 giving and receiving expressions, including:

あげる, くれる, and もらう 〜てあげる, 〜てくれる, and 〜てもらう The speaker’s point of view The direction of benefit Social distance and potentially patronizing expressions More appropriate alternatives such as 〜ましょうか and 〜ていただく

Longer-term plans include:

Continuing systematic human and native-speaker review Expanding contextual workplace Japanese lessons Adding more interactive listening and spoken-response practice Improving explanations for why distractors are incorrect Building better review scheduling and weak-point tracking Improving accessibility, mobile usability, and study analytics Gradually returning quarantined content only after it passes semantic review

Our long-term goal is for hibi-nihongo-note to become more than an JLPT question bank: a reliable daily Japanese-learning environment that helps Traditional Chinese speakers move from recognizing grammar to using Japanese naturally in real situations.

Built With

• firebase
• typescript
• vite