setlocale()

A função PHP setlocale() define a localidade atual de um script — o conjunto de regras culturais que determinam como o texto é ordenado, como números e moedas são formatados e como datas são escritas. Uma localidade é identificada por uma string como en_US (inglês americano) ou de_DE (alemão), geralmente combinada com uma codificação de caracteres como .utf8.

Você usa setlocale() sempre que uma única base de código precisa produzir saída que "pareça nativa" em mais de um país: 1,234.56 para um usuário americano, mas 1.234,56 para um alemão, January versus Januar, e assim por diante.

Sintaxe

setlocale(int $category, string $locale, string ...$locales): string|false

Também pode aceitar um único array de localidades em vez de uma lista:

setlocale(int $category, array $locale): string|false

Parâmetros

• $category — qual grupo de comportamento dependente de localidade deve ser alterado. Passe uma das constantes LC_*:

  Constante	Afeta
  LC_ALL	Todas as categorias ao mesmo tempo
  LC_COLLATE	Comparação e ordenação de strings (veja strcoll())
  LC_CTYPE	Classificação de caracteres e conversão de maiúsculas/minúsculas
  LC_MONETARY	Formatação de moeda (veja money_format())
  LC_NUMERIC	Separador decimal para números
  LC_TIME	Formatação de data e hora (veja strftime())
  LC_MESSAGES	Formatação de mensagens do sistema (não disponível no Windows)

• $locale — a string de localidade a ser aplicada, ex.: 'en_US.utf8'. Três valores especiais são úteis:

  • "" (string vazia) — usa a localidade das variáveis de ambiente do servidor.
  • "0" — não altera nada; apenas retorna a configuração atual para aquela categoria.
  • null — mesmo que "0".

• ...$locales — alternativas opcionais. O PHP tenta cada nome em ordem e aplica o primeiro que o sistema operacional tiver instalado.

Retorna o nome da localidade definida em caso de sucesso, ou false se nenhuma das localidades solicitadas estiver disponível.

Exemplo básico

<?php
$result = setlocale(LC_ALL, 'en_US.utf8');

if ($result !== false) {
    echo "Locale set to: $result";
} else {
    echo "Requested locale is not installed.";
}
?>

setlocale() retorna a nova string de localidade em caso de sucesso ou false em caso de falha, portanto sempre verifique o valor de retorno — uma localidade ausente falha silenciosamente e deixa sua formatação incorreta em vez de lançar um erro.

Fornecendo alternativas

Os nomes de localidade diferem entre sistemas operacionais (en_US.utf8 no Linux, English_United States.1252 no Windows). Listar vários nomes permite que o mesmo script funcione em qualquer lugar — o PHP usa a primeira correspondência instalada:

<?php
$locale = setlocale(
    LC_ALL,
    'en_US.UTF-8',                 // Linux / macOS
    'en_US.utf8',
    'English_United States.1252'   // Windows
);

echo $locale ?: 'No English locale available';
?>

Por que a localidade importa: formatação de números

Após definir LC_NUMERIC (ou LC_ALL), as funções que respeitam a localidade produzem saída específica de cada cultura. Aqui, os separadores decimal e de milhares seguem as convenções alemãs:

<?php
setlocale(LC_ALL, 'de_DE.utf8', 'de_DE', 'German_Germany.1252');

$info = localeconv();
echo $info['decimal_point'];   // ,
echo "\n";
echo $info['thousands_sep'];   // .
?>

localeconv() lê de volta as regras numéricas e monetárias da localidade ativa, que é a forma mais segura de formatar números manualmente. Observe que o number_format() do PHP não lê a localidade — você passa os separadores para ele explicitamente.

Problemas comuns

• A localidade deve estar instalada no servidor. setlocale() só tem sucesso para localidades que o sistema operacional conhece. Em um servidor Debian/Ubuntu, pode ser necessário executar locale-gen de_DE.UTF-8 && update-locale.
• É global para o processo, não é thread-safe. A configuração afeta todo o processo PHP, portanto evite alterá-la simultaneamente em SAPIs com múltiplas threads.
• Não altera echo ou printf() para floats. Use sprintf() com cuidado; o ponto decimal da localidade pode surpreender funções que constroem SQL ou JSON. Redefina com setlocale(LC_NUMERIC, 'C') em torno desse código.
• money_format() foi removido no PHP 8.0. Para moeda, prefira a classe NumberFormatter da extensão intl.

Prática