Geliştirici Rehberi

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

114 Dil

161 Para Birimi

9,415 Havalimanı

Temel Özellikler

Yetkili kaynaklardan kapsamlı veriler (CLDR, Dünya Bankası, mledoze, libphonenumber, OpenFlights)
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, OpenFlights (MWGG)

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 > SimpleLocalize
•Nüfus: Dünya Bankası > mledoze > SimpleLocalize
•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

Proje Yapısı

Önemli dizinler ve amaçları.

localedb/
├── data/                    # Oluşturulan JSON dosyaları ve ham kaynak veriler
│   ├── countries/           # 250 country JSON files
│   ├── languages/           # 114 language JSON files
│   ├── currencies/          # 161 currency JSON files
│   ├── _index_*.json        # Lightweight indices
│   └── _meta.json           # Build metadata
├── 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