Guide du Développeur

Documentation

Tout ce que vous devez savoir sur les données, le pipeline et l'architecture de LocaleDB.

Vue d'ensemble

LocaleDB est une encyclopédie de localisation complète et open-source pour les développeurs créant des applications internationales.

250+ Pays

114 Langues

161 Devises

9,415 Aéroports

Caractéristiques Clés

Données complètes provenant de sources faisant autorité (CLDR, Banque Mondiale, mledoze, libphonenumber, OpenFlights)
Génération statique - aucune base de données d'exécution requise
Licencia MIT et piloté par la communauté
11 langues avec prise en charge RTL pour l'arabe

Commencer

Clonez le dépôt et commencez à explorer les données locales en quelques minutes.

# Cloner le dépôt
git clone https://github.com/ozkurkculer/localedb.git
cd localedb

# Installer les dépendances
pnpm install

# Télécharger les données brutes des sources
pnpm update:data

# Traiter et générer les fichiers JSON
pnpm build:data

# Démarrer le serveur de développement
pnpm dev

Pipeline de Données

LocaleDB traite les données de multiples sources faisant autorité via un pipeline à plusieurs étapes.

Sources Externes

CLDR, mledoze, Banque Mondiale, libphonenumber, OpenFlights (MWGG)

Télécharger les Données Brutes

pnpm update:data télécharge les fichiers dans les sous-répertoires data/

Fichiers de Données Brutes

Fichiers JSON, CSV et XML stockés dans data/

Traiter et Fusionner

pnpm build:data fusionne les sources avec des règles de priorité

JSON Généré

Fichiers individuels de pays, langue et devise

Génération de Site Statique

Next.js construit 5,868+ pages statiques

Priorité des Sources de Données

Lorsque plusieurs sources fournissent le même champ, nous utilisons un système de priorité cohérent :

•Noms de pays : CLDR > mledoze > SimpleLocalize
•Population : Banque Mondiale > mledoze > SimpleLocalize
•Données téléphoniques : libphonenumber XML (faisant autorité)

Schémas de Données

Structure détaillée des fichiers JSON de pays, langues et devises.

Schéma de Pays

data/countries/{CODE}.json

basics

Nom, capitale, coordonnées, continent, population, superficie, langues, emoji drapeau

codes

ISO 3166, BCP-47, FIFA, IOC, FIPS et autres codes internationaux

currency

Code, symbole, position, séparateurs, chiffres décimaux, modèle, exemple

dateTime

Formats date/heure (complet, long, moyen, court), premier jour de la semaine, fuseaux horaires

numberFormat

Séparateurs décimaux/milliers, groupement de chiffres, système de numération

phone

Indicatif, modèles, règles de formatage, longueurs de numéro d'abonné

addressFormat

Modèle de format, regex de code postal et exemple

locale

Direction d'écriture, système de mesure, échelle de température, taille de papier, côté de conduite

airports

Tableau d'aéroports avec IATA, ICAO, coordonnées, fuseau horaire

Schéma de Langue

data/languages/{code}.json

code

Code ISO 639-1

name

Nom anglais

nativeName

Nom natif

direction

Direction du texte (ltr ou rtl)

countries

Tableau des codes de pays où elle est parlée

Schéma de Devise

data/currencies/{CODE}.json

code

Code ISO 4217

name

Nom de la devise

symbol

Symbole de la devise

symbolPosition

avant ou après

separators

Séparateurs décimaux et de milliers

decimalDigits

Décimales standard

pattern

Modèle de formatage

example

Exemple formaté

countries

Tableau des codes de pays utilisant cette devise

Structure du Projet

Répertoires clés et leurs objectifs.

localedb/
├── data/                    # Fichiers JSON générés et données sources brutes
│   ├── countries/           # 250 country JSON files
│   ├── languages/           # 114 language JSON files
│   ├── currencies/          # 161 currency JSON files
│   ├── _index_*.json        # Lightweight indices
│   └── _meta.json           # Build metadata
├── scripts/                 # Scripts du pipeline de données (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/                # Fichiers de traduction pour 11 langues

Référence des Scripts

Commandes disponibles pour la gestion des données et le développement.

Command	Description
`pnpm update:data`	Télécharger les données brutes de toutes les sources externes
`pnpm update:data cldr worldbank`	Télécharger uniquement des sources spécifiques
`pnpm build:data`	Traiter les données brutes et générer les fichiers JSON
`pnpm dev`	Démarrer le serveur de développement
`pnpm build`	Build de production (Génération de Site Statique)
`npx tsx scripts/check-i18n.ts`	Vérifier et remplir automatiquement les clés de traduction manquantes
`pnpm version patch`	Incrémenter la version et générer automatiquement le journal des modifications

Contribuer aux Données

Comment contribuer des corrections et des améliorations à LocaleDB.

Flux de Travail de Contribution

1Forks le dépôt GitHub et clonez-le sur votre machine locale
2Modifiez la priorité des sources dans build-data.ts ou soumettez des corrections aux sources en amont
3Ajoutez des traductions en modifiant messages/{lang}.json et en exécutant check-i18n
4Soumettez une Pull Request avec un changement par PR et des liens vers les sources officielles

Directives

Un changement par Pull Request
Liez toujours aux sources officielles (CLDR, sites gouvernementaux, normes ISO)
Exécutez pnpm build:data pour vérifier que vos changements fusionnent correctement
Messages de commit clairs et descriptifs

Internationalisation

LocaleDB prend en charge 11 langues avec des plans pour plus.

Langues Prises en Charge

Anglais, Turc, Chinois, Hindi, Espagnol, Français, Arabe, Bengali, Portugais, Russe, Japonais

Fichiers de Traduction

Toutes les traductions sont stockées dans les fichiers messages/{lang}.json

Support RTL

Support complet de droite à gauche pour l'arabe (ar) et d'autres langues RTL

Ajouter une Nouvelle Langue

1Créez un nouveau fichier messages/{lang}.json
2Traduisez toutes les clés de messages/en.json
3Ajoutez le code régional à src/i18n/routing.ts
4Exécutez npx tsx scripts/check-i18n.ts pour vérifier l'exhaustivité