Guia do Desenvolvedor

Documentação

Tudo o que você precisa saber sobre os dados, pipeline e arquitetura do LocaleDB.

Visão Geral

LocaleDB é uma enciclopédia de localização abrangente e de código aberto para desenvolvedores que criam aplicativos internacionais.

250+ Países

114 Idiomas

161 Moedas

9,415 Aeroportos

Recursos Principais

Dados abrangentes de fontes autorizadas (CLDR, Banco Mundial, mledoze, libphonenumber, OpenFlights)
Geração estática - banco de dados em tempo de execução não necessário
Licença MIT e impulsionado pela comunidade
11 idiomas com suporte RTL para árabe

Começando

Clone o repositório e comece a explorar dados de localidade em minutos.

# Clonar o repositório
git clone https://github.com/ozkurkculer/localedb.git
cd localedb

# Instalar dependências
pnpm install

# Baixar dados brutos das fontes
pnpm update:data

# Processar e gerar arquivos JSON
pnpm build:data

# Iniciar servidor de desenvolvimento
pnpm dev

Pipeline de Dados

O LocaleDB processa dados de múltiplas fontes autorizadas através de um pipeline de vários estágios.

Fontes Externas

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

Baixar Dados Brutos

pnpm update:data baixa arquivos para subdiretórios data/

Arquivos de Dados Brutos

Arquivos JSON, CSV e XML armazenados em data/

Processar e Mesclar

pnpm build:data mescla fontes com regras de prioridade

JSON Gerado

Arquivos individuais de país, idioma e moeda

Geração de Site Estático

Next.js compila mais de 5.868 páginas estáticas

Prioridade da Fonte de Dados

Quando múltiplas fontes fornecem o mesmo campo, usamos um sistema de prioridade consistente:

•Nomes de países: CLDR > mledoze > SimpleLocalize
•População: Banco Mundial > mledoze > SimpleLocalize
•Dados de telefone: libphonenumber XML (autoritativo)

Esquemas de Dados

Estrutura detalhada dos arquivos JSON de país, idioma e moeda.

Esquema de País

data/countries/{CODE}.json

basics

Nome, capital, coordenadas, continente, população, área, idiomas, emoji da bandeira

codes

ISO 3166, BCP-47, FIFA, IOC, FIPS e outros códigos internacionais

currency

Código, símbolo, posição, separadores, dígitos decimais, padrão, exemplo

dateTime

Formatos de data/hora (completo, longo, médio, curto), primeiro dia da semana, fusos horários

numberFormat

Separadores decimais/milhares, agrupamento de dígitos, sistema de numeração

phone

Código de chamada, padrões, regras de formato, comprimentos de número de assinante

addressFormat

Modelo de formato, regex de código postal e exemplo

locale

Direção de escrita, sistema de medição, escala de temperatura, tamanho de papel, lado de condução

airports

Array de aeroportos com IATA, ICAO, coordenadas, fuso horário

Esquema de Idioma

data/languages/{code}.json

code

Código ISO 639-1

name

Nome em inglês

nativeName

Nome nativo

direction

Direção do texto (ltr ou rtl)

countries

Array de códigos de países onde é falado

Esquema de Moeda

data/currencies/{CODE}.json

code

Código ISO 4217

name

Nome da moeda

symbol

Símbolo da moeda

symbolPosition

antes ou depois

separators

Separadores decimais e de milhares

decimalDigits

Casas decimais padrão

pattern

Padrão de formatação

example

Exemplo formatado

countries

Array de códigos de países que usam esta moeda

Estrutura do Projeto

Diretórios principais e seus propósitos.

localedb/
├── data/                    # Arquivos JSON gerados e dados de fonte bruta
│   ├── 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 do pipeline de dados (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/                # Arquivos de tradução para 11 idiomas

Referência de Scripts

Comandos disponíveis para gerenciamento de dados e desenvolvimento.

Command	Description
`pnpm update:data`	Baixar dados brutos de todas as fontes externas
`pnpm update:data cldr worldbank`	Baixar apenas fontes específicas
`pnpm build:data`	Processar dados brutos e gerar arquivos JSON
`pnpm dev`	Iniciar servidor de desenvolvimento
`pnpm build`	Build de produção (Geração de Site Estático)
`npx tsx scripts/check-i18n.ts`	Verificar e preencher automaticamente chaves de tradução ausentes
`pnpm version patch`	Aumentar versão e gerar changelog automaticamente

Contribuindo Dados

Como contribuir com correções e melhorias para o LocaleDB.

Fluxo de Trabalho de Contribuição

1Faça um fork do repositório GitHub e clone para sua máquina local
2Edite a prioridade da fonte em build-data.ts ou envie correções para as fontes upstream
3Adicione traduções editando messages/{lang}.json e executando check-i18n
4Envie um Pull Request com uma mudança por PR e links para fontes oficiais

Diretrizes

Uma mudança por Pull Request
Sempre link para fontes oficiais (CLDR, sites governamentais, padrões ISO)
Execute pnpm build:data para verificar se suas alterações são mescladas corretamente
Mensagens de commit claras e descritivas

Internacionalização

O LocaleDB suporta 11 idiomas com planos para mais.

Idiomas Suportados

Inglês, Turco, Chinês, Hindi, Espanhol, Francês, Árabe, Bengali, Português, Russo, Japonês

Arquivos de Tradução

Todas as traduções são armazenadas em arquivos messages/{lang}.json

Suporte RTL

Suporte total da direita para a esquerda para Árabe (ar) e outros idiomas RTL

Adicionando um Novo Idioma

1Crie um novo arquivo messages/{lang}.json
2Traduza todas as chaves de messages/en.json
3Adicione o código de localidade em src/i18n/routing.ts
4Execute npx tsx scripts/check-i18n.ts para verificar a integridade