kuroshiro-enhance

Convert Japanese text precisely.

A JavaScript library that converts Japanese text to Hiragana, Katakana, or Romaji — with furigana, okurigana, Katakana ruby annotations, and structured ruby output for custom renderers.

npm install kuroshiro-enhance Browser & Node.js Kuromoji analyzer

01 · Playground

Try a conversion mode

Edit the Japanese input on the left, tune options, and see the converted output update on the right.

Japanese text

Output

Mode

Include Katakana ruby Applied to furigana and furigana_map only.

Result

Loading dictionary…

02 · Compare

Mode comparison

Same input, five output modes — side by side.

Sample 最後のステージから over and over

03 · Reference

Quick docs

Install the package, initialize an analyzer, then call convert() with the output options from the playground.

Install

Install the package and an analyzer plugin.

npm install kuroshiro-enhance kuroshiro-analyzer-kuromoji

Browser usage

The browser bundle does not include analyzer plugins or dictionary files. Load both bundles and pass a dictionary path.

<script src="https://unpkg.com/kuroshiro-enhance@latest/dist/kuroshiro.min.js"></script>
<script src="https://unpkg.com/[email protected]/dist/kuroshiro-analyzer-kuromoji.min.js"></script>
<script>
  const KuroshiroClass = window.Kuroshiro.default || window.Kuroshiro;
  const kuroshiro = new KuroshiroClass();

  await kuroshiro.init(new KuromojiAnalyzer({ dictPath: "/kuroshiro-enhance/dict/" }));
  const result = await kuroshiro.convert("漢字とカタカナ", {
    to: "hiragana",
    mode: "furigana",
    includeKatakana: true
  });
</script>

Node.js usage

import Kuroshiro from "kuroshiro-enhance";
import KuromojiAnalyzer from "kuroshiro-analyzer-kuromoji";

const kuroshiro = new Kuroshiro();
await kuroshiro.init(new KuromojiAnalyzer());

const result = await kuroshiro.convert("漢字とカタカナ", {
  to: "hiragana",
  mode: "furigana_map",
  includeKatakana: true
});

API options

Option	Default	Values	Description
`to`	`"hiragana"`	`"hiragana"`, `"katakana"`, `"romaji"`	Target syllabary or romanization output.
`mode`	`"normal"`	`"normal"`, `"spaced"`, `"okurigana"`, `"furigana"`, `"furigana_map"`	Controls whether the result is plain text, annotated text, ruby HTML, or structured ruby spans.
`includeKatakana`	`false`	`true`, `false`	Adds ruby annotations to Katakana segments in `furigana` and `furigana_map` modes.
`romajiSystem`	`"hepburn"`	`"hepburn"`, `"nippon"`, `"passport"`	Romanization system used when `to` is `"romaji"`.

Structured ruby output

includeKatakana is useful when Katakana loanwords or names should also receive ruby. furigana_map returns structured spans for custom rendering instead of browser ruby HTML.

{
  "text": "漢字とカタカナ",
  "ruby": [
    { "s": 0, "e": 2, "rt": "かんじ" },
    { "s": 3, "e": 7, "rt": "かたかな" }
  ]
}

Browser dictionary files

Browser usage needs Kuromoji dictionary files in addition to the script bundles. For this GitHub Pages demo, those files live in docs/dict/ and are served from /kuroshiro-enhance/dict/.

kuroshiro.min.js
kuroshiro-analyzer-kuromoji.min.js
dict/*.dat.gz