kana-utils

A lightweight, zero-dependency TypeScript library for Japanese kana conversion and manipulation. Convert between Hiragana, Katakana, and Romaji with full support for dakuten, handakuten, youon, and multiple romanization systems.

Features

• Conversion: Hiragana ↔ Katakana ↔ Romaji
• Multiple Romanization Systems: Hepburn, Kunrei-shiki, and Nihon-shiki
• Complete Kana Support: Dakuten, handakuten, youon, small tsu
• Half-width Katakana: Automatic conversion to full-width

Installation

npm install kana-utils

Quick Start

import { toKatakana, toHiragana, toRomaji } from 'kana-utils';

// Basic conversions
toKatakana('こんにちは'); // "コンニチハ"
toHiragana('コンニチハ'); // "こんにちは"
toRomaji('こんにちは');   // "konnichiha"

// Mixed text handling
toRomaji('こんにちは世界'); // "konnichiha世界"

// Advanced features
toRomaji('きょうと', { useMacrons: true }); // "kyōto"
toRomaji('しち', { system: 'kunrei' });     // "siti"

API Reference

toKatakana(text: string): string

Converts Hiragana and half-width Katakana to full-width Katakana.

toKatakana('こんにちは');    // "コンニチハ"
toKatakana('ｺﾝﾆﾁﾊ');        // "コンニチハ"
toKatakana('がっこう');      // "ガッコウ"
toKatakana('きゃっち');      // "キャッチ"

toHiragana(text: string): string

Converts Katakana and half-width Katakana to Hiragana.

toHiragana('コンニチハ');    // "こんにちは"
toHiragana('ｺﾝﾆﾁﾊ');        // "こんにちは"
toHiragana('ガッコウ');      // "がっこう"
toHiragana('キャッチ');      // "きゃっち"

toRomaji(text: string, options?: RomajiOptions): string

Converts Hiragana and Katakana to Romaji.

Options:

• system: 'hepburn' | 'kunrei' | 'nihon' (default: 'hepburn')
• useMacrons: boolean - Use ō/ū instead of ou/uu (default: false)

// Basic conversion
toRomaji('こんにちは'); // "konnichiha"

// Different romanization systems
toRomaji('しちふじ', { system: 'hepburn' }); // "shichifuji"
toRomaji('しちふじ', { system: 'kunrei' });  // "sitihuzi"
toRomaji('しちふじ', { system: 'nihon' });   // "sitihuzi"

// Macron support
toRomaji('おおきい', { useMacrons: true }); // "ōkii"
toRomaji('ゆうびん', { useMacrons: true }); // "yūbin"

// Complex examples
toRomaji('きっぷ');     // "kippu"
toRomaji('がっこう');   // "gakkou"
toRomaji('しゃしん');   // "shashin"

Supported Kana Features

Basic Kana

toRomaji('あいうえお'); // "aiueo"
toRomaji('かきくけこ'); // "kakikukeko"

Dakuten (濁音) and Handakuten (半濁音)

toRomaji('がぎぐげご'); // "gagigugego"
toRomaji('ぱぴぷぺぽ'); // "papipupepo"

Youon (拗音) - Small Kana

toRomaji('きゃきゅきょ'); // "kyakyukyo"
toRomaji('しゃしゅしょ'); // "shashusho"
toRomaji('ちゃちゅちょ'); // "chachucho"

Small Tsu (促音) - Double Consonants

toRomaji('かった');   // "katta"
toRomaji('きっぷ');   // "kippu"
toRomaji('ざっし');   // "zasshi"

Long Vowels

toRomaji('おおきい');     // "ookii"
toRomaji('おおきい', { useMacrons: true }); // "ōkii"
toRomaji('コーヒー');     // "koohii"

Romanization Systems

Hepburn (Default)

Most common system, used in passports and road signs.

toRomaji('しちふじ'); // "shichifuji"

Kunrei-shiki (訓令式)

Official system in Japan, used in education.

toRomaji('しちふじ', { system: 'kunrei' }); // "sitihuzi"

Nihon-shiki (日本式)

Older system, similar to Kunrei-shiki.

toRomaji('しちふじ', { system: 'nihon' }); // "sitihuzi"

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

Development

git clone https://github.com/denver-edwards/kana-utils
cd kana-utils
npm install
npm test

License

AGPL-3.0 License - see LICENSE file for details.

Related Projects

• kana-kara - Kana library
• jlpt - JLPT utility