はじめに (対象読者・この記事でわかること)

本記事は、TypeScript を使って日本語文字列をひらがな・カタカナに変換したい プログラミング初心者から中級者 を対象としています。特に、Web アプリや CLI ツールで日本語入力を標準化したい方、国際化対応の一環として文字種変換を行いたい方に役立ちます。この記事を読むと、以下ができるようになります。

  • npm パッケージ wanakana のインストールから型定義の付与までの流れ
  • TypeScript で安全に文字列をカナ変換する関数の実装方法
  • 変換ロジックで起こりやすいエッジケース（半角/全角、長音、拗音など）への対処法

なお、執筆のきっかけは、社内ツールで入力される自由記述欄の文字種が統一されず、検索やソートに支障が出たことです。手軽に統一できる仕組みを共有したく、本記事を作成しました。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。
基本的な JavaScript / TypeScript の文法
 npm（Node.js パッケージマネージャ）の使用経験
* VS Code などのエディタでプロジェクトを操作できること

カナ変換の概要と背景

日本語テキストは、ひらがな・カタカナ・漢字・ローマ字 が混在するため、検索エンジンやデータベースでの正規化が必要になるケースが多くあります。特に、ユーザーが自由に入力できるフォームでは、同一語でも「テスト」「てすと」「テスト」など表記が分散し、検索結果がばらばらになるリスクがあります。そこで 文字列を統一的なカナ表記に変換 することで、以下のようなメリットが得られます。

  1. 検索の一貫性：カナ変換後にインデックスを作成すれば、表記揺れを吸収できます。
  2. 入力補完の精度向上：ユーザーがローマ字で入力しても、内部的にカナに変換すれば自動補完が容易に。
  3. データクレンジング：データベースに格納された文字列の表記揺れを一括で正規化でき、レポート作成や分析が楽になります。

TypeScript でこの処理を行う際のポイントは、型安全性を保ちつつ外部ライブラリを活用 することです。代表的なライブラリとして wanakana があり、ひらがな⇔カタカナ、ローマ字⇔ひらがななど多彩な変換機能を提供しています。本稿では wanakana を例に、型定義の追加やユーティリティ関数の作成手順を詳しく解説します。

カナ変換実装の手順とコード例

以下では、実際に TypeScript プロジェクトを作成し、文字列をカナ変換するモジュール を実装するまでのフローをステップごとに示します。

ステップ1　プロジェクトの雛形作成と依存関係の導入

  1. 作業ディレクトリを作成し、npm 初期化します。 
Bash

mkdir ts-kana-converter && cd ts-kana-converter
npm init -y
  1. TypeScript と ts-node（開発時の実行用）をインストールします。 
Bash

npm i -D typescript ts-node @types/node
  1. wanakana とその型定義をインストールします。 
Bash

npm i wanakana
npm i -D @types/wanakana
  1. tsconfig.json を生成し、strict モードを有効にします。 
Bash

npx tsc --init --strict
  1. ディレクトリ構成はシンプルに以下を推奨します。 
src/
 └─ index.ts          ← エントリーポイント
 └─ converters/
      └─ kana.ts      ← カナ変換ロジック

ステップ2　カナ変換ユーティリティの実装

src/converters/kana.ts に、汎用的な変換関数とエラーハンドリングを実装します。

Ts

// src/converters/kana.ts
import { toKatakana, toHiragana, isKana, isHiragana, isKatakana } from 'wanakana';

/**
 * 文字列を指定したカナ種別に変換する。
 * @param input 変換対象の文字列
 * @param target 'hiragana' | 'katakana' を指定
 * @returns 変換後の文字列。変換できなかった文字はそのまま返す。
 * @throws {TypeError} input が文字列でない場合にスロー
 */
export function convertKana(
  input: unknown,
  target: 'hiragana' | 'katakana' = 'katakana'
): string {
  if (typeof input !== 'string') {
    throw new TypeError(`convertKana expects a string, but received ${typeof input}`);
  }

  // 空文字はそのまま返す
  if (!input) return '';

  // wanakana の変換関数はローマ字も自動的に変換してくれる
  const normalized = input
    .replace(/\s+/g, '')               // 空白除去（必要に応じて調整）
    .replace(/[～—−]/g, 'ー');          // 各種長音記号を統一

  let result: string;
  if (target === 'hiragana') {
    result = toHiragana(normalized);
  } else {
    result = toKatakana(normalized);
  }

  // 変換後にカナ以外の文字が残っているかチェック
  const nonKana = result.split('').filter(ch => !isKana(ch));
  if (nonKana.length > 0) {
    console.warn(`convertKana: input contains non‑kana characters: ${nonKana.join('')}`);
  }

  return result;
}

ポイント解説：

項目 内容
型安全 input を unknown とし、実行時に typeof チェックを行うことで、予期しない型が渡されたときに早期例外を発生させます。
デフォルト挙動 第2引数 target のデフォルトは 'katakana' に設定し、呼び出し側が省略した場合でも期待通りに動作します。
正規化 全角・半角スペース、異なる長音記号（～、—、−）を統一してから変換することで、入力の揺らぎを減らします。
警告出力 変換後にカナ以外が残っていれば console.warn で通知し、デバッグやログ解析に活用できます。

ステップ3　エントリーポイントからの呼び出し例

src/index.ts にサンプルコードを置き、CLI でも動くようにします。

Ts

// src/index.ts
import { convertKana } from './converters/kana';

const samples = [
  'こんにちは',
  'コンニチハ',
  'konnichiwa',
  'ｶﾀｶﾅ',          // 半角カタカナ
  '東京タワー',
  'Tokyo Tower',
];

for (const s of samples) {
  try {
    const katakana = convertKana(s, 'katakana');
    const hiragana = convertKana(s, 'hiragana');
    console.log(`Original: ${s}`);
    console.log(`→ Katakana: ${katakana}`);
    console.log(`→ Hiragana: ${hiragana}`);
    console.log('---');
  } catch (e) {
    console.error(`Error processing "${s}":`, e);
  }
}

npm run ts-node src/index.ts を実行すると、各サンプル文字列がカタカナ・ひらがなに正しく変換されて出力されます。

ハマった点やエラー解決

現象 原因 解決策
Cannot find module 'wanakana' or its corresponding type declarations. @types/wanakana がインストールされていない、または tsconfig.json の typeRoots が限定されている。 npm i -D @types/wanakana を再実行し、tsconfig.json の typeRoots を削除または node_modules/@types を含める。
変換後に全角スペースが残る 正規化でスペース除去の正規表現が \s のみだったため、全角スペース (\u3000) が対象外。 正規表現を /[\s\u3000]+/g に拡張するか、Unicode 正規化 normalize('NFKC') を利用。
半角カタカナが変換されない wanakana はデフォルトで半角カタカナをサポートしない。 toKatakana/toHiragana にオプション { passRomaji: false, upcaseKatakana: false, katakanaToHiragana: false } を渡すか、事前に normalize('NFKC') で全角化する。
長音記号が統一されずに ー と ｰ が混在 入力に異なる長音文字が混在している。 変換前に replace(/[～—−]/g, 'ー') を適用し、全てを同一文字に揃える。

解決策の実装例（長音・全角化対応）

Ts

// 文字列正規化ユーティリティ
export function normalizeJapanese(input: string): string {
  return input
    .normalize('NFKC')                     // 半角・全角・濁点統一
    .replace(/[～—−]/g, 'ー')               // 長音統一
    .replace(/\s+/g, '')                    // 全角・半角スペース除去
    .trim();
}

上記 normalizeJapanese を convertKana の内部で呼び出すだけで、ほとんどの入力揺らぎを自動的に解決できます。

テストの自動化（オプショナル）

品質を保つために、Jest でユニットテストを書いておくと安心です。

Bash

npm i -D jest ts-jest @types/jest
npx ts-jest config:init

tests/kana.test.ts の例：

Ts

import { convertKana } from '../src/converters/kana';

describe('convertKana', () => {
  it('should convert romaji to katakana', () => {
    expect(convertKana('konnichiwa')).toBe('コンニチワ');
  });

  it('should keep non‑kana characters unchanged', () => {
    expect(convertKana('東京タワー')).toBe('東京タワー');
  });

  it('throws on non‑string input', () => {
    // @ts-ignore
    expect(() => convertKana(123)).toThrow(TypeError);
  });
});

npm test でテストが通れば、実装は安全です。

まとめ

本記事では、TypeScript と wanakana を組み合わせて日本語文字列を安全かつ柔軟にカナ変換する方法 をステップバイステップで解説しました。

  • プロジェクトの初期化から依存パッケージ導入、tsconfig の設定まで網羅
  • カナ変換ロジックを型安全に実装し、正規化やエラーハンドリングを組み込む手法
  • 実装時に陥りやすい問題点とその具体的な解決策、テスト自動化のベストプラクティス

これにより、文字種が統一されないことによる検索やデータ集計の課題を根本的に解決でき、開発効率とデータ品質の向上 が期待できます。次回は、実際の Web フレームワーク（React/Vue）と組み合わせたリアルタイム入力変換や、サーバーサイド（Node.js）での一括バッチ処理について取り上げる予定です。

参考資料