دليل المطور

الوثائق

كل ما تحتاج لمعرفته حول بيانات LocaleDB وخط الأنابيب والهندسة المعمارية.

نظرة عامة

LocaleDB عبارة عن موسوعة توطين شاملة ومفتوحة المصدر للمطورين الذين يبنون تطبيقات دولية.

250+ دولة

114 لغة

161 عملة

9,415 مطار

الميزات الرئيسية

بيانات شاملة من مصادر موثوقة (CLDR، البنك الدولي، mledoze، libphonenumber، OpenFlights)
توليد ثابت - لا توجد قاعدة بيانات وقت التشغيل مطلوبة
مرخصة بموجب MIT ومدفوعة بالمجتمع
11 لغة مع دعم من اليمين إلى اليسار للغة العربية

البدء

استنسخ المستودع وابدأ في استكشاف البيانات المحلية في دقائق.

# استنسخ المستودع
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أرسل طلب سحب (PR) بتغيير واحد لكل طلب وروابط للمصادر الرسمية

الإرشادات

تغيير واحد لكل طلب سحب
اربط دائمًا بالمصادر الرسمية (CLDR، المواقع الحكومية، معايير ISO)
شغل pnpm build:data للتحقق من دمج تغييراتك بشكل صحيح
رسائل التزام (commit) واضحة ووصفية

التدويل (i18n)

يدعم 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 للتحقق من الاكتمال