フロントエンド開発における国・地域データ管理ライブラリの深層比較

フロントエンドアプリケーションで国や地域を扱う際、適切なデータソースを選ぶことは重要な архитектур 決定です。countries-list、country-code-lookup、country-data、country-list、i18n-iso-countries、iso-3166-1 はすべて国データを扱いますが、設計思想と提供機能が大きく異なります。本稿では、実務的な観点から各パッケージを比較します。

📦 データ構造と取得方法

各パッケージは異なるデータ構造を提供しており、これがユースケースに直接影響します。

countries-list はシンプルなオブジェクト構造で、国コードをキーとして国情報を取得します。

import { countries } from 'countries-list';

// 国コードでアクセス
console.log(countries['JP']);
// { name: 'Japan', native: '日本', phone: '81', ... }

// 全リストの取得
console.log(Object.values(countries));

country-code-lookup は検索関数を中心に設計されており、コードや国名から国情報を検索します。

import countryCodeLookup from 'country-code-lookup';

// ISO コードで検索
console.log(countryCodeLookup.byIso('JP'));
// { iso2: 'JP', iso3: 'JPN', name: 'Japan', ... }

// 国名で検索
console.log(countryCodeLookup.byName('Japan'));

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

import countries from 'country-data';

// 配列としてアクセス
console.log(countries.countries['JP']);
// { name: 'Japan', currency: 'JPY', languages: ['ja'], ... }

// 通貨情報も含まれる
console.log(countries.currencies['JPY']);

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

import countries from 'country-list';

// コードと名前の配列
console.log(countries.getData());
// [{ code: 'JP', name: 'Japan' }, ...]

// コードから名前取得
console.log(countries.getName('JP'));
// 'Japan'

i18n-iso-countries は多言語対応に特化し、言語コードを指定して国名を取得できます。

import countries from 'i18n-iso-countries';
import jaLocale from 'i18n-iso-countries/langs/ja.json';

// 言語登録
countries.registerLocale(jaLocale);

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

// 全リスト取得
console.log(countries.getNames('ja'));

iso-3166-1 は ISO 規格の厳密な実装で、3 種類のコード形式をサポートします。

import iso3166 from 'iso-3166-1';

// alpha-2 コードで検索
console.log(iso3166.forAlpha2('JP'));
// { alpha2: 'JP', alpha3: 'JPN', numeric: '392', name: 'Japan' }

// alpha-3 コードで検索
console.log(iso3166.forAlpha3('JPN'));

🌐 多言語対応（i18n）の比較

国際化対応は現代フロントエンド開発の必須要件です。各パッケージの対応状況を比較します。

i18n-iso-countries が唯一、本格的な多言語対応を提供しています。

// i18n-iso-countries: 多言語対応
import countries from 'i18n-iso-countries';
import jaLocale from 'i18n-iso-countries/langs/ja.json';
import enLocale from 'i18n-iso-countries/langs/en.json';

countries.registerLocale(jaLocale);
countries.registerLocale(enLocale);

console.log(countries.getName('JP', 'ja')); // '日本'
console.log(countries.getName('JP', 'en')); // 'Japan'

他のパッケージは英語名のみの提供が基本です。多言語対応が必要な場合、i18n-iso-countries が事実上の標準選択肢となります。

🔍 検索と変換機能

国コードの変換（alpha-2 ↔ alpha-3 ↔ numeric）は頻繁に必要な操作です。

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

import countryCodeLookup from 'country-code-lookup';

// 様々な検索方法
console.log(countryCodeLookup.byIso('JP'));      // alpha-2
console.log(countryCodeLookup.byIso('JPN'));     // alpha-3
console.log(countryCodeLookup.byName('Japan'));  // 国名
console.log(countryCodeLookup.byPhone('81'));    // 電話番号

iso-3166-1 は ISO 規格の全コード形式をサポートします。

import iso3166 from 'iso-3166-1';

console.log(iso3166.forAlpha2('JP'));    // alpha-2
console.log(iso3166.forAlpha3('JPN'));   // alpha-3
console.log(iso3166.forNumeric('392'));  // numeric

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

import countries from 'i18n-iso-countries';

console.log(countries.alpha3ToAlpha2('JPN'));  // 'JP'
console.log(countries.alpha2ToAlpha3('JP'));   // 'JPN'
console.log(countries.numericToAlpha2('392')); // 'JP'

countries-list と country-list は基本的なコードアクセスのみ提供し、変換機能は限定的です。

// countries-list: オブジェクトキーでアクセス
import { countries } from 'countries-list';
console.log(countries['JP'].iso3);  // 'JPN'

// country-list: 簡易変換
import countries from 'country-list';
console.log(countries.getCode('Japan'));  // 'JP'

country-data は包括的なデータ構造内でコードにアクセスします。

import countries from 'country-data';
console.log(countries.countries['JP'].iso2);  // 'JP'
console.log(countries.countries['JP'].iso3'); // 'JPN'

📊 追加メタデータの比較

通貨、言語、国旗、地域などのメタデータが必要な場合があります。

country-data が最も豊富なメタデータを提供します。

import countries from 'country-data';

const japan = countries.countries['JP'];
console.log(japan.currency);      // 'JPY'
console.log(japan.languages);     // ['ja']
console.log(japan.flag);          // '🇯🇵'
console.log(japan.region);        // 'Asia'

countries-list も豊富なメタデータを提供します。

import { countries } from 'countries-list';

const japan = countries['JP'];
console.log(japan.currency);      // 'JPY'
console.log(japan.languages);     // ['ja']
console.log(japan.emoji);         // '🇯🇵'
console.log(japan.phone);         // '81'

country-code-lookup も実用的なメタデータを含みます。

import countryCodeLookup from 'country-code-lookup';

const japan = countryCodeLookup.byIso('JP');
console.log(japan.currency);      // 'JPY'
console.log(japan.flag);          // '🇯🇵'
console.log(japan.phone_code);    // '81'

i18n-iso-countries、country-list、iso-3166-1 はコアデータに集中し、追加メタデータは最小限です。

⚠️ メンテナンス状況と非推奨パッケージ

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

注意: country-data パッケージはメンテナンスが停止している可能性があります。npm ページや GitHub リポジトリで最新のメンテナンス状況を確認してください。新しいプロジェクトでは、より積極的にメンテナンスされている代替パッケージを検討することをお勧めします。

i18n-iso-countries はコミュニティによって積極的にメンテナンスされており、言語ロケールの更新も頻繁に行われています。

// i18n-iso-countries: 積極的なメンテナンス
// 言語ロケールが定期的に更新される
import jaLocale from 'i18n-iso-countries/langs/ja.json';
countries.registerLocale(jaLocale);

countries-list と country-code-lookup も比較的稳定したメンテナンス状況にあります。

iso-3166-1 は ISO 規格が更新された際にのみ更新されるため、更新頻度は低めですが、規格準拠という点では信頼性が高いです。

🎯 実務ユースケース別推奨

ケース 1: 多言語対応の E コマースサイト

// ✅ 推奨: i18n-iso-countries
import countries from 'i18n-iso-countries';
import jaLocale from 'i18n-iso-countries/langs/ja.json';
import enLocale from 'i18n-iso-countries/langs/en.json';

countries.registerLocale(jaLocale);
countries.registerLocale(enLocale);

// ユーザーの言語設定に応じて国名を表示
function renderCountrySelect(userLang) {
  const countryNames = countries.getNames(userLang);
  return Object.entries(countryNames).map(([code, name]) => (
    <option value={code}>{name}</option>
  ));
}

ケース 2: 電話番号入力フォーム

// ✅ 推奨: countries-list または country-code-lookup
import { countries } from 'countries-list';

// 国コードと電話番号プレフィックスを表示
function renderPhoneInput() {
  return Object.entries(countries).map(([code, data]) => (
    <option value={`+${data.phone}`}>
      {data.emoji} {data.name} (+{data.phone})
    </option>
  ));
}

ケース 3: 通貨表示と変換

// ✅ 推奨: country-data または countries-list
import countries from 'country-data';

// 国から通貨コードを取得
function getCurrencyForCountry(countryCode) {
  return countries.countries[countryCode].currency;
}

// 通貨記号と組み合わせて表示
function formatPrice(amount, countryCode) {
  const currency = countries.countries[countryCode].currency;
  return `${amount} ${currency}`;
}

ケース 4: 規格準拠が必須の金融システム

// ✅ 推奨: iso-3166-1
import iso3166 from 'iso-3166-1';

// ISO 規格コードの検証
function validateCountryCode(code) {
  const result = iso3166.forAlpha2(code);
  return result !== undefined;
}

// コード変換（alpha-2 ↔ alpha-3）
function convertCode(code, targetType) {
  if (targetType === 'alpha3') {
    return iso3166.forAlpha2(code).alpha3;
  }
  return iso3166.forAlpha3(code).alpha2;
}

ケース 5: シンプルな国名ドロップダウン

// ✅ 推奨: country-list
import countries from 'country-list';

// 最小限のコードで実装
function renderSimpleSelect() {
  return countries.getData().map(({ code, name }) => (
    <option value={code}>{name}</option>
  ));
}

📋 総合比較表

💡 最終推奨

プロジェクトの要件に応じて、以下の基準で選択してください:

多言語対応が必須 → i18n-iso-countries が唯一の選択肢です。50 以上の言語をサポートし、コミュニティによる積極的なメンテナンスがあります。

豊富なメタデータが必要 → countries-list または country-data を検討してください。通貨、言語、国旗、電話番号など包括的なデータが必要です。

コード変換と検索が中心 → country-code-lookup または iso-3166-1 が適しています。特に ISO 規格準拠が重要な場合は iso-3166-1 を選択してください。

シンプルさが最優先 → country-list が最小限の依存関係で基本的な国名リストを提供します。

重要な注意点: country-data のメンテナンス状況を確認してください。長期プロジェクトでは、より積極的にメンテナンスされているパッケージを選ぶことがリスク軽減につながります。

国データライブラリの選択は、アプリケーションの国際化戦略に直接影響します。プロジェクトの規模、対象地域、メンテナンス計画を考慮して、最適なパッケージを選択してください。