Registry / serialization / wanakana

wanakana

JSON →
library1.0.1jsnpmunverified

WanaKana is a JavaScript utility library designed for detecting and transliterating Japanese text between Hiragana, Katakana, Romaji, and handling Kanji. It provides a comprehensive set of functions for checking the type of script (e.g., `isJapanese`, `isKana`, `isRomaji`), converting between them (e.g., `toKana`, `toHiragana`, `toRomaji`), and includes DOM helpers for real-time input conversion (`bind`, `unbind`). The library is currently at version 5.3.1 and maintains an active release cadence, with minor updates and bug fixes occurring every few months. Its key differentiators include robust input method editor (IME) simulation capabilities for HTML text fields, comprehensive handling of various kana and romaji mapping rules, and support for custom mappings. WanaKana ships with TypeScript definitions, making it highly compatible with modern TypeScript-driven web development workflows.

npm install wanakana
INSTALL
IMPORT
SIG · WANAKANA
W
wanakana
serializationjavascriptv1.0.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

wanakana
import * as wanakana from 'wanakana';
import wanakana from 'wanakana';
The library primarily uses named exports. A default import (`import wanakana from 'wanakana'`) will not provide all utility functions.
toKana, isRomaji
import { toKana, isRomaji } from 'wanakana';
const { toKana, isRomaji } = require('wanakana');
Prefer named ESM imports for modern JavaScript environments. CommonJS `require` works but is discouraged for new projects.
bind, unbind
import { bind, unbind } from 'wanakana';
wanakana.bind(element); // If wanakana was not imported correctly
These DOM helper functions are available as named exports. Ensure `wanakana` is properly imported before attempting to use them.
Wanakana (global)
<script src="https://unpkg.com/wanakana"></script> <script>wanakana.toKana('...');</script>
For browser usage without a build step, WanaKana exposes a global `wanakana` object after loading the UMD bundle from unpkg or similar CDN.

This quickstart demonstrates basic Romaji to Hiragana/Katakana conversion, checks for Japanese text, and illustrates how to bind WanaKana to a DOM input element for real-time conversion.

import { toKana, toHiragana, toRomaji, isJapanese, bind, unbind } from 'wanakana'; // Convert Romaji to Hiragana and Katakana const romajiInput = 'konnichiwa sekai'; const hiragana = toHiragana(romajiInput); // 'こんにちわせかい' const katakana = toKatakana(romajiInput); // 'コンニチワセカイ' console.log(`Romaji: "${romajiInput}"`); console.log(` -> Hiragana: "${hiragana}"`); console.log(` -> Katakana: "${katakana}"`); // Check if a string contains Japanese characters const japaneseText = '日本語を勉強します'; const containsJapanese = isJapanese(japaneseText); // true console.log(`"${japaneseText}" contains Japanese: ${containsJapanese}`); // Demonstrating DOM binding (browser environment required) // This part will only execute if 'document' is defined. if (typeof document !== 'undefined') { const inputElement = document.createElement('input'); inputElement.type = 'text'; inputElement.id = 'wanakana-demo-input'; document.body.appendChild(inputElement); console.log('Appended a demo input element to the document body.'); // Bind wanakana for real-time Romaji to Kana conversion bind(inputElement, { IMEMode: true }); console.log('WanaKana is bound to the input element. Type romaji to convert to kana.'); // Simulate user input (programmatically) inputElement.value = 'nihongo'; inputElement.dispatchEvent(new Event('input', { bubbles: true })); // In a real browser, inputElement.value would now be 'にほんご' // For console, we'll log what it *should* be: console.log(`Simulated input 'nihongo'. Expected input value after conversion: 'にほんご'. Current value (may not reflect live conversion in Node): ${inputElement.value}`); // Clean up unbind(inputElement); document.body.removeChild(inputElement); console.log('WanaKana unbound and input element removed.'); } else { console.log('Skipping DOM binding example as `document` is not defined (likely a Node.js environment).'); }
Debug
Known issues
breakingThe `stripOkurigana()` function's options were changed significantly in v4.0.0. The `{ all: Boolean }` option was removed and replaced with `{ leading: Boolean, matchKanji: String }`.
fix
Review calls to `stripOkurigana()` and update options according to the new API. For example, to strip all kana, use `[...text].filter(isKana)` manually.
affects: >=4.0.0
breakingIn v5.2.0, the `々` (iteration mark) character was reclassified. It is now included in `isKanji()` checks and explicitly excluded from Japanese punctuation checks.
fix
Update any logic that relies on the previous classification of `々`, especially in custom character type detection or processing pipelines.
affects: >=5.2.0
gotchaStarting from v5.0.0, providing `customKanaMapping` or `customRomajiMapping` in conversion options will always replace any existing custom mapping if different. Previously, it would only replace if no custom mapping was already set.
fix
Ensure that your application explicitly manages custom mapping states, passing the desired mapping every time if it might change, rather than relying on a potentially stale or implicitly set mapping.
affects: >=5.0.0
gotchaIn v5.1.0, `bind()` was fixed to prevent binding the same element multiple times, and `unbind()` now removes only the attributes that were specifically added by WanaKana. This might affect applications that relied on `unbind()` leaving certain attributes or allowed multiple `bind()` calls on the same element.
fix
Ensure `bind()` is called only once per element. If you need to re-bind with new options, `unbind()` first. Review applications for any dependencies on attributes `unbind()` might have previously left untouched.
affects: >=5.1.0
Errors
Common errors & fixes
TypeError: wanakana.toKana is not a function
Attempting to call `toKana` on a `wanakana` object that was imported incorrectly, often via `import wanakana from 'wanakana'` instead of `import * as wanakana from 'wanakana'` or named imports.
fix
Use `import { toKana } from 'wanakana';` for specific functions or `import * as wanakana from 'wanakana';` to import all named exports under a namespace.
ReferenceError: wanakana is not defined
The `wanakana` global object is not available, typically because the UMD bundle was not loaded in a browser environment, or the library was not correctly imported in a module environment.
fix
For browser use without a bundler, ensure `<script src="https://unpkg.com/wanakana"></script>` is in your HTML. For module environments, ensure you have `import * as wanakana from 'wanakana';` or appropriate named imports.
TypeError: Cannot read properties of undefined (reading 'bind')
This usually occurs when `wanakana.bind()` is called with an `undefined` or null DOM element, or when `wanakana` itself is not properly imported/defined, leading to `wanakana` being `undefined`.
fix
Verify that the DOM element you are passing to `bind()` actually exists and is not `null` or `undefined`. Also, confirm that `wanakana` has been correctly imported and is accessible in the current scope.
Upgrade
Version history
1.0.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
17 hits · last 30 days
node
12
OpenAI (training)
1
Resources