Руководство Разработчика

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

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

Обзор

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

250+ Стран

114 Языков

161 Валют

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

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

Всесторонние данные из авторитетных источников (CLDR, Всемирный банк, mledoze, libphonenumber, OpenFlights)
Статическая генерация - база данных времени выполнения не требуется
Лицензия 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 обрабатывает данные из нескольких авторитетных источников через многоступенчатый конвейер.

Внешние Источники

CLDR, mledoze, Всемирный банк, libphonenumber, OpenFlights (MWGG)

Скачать Исходные Данные

pnpm update:data скачивает файлы в подкаталоги data/

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

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

Обработка и Слияние

pnpm build:data объединяет источники с правилами приоритета

Сгенерированный JSON

Отдельные файлы стран, языков и валют

Генерация Статического Сайта

Next.js собирает более 5 868 статических страниц

Приоритет Источников Данных

Когда несколько источников предоставляют одно и то же поле, мы используем последовательную систему приоритетов:

•Названия стран: CLDR > mledoze > SimpleLocalize
•Население: Всемирный банк > mledoze > SimpleLocalize
•Данные о телефонах: 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.

Структура Проекта

Ключевые директории и их назначение.

localedb/
├── data/                    # Сгенерированные JSON файлы и исходные данные
│   ├── countries/           # 250 country JSON files
│   ├── languages/           # 114 language JSON files
│   ├── currencies/          # 161 currency JSON files
│   ├── _index_*.json        # Lightweight indices
│   └── _meta.json           # Build metadata
├── 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 языков

Справочник Скриптов

Доступные команды для управления данными и разработки.

Command	Description
`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Сделайте fork репозитория GitHub и клонируйте его на локальную машину
2Отредактируйте приоритет источника в build-data.ts или отправьте исправления в вышестоящие источники
3Добавьте переводы, отредактировав messages/{lang}.json и запустив check-i18n
4Отправьте Pull Request с одним изменением на PR и ссылками на официальные источники

Руководство

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

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

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

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

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

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

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

Поддержка RTL

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

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

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