The Conversion Engine

Chapter 1 decided the conversion algorithm will eventually live on a real Express API. This chapter deliberately doesn't wire anything up to Angular or Express yet — it builds the engine itself as a plain, framework-agnostic module, tested against real input in isolation first. Chapter 4 decides how Angular's own side organizes around it; Chapter 5 moves the canonical copy into Express. Getting the actual algorithm correct comes first.

The Gojūon Table: Japan's Real 5×10 Sound Grid

Japanese kana are built around a real, systematic structure — five vowels (a, i, u, e, o) crossed with nine consonant rows, plus one standalone sound (ん/ン, "n"). A handful of cells are irregular under Hepburn romanization — し is "shi" not "si," ち is "chi" not "ti," つ is "tsu" not "tu," ふ is "fu" not "hu" — genuine historical exceptions baked into the standard system itself, not something this course invented:

Voiced and Semi-Voiced Sounds

A dakuten mark (゛) or handakuten mark (゜) shifts a base consonant into a real, distinct sound — G/Z/D/B rows, and a P row from H. There's a real, genuine ambiguity worth naming honestly rather than hiding: standard Hepburn romanizes both じ and ぢ as "ji", and both ず and づ as "zu" — a flat romaji-keyed table simply cannot tell these apart. This table maps "ji"/"zu" to their far more common Z-row readings (じ/ず); the rarer ぢ/づ, mostly confined to specific compound-word contexts, aren't reachable through plain romaji input at all.

Combination Sounds (Yōon)

A consonant fused with a small ゃ/ゅ/ょ produces a real third category — genuinely three-character romaji tokens like kya, sha, cha — with one more real Hepburn simplification: the sounds spelled じゃ/じゅ/じょ (from the Z row) romanize as ja/ju/jo, just two characters, not "jya."

A Naive Two-Character Tokenizer — And a Real Bug

Romaji tokens genuinely vary in length — one character (a, n), two (ka, shi), or three (kya). A first, reasonable-looking tokenizer only ever tries two characters, then falls back to one:

convertNaiveV1('kyaku') — a real word, 客 (customer) — walks through position 0 trying "ky" (not a valid token) and then "k" alone (also not valid, since only vowels and n are genuine one-character tokens), falling all the way back to emitting the raw letter k unconverted. The result is kやく — a broken mix of a literal Latin letter and two real kana, because the algorithm never even attempts a 3-character match at all.

Adding a Third Length Isn't Enough on Its Own

The obvious fix adds a length-3 check into the same loop — but the order those lengths are tried in matters just as much as trying them at all:

convertNaiveV2('kyaku') actually works — "k" and "ky" both genuinely fail to match anything, so the loop reaches length 3, finds "kya", and produces the correct きゃく. But convertNaiveV2('na') — the single, ordinary syllable な — fails in a real, different way: at position 0, length 1 is tried first, and "n" is a genuinely valid one-character token on its own (ん). The loop matches it immediately and stops, never trying the longer, correct "na" at all. The remaining "a" is then converted separately, producing んあ — two syllables — instead of the single, correct な.

The Real Fix: Always Check Longest-to-Shortest

Trying lengths in descending order guarantees the longest possible match is always found first — and trying a longer chunk that turns out not to match costs nothing, since the loop simply falls through to a shorter length next:

Both real bugs are resolved by the identical, single change — checking length 3, then 2, then 1, rather than the other way around. convert('kyaku').hiragana still correctly produces きゃく, and convert('na').hiragana now correctly produces the single syllable な, with んあ never entering into it.

Trying the Engine in Isolation

A quick script — not yet connected to Angular or Express — confirms the engine on three real words:

That last one is worth pausing on. The real, formal greeting is written こんにちは — using the character は (normally "ha"), pronounced "wa" specifically in this one fossilized grammatical role. Typed literally as "konnichiwa," this engine — correctly, given only what it knows so far — produces こんにちわ instead, a genuinely common casual spelling that plenty of native speakers use interchangeably, but not the traditionally "correct" one. Recognizing when a trailing "wa" really means は is exactly the kind of particle exception Chapter 3 builds real handling for.

Where This Engine Will Actually Live

Nothing built in this chapter depends on Angular or Express — KANA_MAP and convert() are plain TypeScript, testable with nothing more than node or a browser console. Chapter 4 decides how the Angular side of this project organizes its own services around calling this logic; Chapter 5 moves this exact file, unchanged, into the real Express API this course exists to build.

Hands-On Exercises