ja-normalize

日本語テキスト正規化ライブラリ（TypeScript / 依存ゼロ）。Pythonの neologdn / jaconv に相当する処理を、TS/JS向けに提供します。

English README below

日本語

これは何か

日本語は「同じものを表す書き方」が複数存在します（全角/半角、異体字、旧字体、長音とハイフンのゆらぎ、丸数字、企業名の「(株)/株式会社/㈱」など）。検索・名寄せ・突合を行う直前にこれらを統一するための、依存ゼロのユーティリティライブラリです。

• 半角カナ・全角カナ・全角英数字の表記ゆれを統一
• ハイフンに見える記号（- ‐ − ―）を統一し、長音符の連続を圧縮
• 人名・地名に多い異体字・旧字体を正規化（髙→高、﨑→崎 など）
• 法人格表記（㈱/(株)/株式会社）の除去・統一
• 丸数字（①②③）・ローマ数字（Ⅲ）をASCIIに展開
• 全角スペース・波ダッシュ〜/全角チルダ～の統一
• NFC/NFD正規化（macOSのファイル名がNFDで保持される問題への対応）

Node、Vercel Edge、Cloudflare Workersなど、Node API非依存で動作します。

インストール

npm install ja-normalize

使い方

import { normalize } from "ja-normalize";

normalize("ｻｰﾊﾞｰ");
// => "サーバー"

normalize("東京都港区１丁目２−３");
// => "東京都港区1丁目2-3"

normalize("髙橋");
// => "高橋"

// 企業名の名寄せ（法人格表記の除去はデフォルトOFF。明示的に指定する）
normalize("㈱日本電産", { corpSuffix: "remove" });
normalize("日本電産(株)", { corpSuffix: "remove" });
// => どちらも "日本電産"

検索用途では、インデックス時とクエリ時の両方に同じ正規化をかけることが鉄則です。片方だけに適用すると逆にヒットしなくなります。

API

normalize(input: string, options?: NormalizeOptions): string

複数の正規化ルールを組み合わせた統合パイプラインです。

| オプション | 型 | デフォルト | 説明 | |---|---|---|---| | unicodeForm | "NFC" \| "NFD" \| "none" | "NFC" | Unicode正規化形式 | | alnumWidth | "half" \| "full" \| "none" | "half" | 英数記号の幅 | | kanaWidth | "half" \| "full" \| "none" | "full" | カタカナの幅 | | choonpu | boolean | true | ハイフン類の統一・長音符連続の圧縮 | | kanjiVariants | boolean | true | 異体字・旧字体の正規化 | | corpSuffix | "remove" \| "unify" \| "none" | "none" | 法人格表記の正規化（破壊的なため明示指定） | | circledNumber | boolean | true | 丸数字・ローマ数字の展開 | | whitespace | boolean | true | 全角スペース・連続空白の統一 | | tilde | boolean | true | 波ダッシュ・全角チルダの統一 |

個別関数

統合パイプラインを使わず、必要なルールだけを個別に呼び出すこともできます。

import {
  toNFC, toNFD,
  toFullWidthKana, toHalfWidthKana,
  toFullWidthAlnum, toHalfWidthAlnum,
  unifyDashes, collapseChoonpu,
  normalizeKanjiVariants,
  normalizeCorpSuffix,
  expandCircledNumber,
  normalizeWhitespace,
  normalizeTilde,
} from "ja-normalize";

開発

npm install
npm test        # vitest
npm run typecheck
npm run build    # tsup (ESM + CJS + .d.ts)

ライセンス

MIT

English

What is this

Japanese text has many "different spellings for the same thing": full-width/half-width forms, character variants, old-style kanji forms, inconsistent choonpu/hyphen glyphs, circled numbers, and company-suffix notation ((株) / 株式会社 / ㈱). This is a dependency-free utility library that normalizes these variations right before search, deduplication, or record matching.

• Unifies half-width kana / full-width kana / full-width alphanumerics
• Unifies hyphen-like glyphs (- ‐ − ―) and collapses repeated choonpu marks
• Normalizes common character variants / old-style kanji forms found in personal and place names (e.g. 髙→高, 﨑→崎)
• Removes or unifies corporate-suffix notation (㈱ / (株) / 株式会社)
• Expands circled numbers (①②③) and roman numerals (Ⅲ) to ASCII
• Unifies ideographic space, wave dash 〜, and full-width tilde ～
• NFC/NFD normalization (handles macOS filenames stored as NFD vs. NFC elsewhere)

Works anywhere without Node-only APIs: Node, Vercel Edge, Cloudflare Workers, etc.

Install

npm install ja-normalize

Usage

import { normalize } from "ja-normalize";

normalize("ｻｰﾊﾞｰ");
// => "サーバー"

normalize("東京都港区１丁目２−３");
// => "東京都港区1丁目2-3"

normalize("髙橋");
// => "高橋"

// Deduplicating company names (corpSuffix normalization is opt-in, since it's destructive)
normalize("㈱日本電産", { corpSuffix: "remove" });
normalize("日本電産(株)", { corpSuffix: "remove" });
// => both become "日本電産"

For search, always apply the same normalization to both indexing and query time. Applying it to only one side will make matches disappear instead of finding them.

API

normalize(input: string, options?: NormalizeOptions): string

A combined pipeline over the individual normalization rules.

| Option | Type | Default | Description | |---|---|---|---| | unicodeForm | "NFC" \| "NFD" \| "none" | "NFC" | Unicode normalization form | | alnumWidth | "half" \| "full" \| "none" | "half" | Width of alphanumerics/symbols | | kanaWidth | "half" \| "full" \| "none" | "full" | Width of katakana | | choonpu | boolean | true | Unify hyphen-like glyphs, collapse repeated choonpu | | kanjiVariants | boolean | true | Normalize character variants / old-style kanji forms | | corpSuffix | "remove" \| "unify" \| "none" | "none" | Normalize corporate-suffix notation (opt-in, destructive) | | circledNumber | boolean | true | Expand circled numbers / roman numerals | | whitespace | boolean | true | Unify ideographic space, collapse repeated whitespace | | tilde | boolean | true | Unify wave dash and full-width tilde |

Individual rule functions

Each rule can also be called on its own without the combined pipeline:

import {
  toNFC, toNFD,
  toFullWidthKana, toHalfWidthKana,
  toFullWidthAlnum, toHalfWidthAlnum,
  unifyDashes, collapseChoonpu,
  normalizeKanjiVariants,
  normalizeCorpSuffix,
  expandCircledNumber,
  normalizeWhitespace,
  normalizeTilde,
} from "ja-normalize";

Development

npm install
npm test        # vitest
npm run typecheck
npm run build    # tsup (ESM + CJS + .d.ts)

License

MIT