Command Palette

Search for a command to run...

Документация

Все, что вам нужно знать о данных, конвейере и архитектуре LocaleDB.

Обзор

LocaleDB — это всеобъемлющая энциклопедия локализации с открытым исходным кодом для разработчиков, создающих международные приложения.

250+ Стран

100+ Языков

150+ Валют

9,415 Аэропортов

Ключевые Особенности

  • Всесторонние данные из авторитетных источников (CLDR, Всемирный банк, mledoze, libphonenumber, IANA tz, libaddressinput, Wikidata, mwgg/Airports)
  • Статическая генерация - база данных времени выполнения не требуется
  • Лицензия MIT и управление сообществом
  • 11 языков с поддержкой RTL для арабского

Начало Работы

Клонируйте репозиторий и начните изучать данные локали за считанные минуты.

# Клонировать репозиторий
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

Файлы Исходных Данных

Файлы JSON, CSV и XML, хранящиеся в data/

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 в своём коде: типизированная библиотека, работающая офлайн, и инструмент командной строки, который записывает выбранные данные в ваш проект.

Бета: API может измениться до версии 1.0.

@localedb/core

Все наборы данных в виде типизированных синхронных функций для Node.js. В браузере импортируйте отдельные записи в формате JSON из @localedb/core/data/*.

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
  • getВыводит одну запись в формате JSON
  • exportЭкспортирует записи в JSON, CSV или TypeScript: в стандартный вывод, в файл или по файлу на запись
  • listВыводит набор данных таблицей или в JSON
  • searchИщет страны по коду или названию
  • initПошагово создаёт localedb.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. 1Сделайте fork репозитория GitHub и клонируйте его на локальную машину
  2. 2Отредактируйте приоритет источника в build-data.ts или отправьте исправления в вышестоящие источники
  3. 3Добавьте переводы, отредактировав messages/{lang}.json и запустив check-i18n
  4. 4Отправьте Pull Request с одним изменением на PR и ссылками на официальные источники

Руководство

  • Одно изменение на Pull Request
  • Всегда ссылайтесь на официальные источники (CLDR, правительственные сайты, стандарты ISO)
  • Запустите pnpm build:data, чтобы проверить правильность слияния ваших изменений
  • Понятные и описательные сообщения коммитов

Интернационализация

LocaleDB поддерживает 11 языков и планирует поддерживать больше.

Поддерживаемые Языки

Английский, Турецкий, Китайский, Хинди, Испанский, Французский, Арабский, Бенгальский, Португальский, Русский, Японский

Файлы Переводов

Все переводы хранятся в файлах messages/{lang}.json

Поддержка RTL

Полная поддержка письма справа налево для Арабского (ar) и других RTL языков

Добавление Нового Языка

  1. 1Создайте новый файл messages/{lang}.json
  2. 2Переведите все ключи из messages/en.json
  3. 3Добавьте код локали в src/i18n/routing.ts
  4. 4Запустите npx tsx scripts/check-i18n.ts для проверки полноты