setlocale()

Die PHP-Funktion setlocale() legt die aktuelle Locale für ein Skript fest — die Sammlung kulturspezifischer Regeln, die bestimmen, wie Text sortiert wird, wie Zahlen und Währungen formatiert werden und wie Datumsangaben ausgegeben werden. Eine Locale wird durch eine Zeichenkette wie en_US (US-Englisch) oder de_DE (Deutsch) identifiziert, in der Regel kombiniert mit einer Zeichenkodierung wie .utf8.

setlocale() kommt immer dann zum Einsatz, wenn eine einzelne Codebasis Ausgaben erzeugen soll, die sich in mehreren Ländern „einheimisch" anfühlen: 1,234.56 für einen amerikanischen Benutzer, aber 1.234,56 für einen deutschen, January gegenüber Januar und so weiter.

Syntax

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

Es kann auch ein einzelnes Array von Locales anstelle einer Liste übergeben werden:

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

Parameter

• $category — welche Gruppe von locale-abhängigem Verhalten geändert werden soll. Eine der LC_*-Konstanten muss übergeben werden:

  Konstante	Betrifft
  LC_ALL	Alle Kategorien auf einmal
  LC_COLLATE	Zeichenkettenvergleich und -sortierung (siehe strcoll())
  LC_CTYPE	Zeichenklassifizierung und Groß-/Kleinschreibungskonvertierung
  LC_MONETARY	Währungsformatierung (siehe money_format())
  LC_NUMERIC	Dezimaltrennzeichen für Zahlen
  LC_TIME	Datums- und Zeitformatierung (siehe strftime())
  LC_MESSAGES	Systemmeldeformatierung (unter Windows nicht verfügbar)

• $locale — die anzuwendende Locale-Zeichenkette, z. B. 'en_US.utf8'. Drei spezielle Werte sind nützlich:

  • "" (leere Zeichenkette) — verwendet die Locale aus den Umgebungsvariablen des Servers.
  • "0" — ändert nichts; gibt lediglich die aktuelle Einstellung für diese Kategorie zurück.
  • null — identisch mit "0".

• ...$locales — optionale Fallback-Werte. PHP probiert jeden Namen der Reihe nach aus und wendet den ersten an, den das Betriebssystem tatsächlich installiert hat.

Bei Erfolg gibt die Funktion den Namen der gesetzten Locale zurück, oder false, wenn keine der angeforderten Locales verfügbar ist.

Einfaches Beispiel

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

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

setlocale() gibt bei Erfolg die neue Locale-Zeichenkette oder bei Misserfolg false zurück. Daher sollte der Rückgabewert immer geprüft werden — eine fehlende Locale schlägt lautlos fehl und hinterlässt fehlerhafte Formatierungen, anstatt einen Fehler auszulösen.

Fallbacks angeben

Locale-Namen unterscheiden sich je nach Betriebssystem (en_US.utf8 unter Linux, English_United States.1252 unter Windows). Durch Angabe mehrerer Namen kann dasselbe Skript überall funktionieren — PHP verwendet den ersten installierten Treffer:

<?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';
?>

Warum die Locale wichtig ist: Zahlenformatierung

Nach dem Setzen von LC_NUMERIC (oder LC_ALL) erzeugen Funktionen, die die Locale berücksichtigen, kulturspezifische Ausgaben. Hier folgen Dezimal- und Tausendertrennzeichen den deutschen Konventionen:

<?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() liest die numerischen und monetären Regeln der aktiven Locale zurück — dies ist der sicherste Weg, Zahlen manuell zu formatieren. Zu beachten ist, dass PHP's number_format() die Locale nicht liest — Trennzeichen werden explizit übergeben.

Häufige Fallstricke

• Die Locale muss auf dem Server installiert sein. setlocale() gelingt nur für Locales, die das Betriebssystem kennt. Auf einem Debian/Ubuntu-System ist möglicherweise locale-gen de_DE.UTF-8 && update-locale erforderlich.
• Die Einstellung ist prozessglobal und nicht thread-sicher. Die Einstellung wirkt sich auf den gesamten PHP-Prozess aus; daher sollte eine gleichzeitige Änderung in mehrthreadigen SAPIs vermieden werden.
• echo oder printf() für Gleitkommazahlen wird nicht beeinflusst. sprintf() sollte mit Bedacht verwendet werden; das Dezimalzeichen der Locale kann Funktionen überraschen, die SQL oder JSON erzeugen. Mit setlocale(LC_NUMERIC, 'C') kann die Einstellung um solchen Code herum zurückgesetzt werden.
• money_format() wurde in PHP 8.0 entfernt. Für Währungen sollte die Klasse NumberFormatter aus der intl-Erweiterung bevorzugt werden.

Übung