Developer Guide

Documentation

Everything you need to integrate LocaleDB into your applications.

Overview

LocaleDB is a comprehensive, open-source localization encyclopedia for developers building international applications.

250+ Countries

114 Languages

161 Currencies

9,415 Airports

Key Features

Comprehensive data from authoritative sources (CLDR, World Bank, mledoze, libphonenumber, OpenFlights)
Static generation - no runtime database required
MIT licensed and community-driven
11 languages with RTL support for Arabic

Getting Started

Clone the repository and start exploring locale data in minutes.

# Clone the repository
git clone https://github.com/ozkurkculer/localedb.git
cd localedb

# Install dependencies
pnpm install

# Download raw data from sources
pnpm update:data

# Process and generate JSON files
pnpm build:data

# Start development server
pnpm dev

Data Pipeline

LocaleDB processes data from multiple authoritative sources through a multi-stage pipeline.

External Sources

CLDR, mledoze, World Bank, libphonenumber, OpenFlights (MWGG)

Download Raw Data

pnpm update:data downloads files to data/ subdirectories

Raw Data Files

JSON, CSV, and XML files stored in data/

Process & Merge

pnpm build:data merges sources with priority rules

Generated JSON

Individual country, language, and currency files

Static Site Generation

Next.js builds 5,868+ static pages

Data Source Priority

When multiple sources provide the same field, we use a consistent priority system:

•Country names: CLDR > mledoze > SimpleLocalize
•Population: World Bank > mledoze > SimpleLocalize
•Phone data: libphonenumber XML (authoritative)

Data Schemas

Detailed structure of country, language, and currency JSON files.

Country Schema

data/countries/{CODE}.json

basics

Name, capital, coordinates, continent, population, area, languages, flagEmoji

codes

ISO 3166, BCP-47, FIFA, IOC, FIPS, and other international codes

currency

Code, symbol, position, separators, decimal digits, pattern, example

dateTime

Date/time formats (full, long, medium, short), first day of week, timezones

numberFormat

Decimal/thousands separators, digit grouping, numbering system

phone

Calling code, patterns, format rules, subscriber number lengths

addressFormat

Format template, postal code regex and example

locale

Writing direction, measurement system, temperature scale, paper size, driving side

airports

Array of airports with IATA, ICAO, coordinates, timezone

Language Schema

data/languages/{code}.json

code

ISO 639-1 code

name

English name

nativeName

Native name

direction

Text direction (ltr or rtl)

countries

Array of country codes where spoken

Currency Schema

data/currencies/{CODE}.json

code

ISO 4217 code

name

Currency name

symbol

Currency symbol

symbolPosition

before or after

separators

Decimal and thousands separators

decimalDigits

Standard decimal places

pattern

Formatting pattern

example

Formatted example

countries

Array of country codes using this currency

Project Structure

Key directories and their purposes.

localedb/
├── data/                    # Generated JSON files and raw source data
│   ├── countries/           # 250 country JSON files
│   ├── languages/           # 114 language JSON files
│   ├── currencies/          # 161 currency JSON files
│   ├── _index_*.json        # Lightweight indices
│   └── _meta.json           # Build metadata
├── scripts/                 # Data pipeline 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/                # Translation files for 11 languages

Scripts Reference

Available commands for data management and development.

Command	Description
`pnpm update:data`	Download raw data from all external sources
`pnpm update:data cldr worldbank`	Download specific sources only
`pnpm build:data`	Process raw data and generate JSON files
`pnpm dev`	Start development server
`pnpm build`	Production build (Static Site Generation)
`npx tsx scripts/check-i18n.ts`	Check and auto-fill missing translation keys
`pnpm version patch`	Bump version and auto-generate changelog

Contributing Data

How to contribute corrections and improvements to LocaleDB.

Contribution Workflow

1Fork the GitHub repository and clone to your local machine
2Edit source priority in build-data.ts or submit corrections to upstream sources
3Add translations by editing messages/'{lang}'.json and running check-i18n
4Submit a Pull Request with one change per PR and links to official sources

Guidelines

One change per Pull Request
Always link to official sources (CLDR, government sites, ISO standards)
Run pnpm build:data to verify your changes merge correctly
Clear, descriptive commit messages

Internationalization

LocaleDB supports 11 languages with plans for more.

Supported Languages

English, Turkish, Chinese, Hindi, Spanish, French, Arabic, Bengali, Portuguese, Russian, Japanese

Translation Files

All translations are stored in messages/{lang}.json files

RTL Support

Full right-to-left support for Arabic (ar) and other RTL languages

Adding a New Language

1Create a new messages/'{lang}'.json file
2Translate all keys from messages/en.json
3Add the locale code to src/i18n/routing.ts
4Run npx tsx scripts/check-i18n.ts to verify completeness