jpnorm

日本語テキストの「表記ゆれ」を、用途に合わせて 1 行で吸収するライブラリ。 Rust 製コアを Python から使います。neologdn の置き換えから、検索前処理、LLM 出力の評価、 名寄せまで、プリセットを選ぶだけで始められ、必要ならフラグ単位で細かく調整できます。

Fast, configurable Japanese text normalization. Rust core with Python bindings. Pick a preset (neologdn_compat, for_search, for_compare, for_display) or tune 37 flags; unifies old/variant kanji (國→国, 髙→高), katakana loanword spellings (ヴァ→バ, trailing ー), iteration marks (人々→人人), era years (令和6年→2024年); protects URLs / emails / mentions, handles emoji, converts kanji numerals, applies custom synonym dictionaries. 3 to 5 times faster than neologdn.

import jpnorm

jpnorm.normalize("ﾊﾝｶｸｶﾅ　と  全角  ！！")
# => 'ハンカクカナ と 全角 !!'

ブラウザで試す → https://yoshitakaoyama.github.io/jpnorm/ (テキストを貼ると全プリセットの結果が並びます)

こんなときに使います

日本語には「同じ意味なのに文字列としては別物」になる書き方が大量にあります。 半角カナと全角カナ、全角英数と半角英数、ー と 〜 と -、㈱ と (株)、 三百二十円 と 320円、コンピューター と コンピュータ、ヴァイオリン と バイオリン、 渡邊 と 渡辺、髙橋 と 高橋、人々 と 人人、令和6年 と 2024年、幽☆遊☆白書 と 幽白……。 これらを放置すると、次のような問題が起きます。

インストール

pip install jpnorm
# または
uv add jpnorm

Python 3.10 以上。Linux (x86_64 / aarch64)・macOS (x86_64 / arm64)・Windows (x64) の wheel を配布しているので、Rust ツールチェーンは不要です。 コマンドラインだけ使いたい場合は pipx install jpnorm で jpnorm コマンドが入ります。

ユースケース別ガイド

1. 検索・RAG の前処理 (for_search)

索引を作るときと検索するときの両方で同じ Normalizer を通します。 URL やメールアドレスは壊さず、絵文字は落とし、記号のバリエーションを揃えます。

from jpnorm import Normalizer

n = Normalizer("for_search")

docs = ["ＰＹＴＨＯＮ入門 〜〜 初心者向け🔰", "python 入門（初心者向け）"]
n.normalize_batch(docs)
# => ['python入門 〜 初心者向け', 'python 入門(初心者向け)']

n.normalize("詳細は https://example.com/Docs?Q=1 を参照 📎")
# => '詳細は https://example.com/Docs?Q=1 を参照'   ← URL はそのまま

検索でヒット落ちの原因になりやすい「同じ語の別表記」も、辞書なしで同じ形に落とします。

n.normalize("コンピューター")      # => 'コンピュータ'   ← 末尾長音 (JIS Z 8301 方式)
n.normalize("ヴァイオリン")        # => 'バイオリン'
n.normalize("ウェブサーバー")      # => 'ウエブサーバ'
n.normalize("渡邊さんと髙橋さん")  # => '渡辺さんと高橋さん'   ← 旧字体・異体字
n.normalize("人々の舊字體")        # => '人人の旧字体'   ← 繰り返し記号・旧字体
n.normalize("令和6年度予算")       # => '2024年度予算'   ← 元号

英字は小文字に揃えます (case="keep" で無効化)。日本語と英数字の間の空白は残します (cjk_spacing="remove" で削除)。

2. LLM / OCR / 音声認識の出力評価 (for_compare + compare)

「正解データと実質同じか」を判定したい場面です。全角半角・記号・漢数字・空白の違いを すべて潰した上で、完全一致・前方一致・編集距離・LLM judge のいずれかで比較します。

from jpnorm import Normalizer, compare

n = Normalizer("for_compare")

n.normalize("合計：￥１，２００（税込）")    # => '合計¥1200税込'
n.normalize("合計:¥1,200(税込)")            # => '合計¥1200税込'   ← 同じ形になる
n.normalize("第一章　はじめに")             # => '第1章はじめに'
n.normalize("売上 1万2千円 (令和六年)")      # => '売上12000円2024年'

compare("ﾃｽﾄ結果：１２３", "テスト結果:123", strategy="exact", normalizer=n).matched
# => True

r = compare("東京都渋谷区", "東京都渋谷区神南1-2-3", strategy="prefix", normalizer=n)
r.matched, r.detail["direction"]
# => (True, 'prediction_is_prefix_of_reference')

r = compare("kitten", "sitting", strategy="edit_distance", threshold=0.5)
r.score   # => 0.571...  (1 - 編集距離 / 長さ)

意味的な一致まで見たい場合は LLM judge が使えます (pip install "jpnorm[anthropic]" または [openai])。

compare(
    "東京タワーの高さは333メートルです",
    "東京タワーは高さ 333m",
    strategy="llm_judge",
    llm_provider="anthropic",        # or "openai"
    llm_model="claude-haiku-4-5",
    threshold=0.8,
)

judge_fn= に自前の判定関数を渡せば API を呼ばずにテストできます。 API キーは ANTHROPIC_API_KEY / OPENAI_API_KEY から読みます。

3. 名寄せ・重複検出 (for_compare + カスタム辞書)

自社サービス名・作品名・人名など、辞書にしか載っていない表記ゆれは カスタム辞書で正規形に寄せます。辞書は正規化の最終段で最長一致置換されます。 キーは生の表記のまま書いて構いません (同じ設定で正規化してから照合されます)。

n = Normalizer("for_compare").with_custom_dict({
    "幽遊白書": ["幽白", "ゆうはく", "幽☆遊☆白書"],
    "株式会社サンプル": ["サンプル社", "(株)サンプル", "㈱サンプル"],
})

n.normalize("㈱サンプル")            # => '株式会社サンプル'
n.normalize("幽☆遊☆白書 第１巻")     # => '幽遊白書第1巻'
n.normalize("渡邊 太郎")             # => '渡辺太郎'   ← 異体字は辞書なしで統一される

# 重複検出はキーを揃えるだけ
records = ["㈱サンプル", "サンプル社", "株式会社サンプル"]
len({n.normalize(r) for r in records})   # => 1

辞書はファイルからも読めます (拡張子で形式判定、format= で明示も可)。

n = (
    Normalizer("for_compare")
    .load_custom_dict_file("brands.json")   # {"正規形": ["表記ゆれ", ...]}
    .load_custom_dict_file("terms.csv")     # 表記ゆれ,正規形
    .load_custom_dict_file("terms.tsv")     # 表記ゆれ<TAB>正規形
)
n.custom_dict_size      # 登録エントリ数
n.clear_custom_dict()

一般語の同義語は SudachiDict の synonyms.txt (Apache-2.0) をそのまま読み込めます。ライブラリにはバンドルしていないので 必要な場合はダウンロードしてください。

curl -fSL -o synonyms.txt https://raw.githubusercontent.com/WorksApplications/SudachiDict/develop/src/main/text/synonyms.txt

n = Normalizer("for_search").load_sudachi_synonyms("synonyms.txt")
n.normalize("パソコンを買った")   # => 'パーソナルコンピュータを買った'

4. ユーザー投稿の表示前クリーンアップ (for_display)

「見た目を壊さない」が原則です。半角カナだけは全角にし、絵文字・全角記号・空白は残します。

n = Normalizer("for_display")
n.normalize("ﾊﾝｶｸｶﾅ ＋ 全角 🗼")   # => 'ハンカクカナ ＋ 全角 🗼'

保存前のサニタイズ (ゼロ幅文字・制御文字・Bidi 制御文字の除去、改行コード統一) を 足したい場合はフラグを重ねます。Bidi 制御文字の除去は Trojan Source 対策にもなります。

n = Normalizer(
    "for_display",
    remove_zero_width=True,
    remove_control=True,
    remove_bidi_control=True,
    normalize_newlines=True,
)
n.normalize("ゼロ幅\u200b文字と\u202e制御\r\n改行")   # => 'ゼロ幅文字と制御\n改行'

5. neologdn からの移行 (neologdn_compat)

引数なしの jpnorm.normalize() がこれです。半角カナ→全角、全角英数→半角、 長音符の畳み込み、空白の畳み込みなど neologdn と同等の処理を Rust で行います。

import jpnorm

jpnorm.normalize("ﾊﾝｶｸ ﾄ 全角 ＡＢＣ")   # => 'ハンカク ト 全角 ABC'
jpnorm.normalize("あ〜〜〜")              # => 'あ〜'

neologdn と意図的に違う点は次のとおりです (ゴールデンテストで管理しています)。

• 日本語に隣接する空白を neologdn は削除しますが、jpnorm は 1 つに畳むだけで残します (== 概要 == は neologdn では ==概要==)。削除したい場合は cjk_spacing="remove"
• 〜 ~ を neologdn は削除しますが、jpnorm は 〜 に統一して残します
• ‘’ “” ¥ を neologdn は独自変換しますが、jpnorm は既定では触りません (unify_quotes=True で統一可)
• jpnorm は NFKC を掛けるので、℃ → °C、㎞ → km、Ⅰ → I、… → ... になります (neologdn は残します)。避けたい場合は nfkc=False
• 横棒 ― (U+2015) を neologdn は長音 ー にしますが、jpnorm はダッシュ - にします
• 罫線 ─ ━ を neologdn は常に ー にしますが、jpnorm はかなの直後 (ハ─ト → ハート) だけ ー にし、それ以外 (日本全史─ジャパン) は - にします

移行後に「URL は保護したい」「絵文字は消したい」となったら、そこからフラグを足すだけです。

n = Normalizer("neologdn_compat", protect_urls=True, emoji="remove")

プリセット早見表

一覧は Normalizer.presets() で取得できます。迷ったら、表示なら for_display、 それ以外は for_search から始めて、必要に応じて for_compare に寄せるのがおすすめです。

細かく調整する

プリセットをベースに、キーワード引数で個別フラグを上書きできます。 キーは Normalizer.config が返す dict と同じで、Normalizer(**n.config) で複製できます。

n = Normalizer(
    "for_search",
    emoji="keep",              # 絵文字を残す
    kana="kata_to_hira",       # カタカナをひらがなに統一
    url_wrap=("<", ">"),       # URL を <...> で囲む (Slack/Markdown の自動リンク)
    repeat_limit=3,            # 同一文字の連続を 3 つまでに短縮
)
n.normalize("スゴーーーーイ😀 https://example.com")
# => 'すごーい😀 <https://example.com>'

n.config["nfkc"]   # => True

normalize / normalize_batch は処理中に GIL を解放するので、スレッドプールで並列化できます。

コマンドラインで使う

echo "ﾊﾝｶｸｶﾅ　と  全角  ！！" | jpnorm
# ハンカクカナ と 全角 !!

jpnorm -p for_search --set emoji=keep --set kana=kata_to_hira "スゴーーーイ😀"
# すごーい😀

jpnorm -p for_compare --files --dict brands.json input.txt > normalized.txt
jpnorm --json "ｶﾅ"            # {"input": "ｶﾅ", "output": "カナ"}
jpnorm -p for_compare --show-config   # 実際に使う設定を JSON で表示
jpnorm --list-presets

パフォーマンス

neologdn (C++ 実装) と同じ入力で比較したスループットです (scripts/bench-vs-neologdn.py、Apple Silicon、Python 3.12)。

for_search は URL 保護・絵文字除去・機種依存文字展開が加わるぶん neologdn_compat より遅くなります。 normalize / normalize_batch は GIL を解放するので、スレッドプールでさらに並列化できます。

他のライブラリとの違い

jaconv や mojimoji は「文字種変換だけしたい」場面では十分軽量です。 jpnorm は複数の処理を用途に合わせて組み合わせたいときに向いています。

Rust から使う

コアは jpnorm-core クレートとして独立しており、Python 無しでも使えます (現時点では crates.io 未公開のため git 依存で指定してください)。

[dependencies]
jpnorm-core = { git = "https://github.com/YoshitakaOyama/jpnorm" }

use jpnorm_core::{EmojiAction, Normalizer, Preset};

let n = Normalizer::builder()
    .preset(Preset::ForSearch)
    .configure(|c| c.emoji_action = EmojiAction::Keep)   // プリセットの一部を打ち消す
    .kata_to_hira()
    .build();
assert_eq!(n.normalize("ｶﾅ😀"), "かな😀");

// 保護領域の位置も取れる (検索ハイライト等に)
let r = n.normalize_with_segments("@alice と https://example.com だよ");
println!("{:?}", r.segments);

開発

git clone https://github.com/YoshitakaOyama/jpnorm.git
cd jpnorm
uv sync --group dev          # Rust 拡張をビルドして .venv に入れる
uv run pytest                # Python テスト
cargo test --workspace       # Rust テスト
cargo clippy --workspace --all-targets -- -D warnings
uv run ruff check . && uv run mypy
cargo bench -p jpnorm-core   # ベンチマーク (criterion)
uv run --with neologdn scripts/bench-vs-neologdn.py   # neologdn との比較表
wasm-pack build crates/jpnorm-wasm --target web --release --out-dir ../../playground/pkg --no-typescript
python -m http.server -d playground 8765   # プレイグラウンドをローカルで開く

Rust ソースを変更したら uv sync で再ビルドされます。 neologdn とのゴールデン比較テストは tests/golden/neologdn.jsonl を使い、 uv run --with neologdn scripts/gen-neologdn-golden.py で再生成できます。

リリースは CHANGELOG.md を更新し、v* タグを push すると wheel のビルド・PyPI 公開・ GitHub Release 作成まで自動で行われます。

ライセンス

MIT または Apache-2.0 のデュアルライセンス。好きな方を選んでください。