Command Palette

Search for a command to run...

ドキュメント

LocaleDBのデータ、パイプライン、アーキテクチャについて知る必要があるすべて。

概要

LocaleDBは、国際的なアプリケーションを構築する開発者向けの包括的なオープンソースのローカリゼーション百科事典です。

250カ国以上

100+言語

150+通貨

9,415空港

主な機能

  • 信頼できる情報源からの包括的なデータ（CLDR、世界銀行、mledoze、libphonenumber、IANA tz、libaddressinput、Wikidata）
  • 静的生成 - ランタイムデータベースは不要
  • MITライセンスおよびコミュニティ主導
  • アラビア語のRTLサポートを含む11言語

はじめに

リポジトリをクローンして、数分でロケールデータの探索を開始します。

# リポジトリをクローンする
git clone https://github.com/ozkurkculer/localedb.git
cd localedb

# 依存関係をインストールする
pnpm install

# ソースから生データをダウンロードする
pnpm update:data

# 処理してJSONファイルを生成する
pnpm build:data

# 開発サーバーを起動する
pnpm dev

データパイプライン

LocaleDBは、複数の信頼できる情報源からのデータを多段階のパイプラインを通じて処理します。

1

外部ソース

CLDR、mledoze、世界銀行、libphonenumber、IANA tz、libaddressinput、Wikidata、mwgg/Airports, IP2Location

2

生データをダウンロード

pnpm update:data はdata/サブディレクトリにファイルをダウンロードします

3

生データファイル

data/に保存されたJSON、CSV、XMLファイル

4

処理とマージ

pnpm build:data は優先ルールに従ってソースをマージします

5

生成されたJSON

個々の国、言語、通貨ファイル

6

静的サイト生成

Next.jsは5,868ページ以上の静的ページをビルドします

データソースの優先順位

複数のソースが同じフィールドを提供する場合、一貫した優先システムを使用します：

  • •国名：CLDR > mledoze
  • •人口：世界銀行 > CLDR
  • •電話データ：libphonenumber XML（公式）

データスキーマ

国、言語、通貨のJSONファイルの包括的な構造。

国スキーマ

data/countries/{CODE}.json
basics

名前、首都、座標、大陸、人口、面積、言語、国旗の絵文字

codes

ISO 3166、BCP-47、FIFA、IOC、FIPS、その他の国際コード

currency

コード、記号、位置、区切り文字、小数桁数、パターン、例

dateTime

日付/時刻形式（完全、長い、中程度、短い）、週の最初の日、タイムゾーン

numberFormat

小数/桁区切り記号、桁のグループ化、番号システム

phone

国番号、パターン、フォーマットルール、加入者番号の長さ

addressFormat

フォーマットテンプレート、郵便番号の正規表現と例

locale

書字方向、測定システム、温度スケール、用紙サイズ、運転側

airports

IATA、ICAO、座標、タイムゾーンを含む空港の配列

言語スキーマ

data/languages/{code}.json
code

ISO 639-1コード

name

英語名

nativeName

ネイティブ名

direction

テキストの方向（ltrまたはrtl）

countries

話されている国コードの配列

通貨スキーマ

data/currencies/{CODE}.json
code

ISO 4217コード

name

通貨名

symbol

通貨記号

symbolPosition

前または後

separators

小数点および桁区切り記号

decimalDigits

標準の小数点以下の桁数

pattern

フォーマットパターン

example

フォーマットされた例

countries

この通貨を使用している国コードの配列

Data Export

Build custom locale-data exports with the /export wizard. No scrapers, no scripts, no signups.

4-Step Wizard

1. Pick a dataset

Choose Countries, Currencies, Languages, or Airports.

2. Select entities

Searchable, paginated checkbox grid (60 per page) with select-all-filtered helpers. Up to 500 entities per request.

3. Choose fields

Collapsible field tree generated from the dataset schema. Per-group indeterminate state, sensible defaults.

4. Format & download

Pick JSON (pretty), JSON (minified), CSV (RFC 4180, flattened), or ZIP (one JSON file per entity).

Supported Formats

  • JSON (pretty) — indented, human-readable
  • JSON (minified) — compact, single-line
  • CSV — RFC 4180, dot-notation keys for nested fields
  • ZIP — one JSON file per entity, ideal for batch processing

API Endpoint

Server-side serialization happens at POST /api/export (Node runtime, maxDuration: 30). Pass dataset, entities, fields, and format in the JSON body. Set preview: true for an inline first-record JSON response without Content-Disposition.

POST /api/export
Content-Type: application/json

{
  "dataset": "countries",
  "entities": ["TR", "US", "DE"],
  "fields": ["basics.name", "currency.code", "phone.callingCode"],
  "format": "json",
  "preview": false
}

Limits: max 500 entities per request, dataset must be one of countries / currencies / languages / airports.

npm パッケージと CLI

LocaleDB を自分のコードで使えます。オフラインで動く型付きライブラリと、選んだデータをプロジェクトに書き出すコマンドラインツールです。

ベータ版：1.0 までに API が変更される可能性があります。

@localedb/core

すべてのデータセットを Node.js 向けの型付き同期関数として提供します。ブラウザでは @localedb/core/data/* から個々のレコードを JSON としてインポートできます。

npm install @localedb/core

import { getCountry, getCurrency } from "@localedb/core";

getCountry("TR")?.currency.symbol;          // "₺"
getCountry("DEU")?.dateTime.datePatterns;   // alpha-2 or alpha-3
getCurrency("EUR")?.countries;              // ["AT", "BE", "DE", ...]

@localedb/cli

localedb コマンド。init が必要なものを尋ね、JSON、CSV、型付き TypeScript ファイルを生成します。sync はそれらを最新の状態に保ちます。

npx @localedb/cli init

localedb get country TR --fields currency,dateTime.datePatterns
localedb export countries TR DE FR --format ts --out src/locales/countries.ts
localedb sync --check
  • get1 件のレコードを JSON で表示
  • exportレコードを JSON、CSV、TypeScript として標準出力、1 つのファイル、またはレコードごとのファイルに書き出す
  • listデータセットを表または JSON で一覧表示
  • searchコードまたは名前で国を検索
  • initlocaledb.config.json を対話形式で作成し、ファイルを生成
  • sync設定したファイルを再生成。--check は古くなっている場合に CI を失敗させる

コードは MIT ライセンスです。同梱データは各ソースのライセンスに従い、一部は継承（share-alike）条件付きです。詳しくはパッケージ内の NOTICE を参照してください。

プロジェクト構造

主要なディレクトリとその目的。

localedb/
├── data/                    # 生成されたJSONファイルと生ソースデータ
│   ├── countries/           # 250 country JSON files
│   ├── languages/           # 100+ language JSON files
│   ├── currencies/          # 150+ currency JSON files
│   ├── _index_*.json        # Lightweight indices
│   └── _meta.json           # Build metadata
├── packages/
│   ├── core/                # @localedb/core: types + data API
│   └── cli/                 # @localedb/cli: the localedb command
├── scripts/                 # データパイプラインスクリプト（update-data.ts、build-data.ts）
│   ├── update-data.ts       # Download raw data
│   ├── build-data.ts        # Process & generate JSON
│   └── generate-changelog.ts
├── src/
│   ├── app/[locale]/        # Next.js pages (i18n)
│   ├── components/          # React components
│   ├── lib/                 # Data access functions
│   ├── config/              # Site & nav config
│   └── i18n/                # Internationalization setup
└── messages/                # 11言語の翻訳ファイル

スクリプトリファレンス

データ管理と開発に利用可能なコマンド。

CommandDescription
pnpm update:dataすべての外部ソースから生データをダウンロード
pnpm update:data cldr worldbank特定のソースのみをダウンロード
pnpm build:data生データを処理してJSONファイルを生成
pnpm dev開発サーバーを起動
pnpm build本番ビルド（静的サイト生成）
npx tsx scripts/check-i18n.ts欠落している翻訳キーを確認して自動入力
pnpm version patchバージョンを上げ、変更履歴を自動生成

データの貢献

LocaleDBへの修正や改善の貢献方法。

貢献ワークフロー

  1. 1GitHubリポジトリをフォークし、ローカルマシンにクローンする
  2. 2build-data.tsでソースの優先順位を編集するか、アップストリームソースに修正を送信する
  3. 3messages/{lang}.jsonを編集してcheck-i18nを実行し、翻訳を追加する
  4. 41つのPRにつき1つの変更とし、公式ソースへのリンクを含めてプルリクエストを送信する

ガイドライン

  • 1つのプルリクエストにつき1つの変更
  • 常に公式ソース（CLDR、政府サイト、ISO標準）にリンクする
  • pnpm build:dataを実行して、変更が正しくマージされることを確認する
  • 明確で説明的なコミットメッセージ

国際化

LocaleDBは11言語をサポートしており、さらに追加する予定です。

サポートされている言語

英語、トルコ語、中国語、ヒンディー語、スペイン語、フランス語、アラビア語、ベンガル語、ポルトガル語、ロシア語、日本語

翻訳ファイル

すべての翻訳はmessages/{lang}.jsonファイルに保存されます

RTLサポート

アラビア語（ar）およびその他のRTL言語の完全な右から左へのサポート

新しい言語の追加

  1. 1新しいmessages/{lang}.jsonファイルを作成する
  2. 2messages/en.jsonからすべてのキーを翻訳する
  3. 3src/i18n/routing.tsにロケールコードを追加する
  4. 4npx tsx scripts/check-i18n.tsを実行して完全性を確認する