@tortaruga/kanaji

A lightweight JavaScript library to convert between Roumaji script and Japanese Kana.

---

⚡ Features

• Convert Roumaji ↔ Hiragana/Katakana
• Convert Hiragana ↔ Katakana
• Support basic punctuation and digits
• Support both Hepburn romanization system and Nihon-Shiki (view notes on transliteration for more details)

---

📦 Installation

npm install @tortaruga/kanaji

💻 Usage

Import the functions:

import { 
  toHiragana, 
  toKatakana, 
  toRoumaji,
  hiraganaToKatakana, 
  katakanaToHiragana 
} from '@tortaruga/kanaji';

All functions take a string as input.

• Latin inputs support basic punctuation and digits.
• Japanese inputs support full-width punctuation and digits only.

Supported punctuation

The following punctuation and digits are supported in Roumaji input:

Digits: 0 1 2 3 4 5 6 7 8 9
Punctuation: , . - ! ?

The following full-width punctuation and digits are supported in Kana input:

Digits: ０ １ ２ ３ ４ ５ ６ ７ ８ ９
Punctuation: ､ ｡ － ！ ？

Conversion from Roumaji

toHiragana('Ohisashiburi desu!') // Output: おひさしぶりです！
toKatakana('resutoran') // Output: レストラン

Conversion to Roumaji

toRoumaji('にほんご を はなします か？'); // Output: nihongo wo hanashimasu ka?
toRoumaji('エート｡｡｡'); // Output: eeto... 

Converion between Kana

hiraganaToKatakana('ありがとう'); // Output: アリガトウ 
katakanaToHiragana('アリガトウ'); // Output: ありがとう 

⚠️ Notes on transliteration

This library supports both the Hepburn and Nihon-shiki romanization systems, with a few practical exceptions to reduce ambiguity:

• Because the converter doesn't include a grammar parser, は is always romanized as "ha" (never "wa"), including when used as a particle; to produce は when converting from roumaji, use "ha" ("wa" maps to わ).

• へ is always romanized as "he" (never "e"), including when used as a particle; to produce へ when converting from roumaji, use "he" ("e" maps to エ).

• the particle を is always romanized as "wo" (never "o"); to produce を when converting from roumaji, use "wo" ("o" maps to お).

• Japanese text typically does not include spaces. Since the converter cannot recognize word boundaries, the romanized output will also omit spaces (unless provided in the kana input).

• Only valid Japanese syllables will be converted. For foreign words, the converter cannot automatically adapt them into appropriate Japanese phonetic equivalents. You’ll need to manually adjust the input to match valid syllables (e.g., use "Makudonarudo" for "McDonald's").

• When entering roumaji, use "ei" for long e sounds and "ou" for long o sounds.

• Other long vowels are doubled: "aa", "ii", "uu". This avoids the need for macrons (e.g., ā, ī, ū, ē, ō), which are less convenient to type.

• じ / ジ is romanized as "ji", while ぢ / ヂ is romanized as "di".

• ず / ズ is romanized as "zu", while づ / ヅ is romanized as "du".