setlocale()

La función PHP setlocale() establece la configuración regional actual de un script — el conjunto de reglas culturales que determinan cómo se ordena el texto, cómo se formatean los números y la moneda, y cómo se escriben las fechas. Una configuración regional se identifica mediante una cadena como en_US (inglés de EE. UU.) o de_DE (alemán), generalmente combinada con una codificación de caracteres como .utf8.

Se recurre a setlocale() cuando una misma base de código debe producir resultados que se "sientan nativos" en más de un país: 1,234.56 para un usuario estadounidense pero 1.234,56 para uno alemán, January frente a Januar, etcétera.

Sintaxis

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

También puede aceptar un único array de configuraciones regionales en lugar de una lista:

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

Parámetros

• $category — qué grupo de comportamiento dependiente de la configuración regional se desea modificar. Se pasa una de las constantes LC_*:

  Constante	Afecta a
  LC_ALL	Todas las categorías a la vez
  LC_COLLATE	Comparación y ordenación de cadenas (véase strcoll())
  LC_CTYPE	Clasificación de caracteres y conversión de mayúsculas/minúsculas
  LC_MONETARY	Formato de moneda (véase money_format())
  LC_NUMERIC	Separador decimal para números
  LC_TIME	Formato de fecha y hora (véase strftime())
  LC_MESSAGES	Formato de mensajes del sistema (no disponible en Windows)

• $locale — la cadena de configuración regional a aplicar, p. ej. 'en_US.utf8'. Tres valores especiales son útiles:

  • "" (cadena vacía) — utilizar la configuración regional de las variables de entorno del servidor.
  • "0" — no cambiar nada; simplemente devolver la configuración actual para esa categoría.
  • null — igual que "0".

• ...$locales — alternativas opcionales. PHP prueba cada nombre en orden y aplica el primero que el sistema operativo tenga realmente instalado.

Devuelve el nombre de la configuración regional establecida en caso de éxito, o false si ninguna de las configuraciones regionales solicitadas está disponible.

Ejemplo 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() devuelve la nueva cadena de configuración regional en caso de éxito o false en caso de error, por lo que siempre se debe comprobar el valor de retorno — una configuración regional faltante falla silenciosamente y deja el formato incorrecto en lugar de lanzar un error.

Proporcionar alternativas

Los nombres de configuración regional difieren entre sistemas operativos (en_US.utf8 en Linux, English_United States.1252 en Windows). Listar varios nombres permite que el mismo script funcione en todas partes — PHP utiliza la primera coincidencia 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 qué importa la configuración regional: formato de números

Tras establecer LC_NUMERIC (o LC_ALL), las funciones que respetan la configuración regional producen una salida específica para cada cultura. Aquí los separadores decimales y de miles siguen las convenciones alemanas:

<?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() lee las reglas numéricas y monetarias de la configuración regional activa, lo cual es la forma más segura de formatear números manualmente. Nótese que number_format() de PHP no lee la configuración regional — los separadores se le pasan explícitamente.

Errores comunes

• La configuración regional debe estar instalada en el servidor. setlocale() solo tiene éxito con las configuraciones que el sistema operativo conoce. En un sistema Debian/Ubuntu puede ser necesario ejecutar locale-gen de_DE.UTF-8 && update-locale.
• Es global para el proceso, no es segura en entornos multihilo. La configuración afecta a todo el proceso PHP, por lo que se debe evitar cambiarla de forma concurrente en SAPIs multihilo.
• No modifica el comportamiento de echo ni de printf() para los flotantes. Se debe usar sprintf() con precaución; el punto decimal de la configuración regional puede sorprender a las funciones que construyen SQL o JSON. Se puede restablecer con setlocale(LC_NUMERIC, 'C') alrededor de dicho código.
• money_format() fue eliminado en PHP 8.0. Para moneda, se prefiere la clase NumberFormatter de la extensión intl.

Práctica