nl_langinfo()

A função PHP nl_langinfo() retorna uma única informação específica de localidade — como o nome abreviado de um dia da semana, o formato de data local ou o símbolo de moeda — para a localidade atualmente ativa. É um invólucro fino em torno da função de biblioteca C de mesmo nome, portanto as strings exatas que ela retorna são determinadas pelo banco de dados de localidade do seu sistema operacional, e não pelo próprio PHP.

Esta página explica a sintaxe, as constantes de item mais úteis, como nl_langinfo() reage ao setlocale(), e as ressalvas de portabilidade que você deve conhecer antes de depender dela.

Sintaxe

string nl_langinfo ( int $item )

A função recebe um parâmetro, $item: uma constante inteira que nomeia a informação desejada. Ela retorna a string correspondente para a localidade selecionada atualmente, ou false se $item não for válido.

A ideia importante é que você passa a mesma constante independentemente do idioma. nl_langinfo(ABDAY_1) sempre solicita "o nome abreviado do primeiro dia da semana"; se você recebe Sun, Dim ou So depende inteiramente da localidade definida com setlocale(). É isso que torna a função útil: seu código permanece independente de idioma enquanto a saída se adapta.

Constantes de item comuns

As constantes são agrupadas por categoria. A maioria dos sistemas define estas; algumas são específicas de plataforma.

Nota: DAY_n e ABDAY_n são indexados a partir do domingo, portanto ABDAY_1 é domingo e ABDAY_7 é sábado.

Um exemplo básico

Aqui setlocale() ativa a localidade en_US, então nl_langinfo(ABDAY_1) lê o nome abreviado do primeiro dia da semana (domingo) para essa localidade.

A saída é:

Sun

Como a localidade altera o resultado

Como o valor de retorno acompanha a localidade ativa, alternar localidades entre chamadas fornece saída traduzida da mesma constante. As constantes nunca mudam — apenas o setlocale() muda.

<?php
// English
setlocale(LC_ALL, 'en_US.UTF-8');
echo nl_langinfo(MON_1), "\n";   // January

// French — same constant, French output
setlocale(LC_ALL, 'fr_FR.UTF-8');
echo nl_langinfo(MON_1), "\n";   // janvier

Saída esperada (quando ambas as localidades estão instaladas no sistema):

January
janvier

Se uma localidade não estiver instalada, setlocale() retorna false e a localidade anterior permanece em vigor, portanto você pode ver o idioma anterior repetido. Sempre verifique o valor de retorno de setlocale() no código de produção.

Lendo os formatos de data e moeda

Dois dos itens mais práticos são a string de formato de data/hora e a string de moeda. Você pode passar a string de formato diretamente para strftime():

<?php
setlocale(LC_ALL, 'en_US.UTF-8');

$fmt = nl_langinfo(D_T_FMT);      // locale's preferred date+time format
echo $fmt, "\n";                  // e.g. %a %d %b %Y %r %Z

echo nl_langinfo(CRNCYSTR), "\n"; // e.g. -$  (currency symbol + position flag)

O caractere inicial de CRNCYSTR indica onde o símbolo vai em relação ao número (- = antes, + = depois, . = no lugar do ponto decimal). Para formatação monetária completa, geralmente você vai querer localeconv() ou money_format(), que expõem cada detalhe numérico em vez de uma única string.

Portabilidade e ressalvas

• Não está disponível em todos os lugares. nl_langinfo() é indefinida no Windows e em builds do PHP compiladas sem suporte ao langinfo da biblioteca C. Use function_exists('nl_langinfo') se seu código precisar rodar de forma multiplataforma.
• A localidade deve estar realmente instalada. A constante é resolvida contra o banco de dados de localidade do SO; uma localidade não instalada silenciosamente mantém a anterior ativa.
• setlocale() primeiro. Sem um setlocale() explícito, você obtém o que a localidade padrão C/POSIX retorna — geralmente inglês simples sem formatações especiais.
• Constantes são inteiros, não strings. Escreva nl_langinfo(ABDAY_1), não nl_langinfo('ABDAY_1').

Funções relacionadas

• setlocale() — seleciona a localidade que nl_langinfo() lê.
• localeconv() — retorna regras de formatação numérica e monetária como um array.
• strftime() — formata uma data usando uma string de formato de localidade como a de D_T_FMT.
• money_format() — formata um número como moeda para a localidade ativa.

Prática