pykakasi

Warnings

• deprecated The old API methods (`setMode()`, `getConverter()`, `do()`, and the `wakati` class) are deprecated in pykakasi v2.1.0 and will be removed entirely in v3.0. Migrate to the `kakasi().convert()` method for future compatibility.
  Fix: Rewrite code using `kakasi().convert(text)` for conversion. For custom options, `kakasi` can be configured before calling `convert` or by passing a dictionary of options to its constructor (refer to official docs for full options).
• gotcha pykakasi is distributed under the GNU General Public License v3.0 or later (GPLv3+). This license has implications for commercial use, potentially requiring source code disclosure if the library is incorporated into proprietary software.
  Fix: Review your project's licensing requirements. If GPLv3+ is incompatible, consider alternative Japanese romanization libraries with more permissive licenses (e.g., MIT or BSD).
• gotcha The library primarily expects Unicode characters in Normalization Form C (NFC). Using text in Normalization Form D (NFD) might lead to incorrect or unexpected conversion results due to separated diacritics.
  Fix: Ensure input text is normalized to NFC before processing with pykakasi, e.g., using `unicodedata.normalize('NFC', text)`.
• gotcha The original GitHub repository (miurahr/pykakasi) was archived in July 2022 and now points to Codeberg. Users looking for the official source or contributing should refer to the Codeberg repository.
  Fix: Use `https://codeberg.org/miurahr/pykakasi` as the primary source for the project, documentation, and issue tracking.
• gotcha According to some analyses (e.g., Snyk report mentioned in a blog post), the project's maintenance status has been rated as 'Inactive,' despite its continued widespread usage. This might indicate slower response times for issues or new feature development.
  Fix: Be aware of the potential for slower maintenance. For mission-critical applications requiring active development or immediate support, evaluate the project's current activity or consider alternatives.

Install

• pip install pykakasi Install from PyPI

Imports

• kakasi

  from pykakasi import kakasi

  The `setMode()`, `getConverter()`, and `do()` methods (old API) are deprecated and will be removed in v3.0. Use the `kakasi().convert()` method for modern usage.

Quickstart

Initializes the kakasi converter and demonstrates both the deprecated (v1.x) and the recommended (v2.x) API for converting Japanese text into romaji, hiragana, and katakana. The new API offers a more streamlined `convert()` method.

import pykakasi

kks = pykakasi.kakasi()
text = "かな漢字交じり文"

# Configure conversion modes (optional, defaults to Hepburn romaji, no spaces)
kks.setMode('H', 'a') # Hiragana to romaji
kks.setMode('K', 'a') # Katakana to romaji
kks.setMode('J', 'a') # Kanji to romaji
kks.setMode('r', 'Hepburn') # Use Hepburn Romanization
kks.setMode('s', True) # Add spaces
kks.setMode('C', True) # Capitalize

converter = kks.getConverter()
result_old_api = converter.do(text)
print(f"Old API result: {result_old_api}")

# Recommended new API (v2.0.0+)
result_new_api = pykakasi.kakasi().convert(text)
print("\nNew API result (default modes):")
for item in result_new_api:
    print(f"Original: {item['orig']}, Kana: {item['kana']}, Hiragana: {item['hira']}, Romaji: {item['hepburn']}")