DOCSEARCHbyAlgolia
Submit Docs

WanaKana

repository·master·Indexed 21 days ago

https://github.com/wanikani/wanakana

A JavaScript utility library for detecting and transliterating between Kanji, Hiragana, Katakana, and Romaji. It provides tools for converting text, checking Japanese script types, tokenizing strings, and stripping Okurigana. WanaKana can be used in Node.js, ES Modules, or directly in the browser, and includes helpers to bind conversion event listeners to DOM elements.

Tokens
5.3K
Snippets
22
Records
24
Agent score
75%

What's inside wanakana

  1. Import WanaKana in ES Modules or Node.js

    master

    Depending on your environment, import WanaKana using standard ESM or CommonJS syntax.

    ES Modules:

    import * as wanakana from 'wanakana';
// or
import { toKana, isRomaji } from 'wanakana';

    Node.js (>=12 supported):

    const wanakana = require('wanakana');
    import * as wanakana from 'wanakana';

  2. Use WanaKana in the browser without a build step

    master

    To use WanaKana directly in a browser without a bundler, include the UMD bundle via unpkg. This version includes polyfills for older browsers.

    <head>
  <meta charset="UTF-8">
  <script src="https://unpkg.com/wanakana"></script>
</head>
<body>
  <input type="text" id="wanakana-input" />
  <script>
    var textInput = document.getElementById('wanakana-input');
    // Automatically converts text using an eventListener on input
    // Uses IMEMode with toKana() as default
    wanakana.bind(textInput);

    // To remove event listeners:
    // wanakana.unbind(textInput);
  </script>
</body>
    <head>
  <meta charset="UTF-8">
  <script src="https://unpkg.com/wanakana"></script>
</head>
<body>
  <input type="text" id="wanakana-input" />
  <script>
    var textInput = document.getElementById('wanakana-input');
    wanakana.bind(textInput);
  </script>
</body>

  4. IME Mode constants

    master

    The IMEMode option in toKana determines how the conversion handles casing and script enforcement. While the specific constant values are exported via TO_KANA_METHODS, the behavior is:

    • Hiragana enforcement: If IMEMode is set to the Hiragana constant, the output will be Hiragana.
    • Katakana enforcement: If IMEMode is set to the Katakana constant, or if the input substring is entirely uppercase, the output will be Katakana.

  5. Strip Okurigana and Tokenize text

    master

    WanaKana provides advanced utilities for manipulating Japanese text structure:

    • stripOkurigana(text [, options]): Removes Okurigana (kana suffixes) from kanji. Options include leading: true and matchKanji: 'string'.
    • tokenize(text [, options]): Splits text into tokens (e.g., separating kana from kanji or romaji). Option compact: true can be used to group tokens.
    wanakana.stripOkurigana('お祝い'); // => 'お祝'
wanakana.tokenize('ふふフフ'); // => ['ふふ', 'フフ']
wanakana.tokenize('hello 田中さん'); // => ['hello', ' ', '田中', 'さん']

  6. Bind WanaKana to DOM elements

    master

    WanaKana provides helpers to automatically handle text conversion on DOM elements via event listeners.

    • wanakana.bind(domElement [, options]): Automatically converts text using an event listener on input. By default, it sets { IMEMode: true } and uses toKana() as the converter.
    • wanakana.unbind(domElement): Removes the event listener from the specified element.
    wanakana.bind(textInput, /* options */);
wanakana.unbind(textInput);

  7. Check Japanese text types

    master

    Use these utilities to detect the script or language type of a string:

    • isJapanese(text): Returns true if the text contains Japanese characters.
    • isKana(text): Returns true if the text contains Kana (Hiragana or Katakana).
    • isHiragana(text): Returns true if the text is Hiragana.
    • isKatakana(text): Returns true if the text is Katakana.
    • isKanji(text): Returns true if the text is Kanji.
    • isRomaji(text): Returns true if the text is Romaji.
    wanakana.isJapanese('泣き虫。！〜２￥ｚｅｎｋａｋｕ'); // => true
wanakana.isKana('あーア'); // => true
wanakana.isHiragana('すげー'); // => true
wanakana.isKatakana('ゲーム'); // => true
wanakana.isKanji('切腹'); // => true
wanakana.isRomaji('Tōkyō and Ōsaka'); // => true

  8. Transliterate text with WanaKana

    master

    Convert text between Kana, Hiragana, Katakana, and Romaji using the following methods:

    • toKana(text [, options]): Converts text to Kana (Hiragana/Katakana mix). Supports customKanaMapping.
    • toHiragana(text [, options]): Converts text to Hiragana. Options include passRomaji: true and useObsoleteKana: true.
    • toKatakana(text [, options]): Converts text to Katakana. Options include passRomaji: true and useObsoleteKana: true.
    • toRomaji(text [, options]): Converts text to Romaji. Options include upcaseKatakana: true and customRomajiMapping.
    wanakana.toKana('ONAJI buttsuuji'); // => 'オナジ ぶっつうじ'
wanakana.toHiragana('toukyou, オオサカ'); // => 'とうきょう、 おおさか'
wanakana.toKatakana('toukyou, おおさか'); // => 'トウキョウ、 オオサカ'
wanakana.toRomaji('ひらがな　カタカナ'); // => 'hiragana katakana'

  9. Configure toKana options

    master

    You can pass an options object to toKana to control the conversion behavior. Supported keys include:

    • IMEMode: Controls the output script. (See IME Mode constants).
    • useObsoleteKana (Boolean): If true, enables the use of obsolete Kana (e.g., converting 'we' to 'ゑ').
    • customKanaMapping (Object): A dictionary of custom Romaji-to-Kana mappings. For example, { na: 'に', ka: 'bana' } will force those specific sequences to map to the provided values.

    Examples:

    // Using obsolete kana
toKana('we', { useObsoleteKana: true });
// => 'ゑ'

// Using custom mappings
toKana('wanakana', { customKanaMapping: { na: 'に', ka: 'bana' } });
// => 'わにbanaに'

  10. Configure WanaKana conversion options

    master

    WanaKana functions accept an optional DefaultOptions object to customize conversion behavior. These options are merged with the library's defaults.

    Available Options

    OptionTypeDefaultDescription
    useObsoleteKanabooleanfalseSet to true to include obsolete characters like ゐ and ゑ in conversions.
    passRomajibooleanfalseSet to true to leave romaji characters untouched when using toKatakana() or toHiragana() on mixed-script strings.
    convertLongVowelMarkbooleantrueSet to false to prevent the conversion of the katakana prolonged sound mark ー into extended vowels (e.g., in toHiragana()).
    upcaseKatakanabooleanfalseSet to true to convert katakana to uppercase when using toRomaji().
    IMEModeboolean or 'toHiragana' or 'toKatakana'falseEnables handling for conversions while they are being typed (IME input).
    romanization'hepburn''hepburn'Selects the romanization map for toRomaji(). Currently only supports 'hepburn'.
    customKanaMappingRecord<string, string>undefinedA custom mapping object that is merged with the default kana conversion.
    customRomajiMappingRecord<string, string>undefinedA custom mapping object that is merged with the default romaji conversion.
    // Example: Using obsolete kana
toHiragana('we', { useObsoleteKana: true }); // => 'ゑ'

// Example: Passing romaji through
toHiragana('only convert the katakana: ヒラガナ', { passRomaji: true }); // => "only convert the katakana: ひらがな"

// Example: Preventing long vowel conversion
toHiragana('ラーメン', { convertLongVowelMark: false }); // => 'らーめん'

// Example: Uppercasing katakana in romaji
toRomaji('ひらがな カタカナ', { upcaseKatakana: true }); // => "hiragana KATAKANA"

// Example: Custom kana mapping
toKana('wanakana', { customKanaMapping: { na: 'に', ka: 'Bana' } }); // => 'わにBanaに'

// Example: Custom romaji mapping
toRomaji('つじぎり', { customRomajiMapping: { じ: 'zi', つ: 'tu', り: 'li' } }); // => 'tuzigili'

  11. Use custom kana or romaji mappings

    master

    You can extend the default conversion logic by providing customKanaMapping or customRomajiMapping in the options object. These mappings are merged with the library's internal maps, allowing you to override or add specific character/syllable conversions.

    • Use customKanaMapping with toKana, toHiragana, or toKatakana to define how specific romaji strings map to kana.
    • Use customRomajiMapping with toRomaji to define how specific kana strings map to romaji.
    // Custom Kana Mapping
toKana('wanakana', { customKanaMapping: { na: 'に', ka: 'Bana' } }); 
// => 'わにBanaに'

// Custom Romaji Mapping
toRomaji('つじぎり', { customRomajiMapping: { じ: 'zi', つ: 'tu', り: 'li' } }); 
// => 'tuzigili'

  12. Bind and unbind IME event listeners

    master

    Use bind and unbind to attach or remove IME (Input Method Editor) event listeners to DOM elements. These helpers are designed to manage the lifecycle of input events related to Japanese writing systems.

    import { bind, unbind } from 'wanakana';

// Example usage (conceptual):
bind(element, 'input', (event) => {
  // handle IME event
});

unbind(element, 'input');