国別データ管理パッケージ 6 選：機能、保守性、実装比較

フロントエンド開発で国別データ（国名、コード、通貨、言語など）を扱う際、どの npm パッケージを選ぶべきか迷うことはよくあります。countries-list、country-code-lookup、country-data、country-list、i18n-iso-countries、iso-3166-1-alpha-2 の 6 パッケージは、それぞれ異なる設計思想と機能範囲を持っています。本稿では、実務的な観点から各パッケージを深く比較します。

📦 データ構造と取得方法

各パッケージはデータの提供方法が異なります。これがコードの書き方とバンドルサイズに直接影響します。

countries-list はオブジェクト形式で国データをエクスポートします。

import { countries } from 'countries-list';

// 全国家リストの取得
Object.values(countries).forEach(country => {
  console.log(country.name, country.iso2, country.currency);
});

// 特定国の取得
console.log(countries.JP); // { name: 'Japan', iso2: 'JP', ... }

country-code-lookup は検索関数を中心に設計されています。

const countryLookup = require('country-code-lookup');

// ISO コードから国名
console.log(countryLookup.byIso('JP').country);

// 国名からコード
console.log(countryLookup.byCountry('Japan').iso2);

// 電話コードから国
console.log(countryLookup.byPhone('81').country);

country-data は豊富なメタデータを含む配列形式です。

const countries = require('country-data').countries;

// 配列としてイテレーション
countries.forEach(country => {
  console.log(country.name, country.currencies, country.languages);
});

// 特定国の検索
const japan = countries.filter(c => c.alpha2 === 'JP')[0];

country-list はシンプルな配列形式を提供します。

const countries = require('country-list');

// 全国家リスト
console.log(countries.getCodes()); // ['AF', 'AL', ...]
console.log(countries.getName('JP')); // 'Japan'
console.log(countries.getCode('Japan')); // 'JP'

i18n-iso-countries は多言語対応の API を提供します。

const countries = require('i18n-iso-countries');
const ja = require('i18n-iso-countries/langs/ja.json');

countries.registerLocale(ja);

// 日本語で国名取得
console.log(countries.getName('JP', 'ja')); // '日本'

// 全国家リスト（日本語）
console.log(countries.getNames('ja')); // { JP: '日本', US: 'アメリカ合衆国', ... }

iso-3166-1-alpha-2 は 2 文字コードに特化しています。

const alpha2 = require('iso-3166-1-alpha-2');

// コード検証
console.log(alpha2.getCodes()); // ['AF', 'AL', ...]
console.log(alpha2.getCode('Japan')); // 'JP'
console.log(alpha2.getName('JP')); // 'Japan'

🌐 多言語対応（i18n）の深さ

国際化アプリケーションでは、この違いが最も重要になります。

i18n-iso-countries が圧倒的に優れています。50 言語以上の翻訳データを含み、言語ごとに登録して切り替え可能です。

const countries = require('i18n-iso-countries');
const ja = require('i18n-iso-countries/langs/ja.json');
const en = require('i18n-iso-countries/langs/en.json');
const zh = require('i18n-iso-countries/langs/zh.json');

countries.registerLocale(ja);
countries.registerLocale(en);
countries.registerLocale(zh);

// 言語切り替え
console.log(countries.getName('FR', 'ja')); // 'フランス'
console.log(countries.getName('FR', 'en')); // 'France'
console.log(countries.getName('FR', 'zh')); // '法国'

countries-list は英語ベースですが、一部の国に現地語名を含みます。

import { countries } from 'countries-list';

console.log(countries.JP.name); // 'Japan'
console.log(countries.JP.native); // '日本'（一部国のみ）

country-code-lookup、country-data、country-list、iso-3166-1-alpha-2 は多言語対応が限定的または英語のみの場合が多く、国際化プロジェクトでは追加の実装が必要になります。

⚠️ 保守状況と非推奨パッケージ

パッケージのメンテナンス状況は長期プロジェクトで重要な要素です。

country-data は 2018 年以降、大きな更新が確認されていません。npm ページや GitHub リポジトリで非推奨の明示はありませんが、アクティブなメンテナンスは確認できません。新しいプロジェクトでの採用は避けるべきです。

// ⚠️ 新規プロジェクトでは非推奨
const countries = require('country-data').countries;
// 代替: i18n-iso-countries または countries-list を検討

i18n-iso-countries はアクティブにメンテナンスされており、ISO 標準の更新にも追従しています。長期使用に最も安心できます。

countries-list、country-list、country-code-lookup、iso-3166-1-alpha-2 は比較的安定していますが、更新頻度はパッケージにより異なります。採用前に最新の npm ページと GitHub リポジトリを確認しましょう。

🔍 検索・変換機能の比較

国コード、国名、電話コードなど、様々な形式での検索が必要になる場面があります。

country-code-lookup は検索機能に最も特化しています。

const countryLookup = require('country-code-lookup');

// ISO 2 文字コード
console.log(countryLookup.byIso('JP'));

// ISO 3 文字コード
console.log(countryLookup.byIso('JPN'));

// 国名（部分一致も可能）
console.log(countryLookup.byCountry('United'));

// 電話コード
console.log(countryLookup.byPhone('81'));

// 通貨コード
console.log(countryLookup.byCurrency('JPY'));

i18n-iso-countries はコード変換機能を提供します。

const countries = require('i18n-iso-countries');

// alpha-2 から alpha-3
console.log(countries.alpha2ToAlpha3('JP')); // 'JPN'

// alpha-3 から alpha-2
console.log(countries.alpha3ToAlpha2('JPN')); // 'JP'

// 数字コードから alpha-2
console.log(countries.numericToAlpha2('392')); // 'JP'

countries-list、country-list、iso-3166-1-alpha-2 は基本的なコード変換のみ対応し、電話コードや通貨コードでの検索はサポートされていません。

country-data は豊富なデータを含みますが、検索機能は自前で実装する必要があります。

💰 通貨・言語・地域メタデータ

国に関連する追加データが必要な場合、パッケージの選択が重要になります。

country-data が最も豊富なメタデータを含みます。

const countries = require('country-data').countries;

const japan = countries.filter(c => c.alpha2 === 'JP')[0];
console.log(japan.currencies); // [{ code: 'JPY', name: 'Yen' }]
console.log(japan.languages); // ['ja']
console.log(japan.topLevelDomain); // ['.jp']
console.log(japan.region); // 'Asia'

countries-list も通貨情報を含みます。

import { countries } from 'countries-list';

console.log(countries.JP.currency); // 'JPY'
console.log(countries.JP.languages); // ['ja']
console.log(countries.JP.continent); // 'AS'

i18n-iso-countries は通貨コードの変換を提供しますが、通貨名などの詳細データは含みません。

const countries = require('i18n-iso-countries');

// 通貨コード取得（一部バージョン）
console.log(countries.getAlpha2Code('Japan', 'en')); // 'JP'

country-code-lookup は通貨コードでの検索は可能ですが、通貨の詳細データは限定的です。

country-list、iso-3166-1-alpha-2 は国名とコードのみに焦点を当て、通貨や言語データは含みません。

🎯 実務シナリオ別推奨

シナリオ 1：多言語 e コマースサイト

✅ 推奨: i18n-iso-countries

理由：50 言語以上の対応、ISO 標準準拠、アクティブなメンテナンス。

const countries = require('i18n-iso-countries');
const ja = require('i18n-iso-countries/langs/ja.json');
const en = require('i18n-iso-countries/langs/en.json');

countries.registerLocale(ja);
countries.registerLocale(en);

// ユーザーの言語設定に応じて表示切り替え
function getCountryName(code, userLang) {
  return countries.getName(code, userLang) || countries.getName(code, 'en');
}

シナリオ 2：シンプルな国選択ドロップダウン

✅ 推奨: country-list または countries-list

理由：軽量、シンプルな API、十分な機能。

const countries = require('country-list');

// React コンポーネント例
function CountrySelect({ value, onChange }) {
  return (
    <select value={value} onChange={onChange}>
      {countries.getCodes().map(code => (
        <option key={code} value={code}>
          {countries.getName(code)}
        </option>
      ))}
    </select>
  );
}

シナリオ 3：国コード検証・変換サービス

✅ 推奨: country-code-lookup

理由：多様な検索方法、コード変換に特化。

const countryLookup = require('country-code-lookup');

function validateAndNormalize(input) {
  // 様々な形式の入力を正規化
  const result = countryLookup.byIso(input) || 
                 countryLookup.byCountry(input) ||
                 countryLookup.byPhone(input);
  
  return result ? result.iso2 : null;
}

シナリオ 4：レガシープロジェクトの維持

⚠️ 注意: country-data 使用の場合は移行を検討

理由：メンテナンス停滞のリスク。

// 既存コード
const countries = require('country-data').countries;

// 移行先例（i18n-iso-countries）
const countries = require('i18n-iso-countries');
// API の違いに注意してリファクタリングが必要

📊 機能比較サマリー

💡 最終的な選択ガイド

パッケージ選択は、プロジェクトの要件と長期運用計画に基づいて行うべきです。

i18n-iso-countries を選ぶべき場合:

• 多言語対応が必須
• ISO 標準への完全準拠が必要
• 長期メンテナンスを重視
• e コマース、SaaS、国際向けプロダクト

countries-list を選ぶべき場合:

• 英語ベースのアプリケーション
• 通貨・言語メタデータも必要
• 軽量さを維持したい
• シンプルな API 設計を好む

country-code-lookup を選ぶべき場合:

• 国コード変換・検索が主目的
• 電話コードや通貨コードでの検索が必要
• 豊富なメタデータは不要

country-list を選ぶべき場合:

• 最小限の機能で十分
• バンドルサイズを最優先
• シンプルなドロップダウン UI 実装

country-data の扱い:

• 新規プロジェクトでは非推奨
• 既存プロジェクトは移行計画を立てる
• 代替: i18n-iso-countries または countries-list

iso-3166-1-alpha-2 を選ぶべき場合:

• 2 文字コードのみに焦点
• 最小限の依存関係
• 特定形式の検証のみ必要

🔚 まとめ

6 パッケージ各有り一長一短がありますが、現代のフロントエンド開発では i18n-iso-countries が最もバランスの取れた選択と言えます。多言語対応、ISO 標準準拠、アクティブなメンテナンス、これら 3 つの要素が揃っているためです。

ただし、プロジェクトの要件によっては軽量な countries-list や country-list が適している場合もあります。バンドルサイズ、機能要件、保守計画を総合的に評価して選択しましょう。

最も重要なのは、パッケージのメンテナンス状況を確認し、長期運用を見据えた選択を行うことです。npm ページ、GitHub リポジトリ、最新のリリースノートを定期的にチェックする習慣をつけましょう。