Dokümantasyon

LocaleDB'yi uygulamalarınıza entegre etmek için ihtiyacınız olan her şey.

Genel Bakış

LocaleDB, uluslararası uygulamalar geliştiren yazılımcılar için kapsamlı, açık kaynaklı bir yerelleştirme ansiklopedisidir.

250+ Ülke

100+ Dil

150+ Para Birimi

9,415 Havalimanı

Temel Özellikler

Yetkili kaynaklardan kapsamlı veriler (CLDR, Dünya Bankası, mledoze, libphonenumber, IANA tz, libaddressinput, Wikidata, mwgg/Airports)
Statik oluşturma - çalışma zamanı veritabanı gerekmez
MIT lisanslı ve topluluk odaklı
Arapça için RTL desteği ile 11 dil

Başlarken

Depoyu klonlayın ve dakikalar içinde yerel verileri keşfetmeye başlayın.

# Depoyu klonlayın
git clone https://github.com/ozkurkculer/localedb.git
cd localedb

# Bağımlılıkları yükleyin
pnpm install

# Kaynaklardan ham verileri indirin
pnpm update:data

# İşleyin ve JSON dosyalarını oluşturun
pnpm build:data

# Geliştirme sunucusunu başlatın
pnpm dev

Veri Hattı

LocaleDB, birden fazla yetkili kaynaktan gelen verileri çok aşamalı bir işlem hattıyla işler.

Harici Kaynaklar

CLDR, mledoze, Dünya Bankası, libphonenumber, IANA tz, libaddressinput, Wikidata, mwgg/Airports, IP2Location

Ham Veriyi İndir

pnpm update:data dosyaları data/ alt dizinlerine indirir

Ham Veri Dosyaları

data/ içinde saklanan JSON, CSV ve XML dosyaları

İşle & Birleştir

pnpm build:data kaynakları öncelik kurallarıyla birleştirir

Oluşturulan JSON

Bireysel ülke, dil ve para birimi dosyaları

Statik Site Oluşturma

Next.js 5.868+ statik sayfa oluşturur

Veri Kaynağı Önceliği

Birden fazla kaynak aynı alanı sağladığında, tutarlı bir öncelik sistemi kullanırız:

•Ülke adları: CLDR > mledoze
•Nüfus: Dünya Bankası > CLDR
•Telefon verileri: libphonenumber XML (yetkili)

Veri Şemaları

Ülke, dil ve para birimi JSON dosyalarının ayrıntılı yapısı.

Ülke Şeması

data/countries/{CODE}.json

basics

İsim, başkent, koordinatlar, kıta, nüfus, yüzölçümü, diller, bayrak emojisi

codes

ISO 3166, BCP-47, FIFA, IOC, FIPS ve diğer uluslararası kodlar

currency

Kod, sembol, konum, ayırıcılar, ondalık basamaklar, desen, örnek

dateTime

Tarih/saat formatları (tam, uzun, orta, kısa), haftanın ilk günü, saat dilimleri

numberFormat

Ondalık/binlik ayırıcılar, basamak gruplama, numaralandırma sistemi

phone

Ülke kodu, desenler, format kuralları, abone numarası uzunlukları

addressFormat

Format şablonu, posta kodu regex ve örneği

locale

Yazım yönü, ölçüm sistemi, sıcaklık ölçeği, kağıt boyutu, sürüş tarafı

airports

IATA, ICAO, koordinatlar, saat dilimi ile havalimanları dizisi

Dil Şeması

data/languages/{code}.json

code

ISO 639-1 kodu

name

İngilizce adı

nativeName

Yerel adı

direction

Metin yönü (ltr veya rtl)

countries

Konuşulduğu ülke kodları dizisi

Para Birimi Şeması

data/currencies/{CODE}.json

code

ISO 4217 kodu

name

Para birimi adı

symbol

Para birimi sembolü

symbolPosition

önce veya sonra

separators

Ondalık ve binlik ayırıcılar

decimalDigits

Standart ondalık basamaklar

pattern

Biçimlendirme deseni

example

Biçimlendirilmiş örnek

countries

Bu para birimini kullanan ülke kodları dizisi

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 Paketleri ve CLI

LocaleDB'yi kendi kodunda kullan: tipli, internet gerektirmeyen bir kütüphane ve seçtiğin veriyi projene yazan bir komut satırı aracı.

Beta: API'ler 1.0'dan önce değişebilir.

@localedb/core

Tüm veri setleri Node.js için tipli ve senkron fonksiyonlar olarak. Tarayıcıda tek tek kayıtları @localedb/core/data/* yolundan JSON olarak içe aktarabilirsin.

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 komutu. init neye ihtiyacın olduğunu sorar ve JSON, CSV ya da tipli TypeScript dosyaları üretir; sync bunları güncel tutar.

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

getTek bir kaydı JSON olarak yazdırır
exportKayıtları JSON, CSV veya TypeScript olarak terminale, bir dosyaya ya da kayıt başına ayrı dosyalara aktarır
listBir veri setini tablo ya da JSON olarak listeler
searchÜlkeleri koda veya isme göre bulur
initlocaledb.config.json dosyasını adım adım oluşturur ve dosyaları üretir
syncConfig'teki dosyaları yeniden üretir; --check güncel olmayan dosyalarda CI'ı durdurur

Kod MIT lisanslıdır. Paketle gelen veri kaynaklarının lisanslarını korur, bazıları benzer şekilde paylaşım şartlıdır; ayrıntılar paketteki NOTICE dosyasında.

Proje Yapısı

Önemli dizinler ve amaçları.

localedb/
├── data/                    # Oluşturulan JSON dosyaları ve ham kaynak veriler
│   ├── 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/                 # Veri hattı komut dosyaları (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 dil için çeviri dosyaları

Komut Dosyası Referansı

Veri yönetimi ve geliştirme için mevcut komutlar.

Command	Description
`pnpm update:data`	Tüm harici kaynaklardan ham verileri indir
`pnpm update:data cldr worldbank`	Yalnızca belirli kaynakları indir
`pnpm build:data`	Ham verileri işle ve JSON dosyalarını oluştur
`pnpm dev`	Geliştirme sunucusunu başlat
`pnpm build`	Üretim derlemesi (Statik Site Oluşturma)
`npx tsx scripts/check-i18n.ts`	Eksik çeviri anahtarlarını kontrol et ve otomatik doldur
`pnpm version patch`	Sürümü yükselt ve otomatik değişiklik günlüğü oluştur

Veri Katkısı

LocaleDB'ye düzeltmeler ve iyileştirmeler nasıl katkıda bulunulur.

Katkı İş Akışı

1GitHub deposunu çatallayın (fork) ve yerel makinenize klonlayın
2build-data.ts'deki kaynak önceliğini düzenleyin veya kaynaklara düzeltmeler gönderin
3messages/'{lang}'.json dosyasını düzenleyerek ve check-i18n çalıştırarak çeviriler ekleyin
4Her PR için bir değişiklik ve resmi kaynaklara bağlantılarla bir Pull Request gönderin

Kurallar

Pull Request başına bir değişiklik
Her zaman resmi kaynaklara bağlantı verin (CLDR, devlet siteleri, ISO standartları)
Değişikliklerin doğru birleştirildiğini doğrulamak için pnpm build:data çalıştırın
Açık, açıklayıcı taahhüt (commit) mesajları

Uluslararasılaştırma

LocaleDB 11 dili destekler ve daha fazlası planlanmaktadır.

Desteklenen Diller

İngilizce, Türkçe, Çince, Hintçe, İspanyolca, Fransızca, Arapça, Bengalce, Portekizce, Rusça, Japonca

Çeviri Dosyaları

Tüm çeviriler messages/{lang}.json dosyalarında saklanır

RTL Desteği

Arapça (ar) ve diğer RTL dilleri için tam sağdan sola desteği

Yeni Dil Ekleme

1Yeni bir messages/'{lang}'.json dosyası oluşturun
2messages/en.json'daki tüm anahtarları çevirin
3src/i18n/routing.ts dosyasına yerel ayar kodunu ekleyin
4Tamamlandığını doğrulamak için npx tsx scripts/check-i18n.ts çalıştırın