Guía del Desarrollador

Documentación

Todo lo que necesitas saber sobre los datos, el pipeline y la arquitectura de LocaleDB.

Descripción General

LocaleDB es una enciclopedia de localización completa y de código abierto para desarrolladores que crean aplicaciones internacionales.

250+ Países

114 Idiomas

161 Monedas

9,415 Aeropuertos

Características Principales

Datos completos de fuentes autorizadas (CLDR, Banco Mundial, mledoze, libphonenumber, OpenFlights)
Generación estática - no requiere base de datos en tiempo de ejecución
Licencia MIT e impulsado por la comunidad
11 idiomas con soporte RTL para árabe

Empezando

Clone el repositorio y comience a explorar los datos de localización en minutos.

# Clonar el repositorio
git clone https://github.com/ozkurkculer/localedb.git
cd localedb

# Instalar dependencias
pnpm install

# Descargar datos sin procesar de las fuentes
pnpm update:data

# Procesar y generar archivos JSON
pnpm build:data

# Iniciar servidor de desarrollo
pnpm dev

Pipeline de Datos

LocaleDB procesa datos de múltiples fuentes autorizadas a través de un pipeline de varias etapas.

Fuentes Externas

CLDR, mledoze, Banco Mundial, libphonenumber, OpenFlights (MWGG)

Descargar Datos Crudos

pnpm update:data descarga archivos a subdirectorios data/

Archivos de Datos Crudos

Archivos JSON, CSV y XML almacenados en data/

Procesar y Fusionar

pnpm build:data fusiona fuentes con reglas de prioridad

JSON Generado

Archivos individuales de país, idioma y moneda

Generación de Sitio Estático

Next.js construye 5,868+ páginas estáticas

Prioridad de Fuente de Datos

Cuando múltiples fuentes proporcionan el mismo campo, utilizamos un sistema de prioridad consistente:

•Nombres de países: CLDR > mledoze > SimpleLocalize
•Población: Banco Mundial > mledoze > SimpleLocalize
•Datos telefónicos: libphonenumber XML (autorizado)

Esquemas de Datos

Estructura detallada de los archivos JSON de países, idiomas y monedas.

Esquema de País

data/countries/{CODE}.json

basics

Nombre, capital, coordenadas, continente, población, área, idiomas, emoji de bandera

codes

ISO 3166, BCP-47, FIFA, IOC, FIPS y otros códigos internacionales

currency

Código, símbolo, posición, separadores, dígitos decimales, patrón, ejemplo

dateTime

Formatos de fecha/hora (completo, largo, medio, corto), primer día de la semana, zonas horarias

numberFormat

Separadores decimales/miles, agrupación de dígitos, sistema de numeración

phone

Código de llamada, patrones, reglas de formato, longitudes de número de suscriptor

addressFormat

Plantilla de formato, expresión regular de código postal y ejemplo

locale

Dirección de escritura, sistema de medición, escala de temperatura, tamaño de papel, lado de conducción

airports

Matriz de aeropuertos con IATA, ICAO, coordenadas, zona horaria

Esquema de Idioma

data/languages/{code}.json

code

Código ISO 639-1

name

Nombre en inglés

nativeName

Nombre nativo

direction

Dirección del texto (ltr o rtl)

countries

Matriz de códigos de países donde se habla

Esquema de Moneda

data/currencies/{CODE}.json

code

Código ISO 4217

name

Nombre de la moneda

symbol

Símbolo de la moneda

symbolPosition

antes o después

separators

Separadores decimales y de miles

decimalDigits

Lugares decimales estándar

pattern

Patrón de formato

example

Ejemplo formateado

countries

Matriz de códigos de países que usan esta moneda

Estructura del Proyecto

Directorios clave y sus propósitos.

localedb/
├── data/                    # Archivos JSON generados y datos fuente sin procesar
│   ├── 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 del pipeline de datos (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/                # Archivos de traducción para 11 idiomas

Referencia de Scripts

Comandos disponibles para gestión de datos y desarrollo.

Command	Description
`pnpm update:data`	Descargar datos sin procesar de todas las fuentes externas
`pnpm update:data cldr worldbank`	Descargar solo fuentes específicas
`pnpm build:data`	Procesar datos sin procesar y generar archivos JSON
`pnpm dev`	Iniciar servidor de desarrollo
`pnpm build`	Construcción de producción (Generación de Sitio Estático)
`npx tsx scripts/check-i18n.ts`	Verificar y autocompletar claves de traducción faltantes
`pnpm version patch`	Incrementar versión y generar registro de cambios automáticamente

Contribuir Datos

Cómo contribuir correcciones y mejoras a LocaleDB.

Flujo de Trabajo de Contribución

1Hacer Fork del repositorio de GitHub y clonarlo en su máquina local
2Editar prioridad de fuente en build-data.ts o enviar correcciones a fuentes originales
3Agregar traducciones editando messages/{lang}.json y ejecutando check-i18n
4Enviar un Pull Request con un cambio por PR y enlaces a fuentes oficiales

Directrices

Un cambio por Pull Request
Siempre enlace a fuentes oficiales (CLDR, sitios gubernamentales, estándares ISO)
Ejecute pnpm build:data para verificar que sus cambios se fusionen correctamente
Mensajes de commit claros y descriptivos

Internacionalización

LocaleDB soporta 11 idiomas con planes para más.

Idiomas Soportados

Inglés, Turco, Chino, Hindi, Español, Francés, Árabe, Bengalí, Portugués, Ruso, Japonés

Archivos de Traducción

Todas las traducciones se almacenan en archivos messages/{lang}.json

Soporte RTL

Soporte completo de derecha a izquierda para árabe (ar) y otros idiomas RTL

Agregar un Nuevo Idioma

1Crear un nuevo archivo messages/{lang}.json
2Traducir todas las claves de messages/en.json
3Agregar el código de configuración regional a src/i18n/routing.ts
4Ejecutar npx tsx scripts/check-i18n.ts para verificar integridad