kuroshiro is a Japanese language library for converting Japanese sentence to Hiragana, Katakana or Romaji with furigana and okurigana modes supported.

Read this in other languages: English, 日本語, 简体中文, 繁體中文, Esperanto, 한국어.

You can check the demo here.

• Japanese Sentence => Hiragana, Katakana or Romaji
• Furigana and okurigana supported
• 🆕Multiple morphological analyzers supported
• 🆕Multiple romanization systems supported
• Useful Japanese utils

• Version 2 requires Node.js 22+ or a browser with native ES2015 support, including Promises. Internet Explorer is not supported. Check the analyzer's additional requirements separately.
• Replace Kuroshiro.Util.kanaToHiragna(...) with Kuroshiro.Util.kanaToHiragana(...); the old spelling has been removed.
• CommonJS require, ESM default imports, the Kuroshiro browser global, and the asynchronous init() / convert() API remain supported.
• TypeScript declarations are included. The examples below use the Kuromoji 2.0 beta, which also includes declarations.

You should check the environment compatibility of each analyzer before you start working with them

The Yahoo Web API analyzer's API migration is incomplete and maintenance is paused. It is not recommended for new projects. See its maintenance status.

Install with npm package manager:

$ npm install kuroshiro@beta kuroshiro-analyzer-kuromoji@beta

Load the library:

Support ES6 Module import

import Kuroshiro from "kuroshiro";
// Initialize kuroshiro with an instance of analyzer (You could check the [apidoc](#initanalyzer) for more information):
// For this example, you should npm install and import the kuromoji analyzer first
import KuromojiAnalyzer from "kuroshiro-analyzer-kuromoji";
// Instantiate
const kuroshiro = new Kuroshiro();
// Initialize
// Here uses async/await, you could also use Promise
await kuroshiro.init(new KuromojiAnalyzer());
// Convert what you want
const result = await kuroshiro.convert("感じ取れたら手を繋ごう、重なるのは人生のライン and レミリア最高！", { to: "hiragana" });

And CommonJS require

const Kuroshiro = require("kuroshiro");
const KuromojiAnalyzer = require("kuroshiro-analyzer-kuromoji");
const kuroshiro = new Kuroshiro();

kuroshiro.init(new KuromojiAnalyzer())
    .then(function(){
        return kuroshiro.convert("感じ取れたら手を繋ごう、重なるのは人生のライン and レミリア最高！", { to: "hiragana" });
    })
    .then(function(result){
        console.log(result);
    })

Use dist/kuroshiro.min.js from the installed npm package in your frontend project, and include it in your HTML:

<script src="url/to/kuroshiro.min.js"></script>

For this example, you should also include kuroshiro-analyzer-kuromoji.min.js which you could get from kuroshiro-analyzer-kuromoji

<script src="url/to/kuroshiro-analyzer-kuromoji.min.js"></script>

Instantiate:

var kuroshiro = new Kuroshiro();

Copy the dictionary files from node_modules/kuromoji/dict/ to a public directory such as public/dict/. Set dictPath to their URL (/dict/ in this example); see the browser dictionary guide.

Initialize kuroshiro with an instance of analyzer, then convert what you want:

kuroshiro.init(new KuromojiAnalyzer({ dictPath: "/dict/" }))
    .then(function () {
        return kuroshiro.convert("感じ取れたら手を繋ごう、重なるのは人生のライン and レミリア最高！", { to: "hiragana" });
    })
    .then(function(result){
        console.log(result);
    })
    .catch(function (error) {
        console.error(error);
    });

Version 2 includes declarations for the package entry, custom analyzers, conversion options, and the static Kuroshiro.Util helpers. The Kuromoji 2.0 beta also includes declarations, so no separate @types package is needed for either library.

import Kuroshiro from "kuroshiro";

const options: Kuroshiro.ConvertOptions = { to: "romaji", romajiSystem: "hepburn" };
const hiragana: string = Kuroshiro.Util.kanaToHiragana("カナ");

For TypeScript compiled to CommonJS, enable esModuleInterop for default imports, or use import Kuroshiro = require("kuroshiro"). Native Node ESM and bundler module resolution also support the default import. Non-module browser scripts can use /// <reference types="kuroshiro" /> for the Kuroshiro global; the actual UMD script must still be loaded in the page.

Examples

const kuroshiro = new Kuroshiro();

Initialize kuroshiro with an instance of analyzer. You should first import an analyzer and initialize it. You can make use of the Ready-made Analyzers listed above. And please refer to documentation of analyzers for analyzer initialization instructions

Arguments

• analyzer - An instance of analyzer.

Examples

await kuroshiro.init(new KuromojiAnalyzer());

Convert given string to target syllabary with options available

Arguments

• str - A String to be converted.
• options - Optional kuroshiro has several convert options as below.

*: Param romajiSystem is only applied when the value of param to is romaji. For more about it, check Romanization System

Examples

// normal
await kuroshiro.convert("感じ取れたら手を繋ごう、重なるのは人生のライン and レミリア最高！", {mode:"normal", to:"hiragana"});
// result：かんじとれたらてをつなごう、かさなるのはじんせいのライン and レミリアさいこう！

// spaced
await kuroshiro.convert("感じ取れたら手を繋ごう、重なるのは人生のライン and レミリア最高！", {mode:"spaced", to:"hiragana"});
// result：かんじとれ たら て を つなごう 、 かさなる の は じんせい の ライン   and   レミ リア さいこう ！

// okurigana
await kuroshiro.convert("感じ取れたら手を繋ごう、重なるのは人生のライン and レミリア最高！", {mode:"okurigana", to:"hiragana"});
// result: 感(かん)じ取(と)れたら手(て)を繋(つな)ごう、重(かさ)なるのは人生(じんせい)のライン and レミリア最高(さいこう)！

// furigana
await kuroshiro.convert("感じ取れたら手を繋ごう、重なるのは人生のライン and レミリア最高！", {mode:"furigana", to:"hiragana"});
// result: 感(かん)じ取(と)れたら手(て)を繋(つな)ごう、重(かさ)なるのは人生(じんせい)のライン and レミリア最高(さいこう)！

Examples

const result = Kuroshiro.Util.isHiragana("あ");

Check if input char is hiragana.

Check if input char is katakana.

Check if input char is kana.

Check if input char is kanji.

Check if input char is Japanese.

Check if input string has hiragana.

Check if input string has katakana.

Check if input string has kana.

Check if input string has kanji.

Check if input string has Japanese.

Convert input kana string to hiragana.

In 2.x, this replaces the misspelled 1.x method kanaToHiragna. Update existing calls to Kuroshiro.Util.kanaToHiragana(...); the old name is no longer exported. This is a breaking API change.

Convert input kana string to katakana.

Convert input kana string to romaji. Param system accepts "nippon", "passport", "hepburn" (Default: "hepburn").

kuroshiro supports three kinds of romanization systems.

nippon: Nippon-shiki romanization. Refer to ISO 3602 Strict.

passport: Passport-shiki romanization. Refer to Japanese romanization table published by Ministry of Foreign Affairs of Japan.

hepburn: Hepburn romanization. Refer to BS 4812 : 1972.

There is a useful webpage for you to check the difference between these romanization systems.

Furigana (kana spelling) does not always provide enough pronunciation information to distinguish long vowels, so converting it directly to romaji cannot reliably reproduce pronunciation. See なぜ フリガナでは ダメなのか？ for more background.

For this reason, kanaToRomaji() does not infer long vowels from kana spelling in any of the three romanization systems. The long vowel mark ー (chōonpu) is still handled according to the selected system.

For example, converting こうし with kanaToRomaji() produces kousi, koushi, and koushi in nippon, passport, and hepburn, respectively.

This limitation of direct kana conversion does not prevent convert() from handling long vowels: it uses pronunciation information from the analyzer when available, including when converting kanji with or without annotations. The result therefore depends on the pronunciation information provided by the analyzer.

When no following consonant can be doubled, all three systems use ', e.g. っい → 'i, あっ → a'. This is kuroshiro's convention, not an extra spoken syllable.

Please check CONTRIBUTING.

• kuromoji
• wanakana

MIT