kuroshiro-enhance

Convert Japanese text precisely.

An enhanced fork of kuroshiro — 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, furigana_segments 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/kuroshiro-analyzer-kuromoji@1.1.0/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: "/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_segments",
  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_segments"`, `"furigana_map"` (deprecated)	Controls whether the result is plain text, annotated text, ruby HTML, or a structured segment array. `furigana_map` is deprecated — use `furigana_segments` instead.
`includeKatakana`	`false`	`true`, `false`	Adds ruby annotations to Katakana segments in `furigana`, `furigana_segments` 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_segments returns a flat segment array for custom rendering instead of browser ruby HTML — each segment is a slice of the input, with a ruby reading only where one applies.

[
  { "text": "漢字", "ruby": "かんじ" },
  { "text": "と" },
  { "text": "カ", "ruby": "か" },
  { "text": "タ", "ruby": "た" },
  { "text": "カ", "ruby": "か" },
  { "text": "ナ", "ruby": "な" }
]

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