wanakana

ワナカナ <--> WanaKana <--> わなかな

Javascript utility library for checking and converting between Kanji, Hiragana, Katakana, and Romaji

Demo

Visit the website to see WanaKana in action.

Documentation

Extended API reference

Quick Start

Install

yarn add wanakana
# alternatively: npm install wanakana

Or to get the minified browser (umd) bundle

https://unpkg.com/wanakana

Browser:

<input type="text" id="wanakana-input" />
<script src="https://unpkg.com/wanakana"></script>
<script>
  const textInput = document.querySelector('#wanakana-input');
  wanakana.bind(textInput); // uses IMEMode toKana() as default
</script>

JavaScript:

import wanakana from 'wanakana';
// with destructuring
import { toKana, isRomaji } from 'wanakana';
// directly reference single methods for smaller builds:
import isKanji from 'wanakana/isKanji';

/*** OPTIONS ***/
{
  // Use obsolete kana characters, such as ゐ and ゑ.
  useObsoleteKana: false,
  // Pass through romaji when using toKatakana() or toHiragana()
  passRomaji: false,
  // Convert katakana to uppercase when using toRomaji()
  upcaseKatakana: false,
  // Convert characters from a text input while being typed.
  IMEMode: false, // alternatives are: true, 'toHiragana', or 'toKatakana'
  // Choose toRomaji() romanization map
  romanization: 'hepburn' // (currently only hepburn)
  // custom map will be merged with default conversion
  customKanaMapping: {}
  // toKana('wanikani', { customKanaMapping: { na: 'に', ka: 'bana' }) });
  // => 'わにbanaに'
  customRomajiMapping: {}
  // toRomaji('つじぎり', { customRomajiMapping: { じ: 'zi', つ: 'tu', り: 'li' }) };
  // => 'tuzigili'
}

/*** DOM HELPERS ***/
// Automatically converts text using an eventListener on input
// Handles cursor positioning, mid-text insertion, passthrough native IME composition
// bind() uses option: { IMEMode: true } with `toKana()` by default
// Alternatives are: 'toHiragana' or 'toKatakana' to enforce kana type
wanakana.bind(HTMLElement [, options]);

// Removes event listener
wanakana.unbind(HTMLElement);


/*** TEXT CHECKING UTILITIES ***/
wanakana.isJapanese('泣き虫。！〜２￥ｚｅｎｋａｋｕ')
// => true

wanakana.isKana('あーア')
// => true

wanakana.isHiragana('げーむ')
// => true

wanakana.isKatakana('ゲーム')
// => true

wanakana.isKanji('切腹')
// => true

wanakana.isRomaji('Tōkyō and Ōsaka')
// => true

/*
 * toKana notes:
 * Lowercase -> Hiragana.
 * Uppercase -> Katakana.
 * Non-romaji and _English_ punctuation is passed through: 123 @#$%
 * Limited Japanese equivalent punctuation is converted:
 * !?.:/,~-‘’“”[](){}
 * ！？。：・、〜ー「」『』［］（）｛｝
 */
wanakana.toKana('ONAJI buttsuuji')
// => 'オナジ ぶっつうじ'
wanakana.toKana('座禅‘zazen’スタイル')
// => '座禅「ざぜん」スタイル'
wanakana.toKana('batsuge-mu')
// => 'ばつげーむ'

wanakana.toHiragana('toukyou, オオサカ')
// => 'とうきょう、　おおさか'
wanakana.toHiragana('only カナ', { passRomaji: true })
// => 'only かな'
wanakana.toHiragana('wi', { useObsoleteKana: true })
// => 'ゐ'

wanakana.toKatakana('toukyou, おおさか')
// => 'トウキョウ、　オオサカ'
wanakana.toKatakana('only かな', { passRomaji: true })
// => 'only カナ'
wanakana.toKatakana('wi', { useObsoleteKana: true })
// => 'ヰ'

wanakana.toRomaji('ひらがな　カタカナ')
// => 'hiragana katakana'
wanakana.toRomaji('ひらがな　カタカナ', { upcaseKatakana: true })
// => 'hiragana KATAKANA'


/*** EXTRA UTILITIES ***/
wanakana.stripOkurigana('お祝い')
// => 'お祝'
wanakana.stripOkurigana('踏み込む')
// => '踏み込'
wanakana.stripOkurigana('踏み込む', { all: true })
// => '踏込'

wanakana.tokenize('ふふフフ')
// => ['ふふ', 'フフ']
wanakana.tokenize('感じ')
// => ['感', 'じ']
wanakana.tokenize('I said "私は悲しい"')
// => ['I said "','私', 'は', '悲', 'しい', '"']

Important

Only the browser build via unpkg or wanakana/umd/*.js include polyfills for older browsers.

Contributing

Please see CONTRIBUTING.md

Contributors

• Mims H. Wright – Author
• Duncan Bay – Author
• Geggles – Contributor
• James McNamee – Contributor

Credits

Project sponsored by Tofugu & WaniKani

Ports

The following are ports created by the community:

• Java (MasterKale/WanaKanaJava)