kuroshiro

When converting to Romaji (to: 'romaji'), you can specify the romajiSystem option. Supported systems are:

• nippon: Nippon-shiki system (ISO 3602 Strict).
• passport: Passport-shiki system (Japanese Ministry of Foreign Affairs).
• hepburn: Hepburn system (BS 4812 : 1972).

Note: Converting from Kana to Romaji cannot perfectly handle long vowels (chōon) because Kana lacks complete pronunciation information, though Chōonpu is always converted.

When converting to romaji, you can specify the following systems via the romajiSystem option:

• nippon: Nippon-shiki (Japanese style) [ISO 3602 Strict].
• passport: Passport style (based on the Ministry of Foreign Affairs' Hepburn-based spelling).
• hepburn: Hepburn style [BS 4812 : 1972].

Note on Furigana to Romaji: Because furigana does not always represent exact phonetic values, kuroshiro does not perform long vowel processing when converting directly from kana (furigana) to romaji. For example, using nippon, passport, or hepburn on kana might result in "kousi", "koushi", or "koushi" respectively. However, Kanji-to-Romaji conversion is unaffected by this limitation.

kuroshiro is a Japanese language library that converts Japanese sentences into Hiragana, Katakana, or Romaji. It does not include a morphological analyzer by default. Instead, it uses a plugin-based architecture where you must provide an analyzer instance during initialization.

Workflow:

1. Instantiate Kuroshiro.
2. Initialize it using kuroshiro.init(analyzer) with an instance of a morphological analyzer plugin.
3. Use kuroshiro.convert(str, options) to perform conversions.

Available Ready-made Analyzers:

When converting to Romaji (to: 'romaji'), you can specify the romajiSystem option. Supported systems are:

• nippon: Japanese style (ISO 3602 Strict).
• passport: Passport style (Japanese Ministry of Foreign Affairs).
• hepburn: Hepburn style (BS 4812 : 1972).

Important Note on Direct Kana-to-Romaji Conversion Directly converting Kana to Romaji (without Kanji analysis) does not handle long vowels (chōon) correctly because Kana lacks explicit pronunciation information. For example, converting こうし might result in kousi, koushi, or koushi depending on the system. However, Kanji-to-Romaji conversion is NOT affected by this limitation and will handle long vowels correctly via the analyzer.

When using { to: "romaji" }, you can specify the romajiSystem option. Supported systems are:

• nippon: Nippon-shiki romanization (ISO 3602 Strict).
• passport: Passport-shiki romanization (Ministry of Foreign Affairs of Japan).
• hepburn: Hepburn romanization (BS 4812 : 1972).

Important Note on Furigana to Romaji: Directly converting furigana (kana) to romaji is limited because furigana lacks pronunciation information for long vowels (chōon). Consequently, kuroshiro may not handle chōon correctly when converting directly from kana to romaji (except for the Chōonpu character itself). However, Kanji-to-Romaji conversion is unaffected by this limitation.

Before converting text, you must initialize the Kuroshiro instance with an analyzer plugin (e.g., kuroshiro-analyzer-kuromoji). This process is asynchronous and uses async/await or Promises.

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

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

To use kuroshiro in a frontend project, include the minified scripts in your HTML. You must include both the kuroshiro library and an analyzer library.

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

<script>
  var kuroshiro = new Kuroshiro();
  kuroshiro.init(new KuromojiAnalyzer({ dictPath: "url/to/dictFiles" }))
    .then(function () {
      return kuroshiro.convert("感じ取れたら", { to: "hiragana" });
    })
    .then(function (result) {
      console.log(result);
    });
</script>

Note: When using Kuromoji in the browser, you must provide a dictPath to the KuromojiAnalyzer constructor to locate the dictionary files.

Depending on your project setup, you can use either ES6 Modules or CommonJS.

ES6 Module Example:

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

const kuroshiro = new Kuroshiro();
await kuroshiro.init(new KuromojiAnalyzer());
const result = await kuroshiro.convert("感じ取れたら手を繋ごう", { to: "hiragana" });

CommonJS Example:

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

kuroshiro.init(new KuromojiAnalyzer())
    .then(() => kuroshiro.convert("感じ取れたら手を繋ごう", { to: "hiragana" }))
    .then(result => console.log(result));

To use kuroshiro in a browser environment:

1. Include dist/kuroshiro.min.js in your project (build it via npm run build first).
2. Include the minified version of your chosen analyzer (e.g., kuroshiro-analyzer-kuromoji.min.js).
3. Instantiate Kuroshiro and initialize it using .init() with the analyzer instance. For analyzers like Kuromoji, you may need to provide a dictPath.

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

<script>
  var kuroshiro = new Kuroshiro();
  kuroshiro.init(new KuromojiAnalyzer({ dictPath: "url/to/dictFiles" }))
    .then(function () {
        return kuroshiro.convert("感じ取れたら", { to: "hiragana" });
    })
    .then(function(result){
        console.log(result);
    });
</script>

To use kuroshiro in Node.js, you need to install the main library and an analyzer plugin (e.g., kuroshiro-analyzer-kuromoji).

1. Install dependencies:

   npm install kuroshiro kuroshiro-analyzer-kuromoji

2. Import and Initialize: Import Kuroshiro and your chosen analyzer, then initialize the instance using await kuroshiro.init(new Analyzer()).
3. Convert text: Use await kuroshiro.convert(text, options) to perform the conversion.

Note: The library supports both ES6 Modules (import) and CommonJS (require).

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

const kuroshiro = new Kuroshiro();

// Initialize with an analyzer
await kuroshiro.init(new KuromojiAnalyzer());

// Perform conversion
const result = await kuroshiro.convert("感じ取れたら手を繋ごう", { to: "hiragana" });

To use kuroshiro in a Node.js environment or with a module bundler like Webpack, install the package using npm:

$ npm install kuroshiro

Note that you will also need to install an analyzer plugin (e.g., kuroshiro-analyzer-kuromoji) to perform morphological analysis.

When calling convert(), you can specify how the output is formatted using the to and mode parameters.

Target Syllabaries (to):

• hiragana (default)
• katakana
• romaji

Conversion Modes (mode):

• normal: Returns a single continuous string.
• spaced: Returns a string with spaces between converted tokens.
• okurigana: Returns the text with readings appended to specific parts (like Kanji) using delimiter_start and delimiter_end (e.g., 漢字(かんじ)).
• furigana: Returns HTML <ruby> markup for browser rendering (e.g., <ruby>漢字<rp>(</rp><rt>かんじ</rt><rp>)</rp></ruby>).