O que é Intl API e Por Que Importa
A Intl API é um objeto global do JavaScript que fornece funcionalidades de internacionalização (i18n) nativa, permitindo formatar números, datas, moedas e realizar comparações de strings respeitando as convenções de cada localidade. Diferentemente de bibliotecas externas, ela vem integrada aos navegadores modernos e ambientes Node.js, oferecendo suporte a centenas de idiomas e regiões sem dependências adicionais.
Em aplicações globais, ignorar i18n resulta em experiências confusas para usuários. Um americano espera ver $1,234.56, enquanto um brasileiro espera R$ 1.234,56. A Intl API resolve isso automaticamente, detectando a localidade do sistema ou permitindo especificar manualmente.
Intl.NumberFormat: Formatando Números e Moedas
Intl.NumberFormat é seu aliado principal para exibir números de forma culturalmente apropriada. Ele formata inteiros, decimais e moedas conforme as regras de cada região.
// Números simples em diferentes locales
const numberBR = new Intl.NumberFormat('pt-BR');
const numberUS = new Intl.NumberFormat('en-US');
console.log(numberBR.format(1234567.89)); // 1.234.567,89
console.log(numberUS.format(1234567.89)); // 1,234,567.89
// Formatando moedas
const currencyBR = new Intl.NumberFormat('pt-BR', {
style: 'currency',
currency: 'BRL'
});
const currencyUS = new Intl.NumberFormat('en-US', {
style: 'currency',
currency: 'USD'
});
console.log(currencyBR.format(99.99)); // R$ 99,99
console.log(currencyUS.format(99.99)); // $99.99
// Porcentagens
const percentage = new Intl.NumberFormat('pt-BR', {
style: 'percent',
minimumFractionDigits: 2
});
console.log(percentage.format(0.8534)); // 85,34%
A chave está nos options: style define o tipo (currency, percent ou decimal), currency especifica a moeda, e minimumFractionDigits controla casas decimais. Isso elimina manipulação manual de strings e garante conformidade automática com padrões regionais.
Intl.DateTimeFormat: Datas e Horas Localizadas
Datas são ainda mais sensíveis culturalmente. Intl.DateTimeFormat adapta formato, ordem de componentes e nomes de meses/dias conforme a localidade.
const data = new Date('2024-12-25T14:30:00');
// Formato longo em português
const formatBR = new Intl.DateTimeFormat('pt-BR', {
weekday: 'long',
year: 'numeric',
month: 'long',
day: 'numeric',
hour: '2-digit',
minute: '2-digit'
});
console.log(formatBR.format(data));
// quarta-feira, 25 de dezembro de 2024, 14:30
// Formato compacto em inglês
const formatUS = new Intl.DateTimeFormat('en-US', {
month: 'short',
day: 'numeric',
year: '2-digit'
});
console.log(formatUS.format(data));
// Dec 25, 24
// Apenas hora em diferentes zonas
const timeZone = new Intl.DateTimeFormat('pt-BR', {
timeZone: 'America/Sao_Paulo',
hour: '2-digit',
minute: '2-digit',
second: '2-digit'
});
console.log(timeZone.format(data)); // 11:30:00 (UTC-3)
Repare que você não concatena strings ou manipula índices: o próprio Intl cuida da ordem, nomes traduzidos e até conversão de fusos horários. Usar timeZone é essencial em aplicações com usuários distribuídos globalmente.
Intl.Collator: Comparação de Strings com Sensibilidade Cultural
Para buscar, ordenar ou comparar texto, Intl.Collator implementa as regras de cada idioma. Em alguns idiomas, acentuação importa; em outros, maiúsculas/minúsculas têm peso diferente.
// Ordenação em português
const collatorPT = new Intl.Collator('pt-BR');
const palavras = ['ação', 'acção', 'açúcar', 'aca'];
console.log(palavras.sort(collatorPT.compare));
// ['aca', 'ação', 'açúcar', 'acção']
// Comparação sensível a case
const collatorCase = new Intl.Collator('pt-BR', {
sensitivity: 'case'
});
console.log(collatorCase.compare('a', 'A')); // -1 (a < A)
// Sem sensibilidade a diacríticos
const collatorBase = new Intl.Collator('pt-BR', {
sensitivity: 'base'
});
console.log(collatorBase.compare('café', 'cafe')); // 0 (iguais)
// Ordenação ignorando símbolos
const textos = ['zebra', '$apple', '@banana'];
const collatorIgnore = new Intl.Collator('en-US', {
ignorePunctuation: true
});
console.log(textos.sort(collatorIgnore.compare));
// ['$apple', '@banana', 'zebra']
O método compare() retorna -1, 0 ou 1, compatível com Array.sort(). As opções sensitivity (base, accent, case, variant) e ignorePunctuation controlam o nível de rigor na comparação, adaptando-se ao seu caso de uso.
Dicas Práticas e Detecção de Localidade
Sempre detecte a localidade do usuário antes de formatar. Use navigator.language no navegador ou process.env.LC_ALL no Node.js como fallback.
// Detectar localidade do usuário
const userLocale = navigator.language || 'en-US';
// Usar em um helper reutilizável
function formatarMoeda(valor, moeda = 'BRL') {
return new Intl.NumberFormat(userLocale, {
style: 'currency',
currency: moeda
}).format(valor);
}
function formatarData(data) {
return new Intl.DateTimeFormat(userLocale, {
year: 'numeric',
month: 'long',
day: 'numeric'
}).format(data);
}
// Uso
console.log(formatarMoeda(150.50));
console.log(formatarData(new Date()));
Criar funções reutilizáveis reduz repetição de código e centraliza mudanças de formato. Se precisar suportar múltiplas moedas ou zonas, considere guardar essas preferências em um contexto (React) ou variável global (vanilla JS).
Conclusão
A Intl API elimina o trabalho manual de i18n, oferecendo três takeaways essenciais: (1) NumberFormat padroniza exibição de números e moedas conforme a cultura local, garantindo confiança do usuário em transações. (2) DateTimeFormat adapta datas, horas e fusos automaticamente, crítico em aplicações globais. (3) Collator implementa ordenação e comparação semanticamente correta, fundamental para buscas e filtros em idiomas com regras complexas.
Domine esses três objetos e sua aplicação será genuinamente internacional, sem dependências externas e com performance nativa.