Cutlet

0.5.0 verified Fri May 01 auth: no python

Japanese to romaji converter using fugashi and kakasi. Current version 0.5.0 (May 2025). Low/medium release cadence; pre-1.0 API cleanup expected.

pip install cutlet

Common errors

error ImportError: cannot import name 'Cutlet' from 'cutlet' ↓

cause Using wrong import syntax (e.g., from cutlet import cutlet).

fix

Use: from cutlet import Cutlet

error ModuleNotFoundError: No module named 'fugashi' ↓

cause Missing transitive dependency. cutlet requires fugashi.

fix

pip install fugashi (or use a dict like pip install cutlet[fugashi] if available)

error RuntimeError: Please install a dictionary for fugashi (e.g., pip install unidic-lite) ↓

cause Fugashi requires a dictionary to be installed separately.

fix

pip install unidic-lite

Warnings

breaking v0.5.0 changed behavior: whitespace in ASCII strings is now preserved instead of being subject to the same rules as Japanese text. Output may differ from v0.4.0. ↓

fix If you relied on whitespace being modified, adjust logic to handle ASCII whitespace separately.

gotcha Particles like は are romanized as 'ha' (not 'wa') and へ as 'he' (not 'e'). This is technically correct but may be unexpected for learners. ↓

fix Use hepburn=False or override via manual post-processing if Hepburn-style romanization is desired.

gotcha Unknown characters (non-Japanese, non-ASCII) are converted to '?' by default. This can silently corrupt text. ↓

fix Set the 'unknown' argument to a different placeholder or handle missing chars manually.

gotcha The Cutlet class is stateful; do not reuse the same instance across threads without synchronization. ↓

fix Instantiate a new Cutlet object per thread.

Imports

Cutlet
```
from cutlet import Cutlet
```

Quickstart

Basic romaji conversion. Note: particles like は are romanized as 'ha' not 'wa'.

from cutlet import Cutlet

katsu = Cutlet()
print(katsu.romaji('私は猫です'))
# 'watashi ha neko desu'