Locale — Klasse · PHP-Referenz

Signatur

class Locale

Beschreibung

Die Klasse Locale aus der Intl-Erweiterung kapselt Operationen rund um Locale-Bezeichner (z. B. de_DE, en_US_POSIX, zh-Hant-TW). Ein Locale-Bezeichner beschreibt eine Kombination aus Sprache, Region, Skript und weiteren Subtags gemäß dem IETF-Standard BCP 47 und ICU-Konventionen.

Typische Anwendungsfälle sind: Auslesen der bevorzugten Sprache eines Nutzers aus dem HTTP-Header Accept-Language, Normalisierung von Locale-Bezeichnern, Lookup des besten passenden Locale aus einer Liste sowie das Zerlegen und Zusammensetzen komplexer Locale-Tags für Kollation, Datumsformatierung oder Nachrichtenformatierung.

Alle Methoden der Klasse sind statisch; es gibt keinen zu instanziierenden Zustand. Alternativ stehen in vielen Fällen prozedurale Wrapper-Funktionen wie locale_get_primary_language() zur Verfügung.

Parsen: Locale::parseLocale() zerlegt einen Bezeichner in seine Subtags.
Zusammensetzen: Locale::composeLocale() fügt Subtags zu einem gültigen Bezeichner zusammen.
Lookup: Locale::lookup() findet das am besten passende Locale aus einer Liste.
Accept-Language: Locale::acceptFromHttp() wertet den HTTP-Header aus.

Beispiele

Primärsprache und Region aus einem Locale-Bezeichner auslesen

<?php
$locale = 'de_AT';

echo Locale::getPrimaryLanguage($locale);  // de
echo PHP_EOL;
echo Locale::getRegion($locale);            // AT
echo PHP_EOL;

// Alle Subtags auf einmal
$parts = Locale::parseLocale('zh-Hant-TW-u-ca-buddhist');
print_r($parts);

de AT Array ( [language] => zh [script] => Hant [region] => TW [variant0] => [keyword_ca] => buddhist )

Bestes Locale anhand des HTTP-Headers Accept-Language ermitteln

<?php
// Simulierter Accept-Language-Header
$_SERVER['HTTP_ACCEPT_LANGUAGE'] = 'fr-CH, fr;q=0.9, de;q=0.8, *;q=0.5';

$bestMatch = Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']);
echo $bestMatch; // fr_CH

// Aus eigener Liste das beste Locale wählen
$available = ['de_DE', 'de_AT', 'en_US', 'fr_FR'];
$requested = 'fr_BE';

$found = Locale::lookup($available, $requested, true, 'en_US');
echo PHP_EOL . $found; // fr_FR

fr_CH fr_FR

Locale aus Subtags zusammensetzen

<?php
$subtags = [
    'language' => 'sr',
    'script'   => 'Cyrl',
    'region'   => 'RS',
];

$locale = Locale::composeLocale($subtags);
echo $locale; // sr_Cyrl_RS

// Anzeigename des Locales in der Sprache des Nutzers
echo PHP_EOL;
echo Locale::getDisplayName('sr_Cyrl_RS', 'de'); // Serbisch (Kyrillisch, Serbien)

sr_Cyrl_RS Serbisch (Kyrillisch, Serbien)

// Wichtig · Fallstricke

Erweiterung erforderlich: Die Klasse Locale setzt die PHP-Erweiterung intl voraus (extension=intl in der php.ini). Ohne sie steht weder die Klasse noch eine der prozeduralen Wrapper-Funktionen zur Verfügung.

Standardlocale: Mit Locale::setDefault('de_DE') lässt sich ein globaler Fallback setzen, der von Intl-Klassen wie NumberFormatter oder DateFormatter genutzt wird, wenn kein explizites Locale angegeben wird.

Sicherheitshinweis bei acceptFromHttp(): Die Methode wertet rohe HTTP-Header-Eingaben aus. Das Ergebnis sollte stets gegen eine Liste bekannter, unterstützter Locales geprüft werden, bevor es für Datenbankabfragen, Dateinamen oder sicherheitskritische Operationen verwendet wird.

ICU-Versionsabhängigkeit: Das Verhalten einzelner Methoden (Normalisierung, Kanonisierung) hängt von der installierten ICU-Bibliotheksversion ab. Mit INTL_ICU_VERSION lässt sich die Version zur Laufzeit prüfen.

Siehe auch

NumberFormatter IntlDateFormatter Collator locale_get_primary_language locale_accept_from_http locale_lookup locale_parse