📢

`joyokanji`をリリースしました

に公開
Python
NLP
PyPI
日本語
tech

大規模な日本語データセットをSudachipyでパーシングしようとしたのですが、旧字や異文字が含まれており正確にパースできなかったので、旧字および異文字を新字に変化するPythonライブラリを開発しました。
以外、日本語版Readmeからの引用になります。

joyokanji

joyokanji は、旧字体（旧字／旧字体：きゅうじたい）を新字体（新字／新字体：しんじたい）へ置き換えるための軽量・高速な Python ライブラリです。文化庁が公表する 常用漢字表 を参照してマッピングを作成しています：https://www.bunka.go.jp/kokugo_nihongo/sisaku/joho/joho/kijun/naikaku/kanji/

また、個人名などで使われやすい**異体字（髙／𠮷／﨑／隆 など）**の正規化も、variants=True でオプション利用できます。

旧字と新字とは？
戦後の国語改革により、よく使われる漢字の字形が簡略化されました。簡略化前の字形が 旧字体（旧字）、簡略化後の字形が 新字体（新字） です。例：鹽 → 塩, 國 → 国, 體 → 体。本ライブラリは旧字を現代的な新字に統一する用途に向きます。

特徴

  • 旧字体→新字体の**決定的（deterministic）**な置換。
  • str.translate による1パス O(n) の高速変換。
  • マッピングは joyokanji/config/kanji.json から初回のみ読み込み＆キャッシュ。
  • オプションで joyokanji/config/variants.json を併用し、人名などの異体字を正規化（variants=True）。
  • 依存関係が少なく、既存の前処理パイプラインに組み込みやすい。

インストール

pip install joyokanji

使い方

import joyokanji

text = "鹽と黃と黑と點と發"
print(joyokanji.convert(text))  # => 塩と黄と黒と点と発

# 異体字も含めて正規化したい場合
text2 = "髙橋𠮷野屋"
print(joyokanji.convert(text2, variants=True))  # => 高橋吉野屋

API:

joyokanji.convert(text: str, variants: bool = False) -> str

内部動作

  • 旧→新の単文字マッピング（例：{"鹽": "塩"}）を JSON から読み込み、str.maketrans で変換テーブルを構築します。
  • 以降の変換は str.translate により単一走査で実行されます。
  • テーブルはプロセス内で再利用され、2回目以降の呼び出しはメモリのみで高速です。
  • variants=True の場合は joyokanji/config/variants.json を読み込み、基本マップとマージ（衝突時は異体字側が優先）。このモード専用のキャッシュも用意します。

変換例

入力 → 出力：

旧字体 新字体
鹽 塩
黃 黄
黑 黒
點 点
發 発

※ マッピングにない文字は変換されず、そのまま残ります。

異体字オプション

variants=True を指定すると、人名等で用いられる異体字も正規化します。例：

異体字 正規化後
髙 高
𠮷 吉
﨑 崎
隆 隆
羽 羽
練 練

対象範囲と制限

  • 対象：現代日本語のテキスト正規化を主眼とした単文字置換です。中国語（繁体字・簡体字）の相互変換を目的としたものではありません。
  • 文脈非依存：単文字の置換のみで、形態素解析や文脈判断は行いません。
  • 固有名詞・人名：法的氏名・商標・歴史資料など、意図的に旧字を使うケースでは自動変換が不適切なことがあります。重要用途では必ず目視確認してください。
    • このため、異体字の正規化はデフォルトでは無効です。必要な場合のみ variants=True を指定してください。
  • 正規化：本ライブラリ自体は Unicode 正規化（NFKC 等）を行いません。必要に応じて前後で実施してください。
  • 異体字：歴史的に複数の字形が存在する文字は代表的な新字体へ集約しています。分野固有の表記が必要な場合はマッピングの拡張をご検討ください。

出典・クレジット

性能メモ

  • 変換テーブルの構築は初回のみ（プロセス単位）。
  • 以降はO(n) の1パス変換で、バッチ処理にも適します。

利用が適する場面／注意が必要な場面

適する場面：OCR した歴史資料の現代表記への統一、旧字混在テキストの前処理、検索索引の整形など。
注意が必要：戸籍・住民票などの人名、商標・企業名、学術的な校訂本文など原字形が意味を持つ場面。

コントリビュート

  • マッピングの改善、テストケースの追加、英日ドキュメントの改善を歓迎します。
  • 新規ペアを提案する際は、根拠（出典）と使用例を添えてください。

Discussion