locale_lookup — Funktion · PHP-Referenz

Signatur

locale_lookup(array $languageTag, string $locale, bool $canonicalize = false, string $default = ''): string

Beschreibung

locale_lookup() implementiert den Lookup-Algorithmus aus RFC 4647, um aus einer Liste von Sprach-Tags dasjenige zu finden, das am besten zur gewünschten Locale passt. Der Algorithmus arbeitet durch schrittweises Kürzen des gesuchten Tags (z. B. de-AT → de), bis eine Übereinstimmung in der übergebenen Liste gefunden wird.

Typisches Einsatzgebiet ist die Sprachaushandlung in Webanwendungen: Der Browser sendet via Accept-Language eine Prioritätsliste gewünschter Sprachen; mit locale_lookup() kann die Anwendung daraus das am besten passende, verfügbare Locale ermitteln.

Wird $canonicalize auf true gesetzt, werden die Einträge der Liste zunächst in ihre kanonische Form umgewandelt, bevor der Vergleich stattfindet. Das verhindert Fehler durch inkonsistente Schreibweisen (z. B. ZH_cn vs. zh-CN).

Diese Funktion ist die prozedurale Variante von Locale::lookup() aus der intl-Erweiterung.

Parameter

Name	Typ	Default	Beschreibung
$languageTag Pflicht	array		Geordnete Liste von Sprach-Tags (Strings), die als verfügbare Locales dienen, z. B. `['de-DE', 'de', 'en-US', 'en']`.
$locale Pflicht	string		Das gewünschte Locale, nach dem in `$languageTag` gesucht wird, z. B. `de-AT`.
$canonicalize	bool	false	Wenn `true`, werden alle Einträge der Liste vor dem Vergleich in ihre kanonische ICU-Form umgewandelt.
$default	string		Rückgabewert, falls kein Treffer gefunden wird. Wird auch zurückgegeben, wenn `$locale` leer ist.

Rückgabewert

Typ

string

Beschreibung

Das beste passende Sprach-Tag aus $languageTag oder den Wert von $default, wenn kein Treffer gefunden wurde.

Beispiele

Einfache Sprach-Suche für ein österreichisches Deutsch-Locale

<?php
$available = ['de-DE', 'de', 'en-US', 'en', 'fr'];

// Gesucht: de-AT — nicht direkt vorhanden, aber 'de' passt
$match = locale_lookup($available, 'de-AT', false, 'en');
echo $match; // de

// Gesucht: zh-Hans-CN — kein passender Eintrag, Fallback greift
$match2 = locale_lookup($available, 'zh-Hans-CN', false, 'en');
echo PHP_EOL . $match2; // en

de en

Sprachaushandlung aus Accept-Language-Header

<?php
// Simulierter Accept-Language-Header: de-AT;q=0.9,en-GB;q=0.8,fr;q=0.7
$acceptLanguage = 'de-AT;q=0.9,en-GB;q=0.8,fr;q=0.7';

// Locale::acceptFromHttp() liefert das bevorzugte Tag
$preferred = locale_accept_from_http($acceptLanguage);

$supported = ['de-DE', 'en', 'fr', 'es'];

$best = locale_lookup($supported, $preferred, true, 'en');
echo 'Gewähltes Locale: ' . $best;

Gewähltes Locale: de-DE

Kanonisierung aktivieren

<?php
// Inkonsistente Schreibweise in der Liste
$available = ['ZH_cn', 'EN_us', 'DE_de'];

// Ohne Kanonisierung: kein Treffer wegen Groß-/Kleinschreibung
$noCanon = locale_lookup($available, 'zh-CN', false, 'fallback');
echo $noCanon . PHP_EOL; // fallback

// Mit Kanonisierung: ICU-Normalisierung ermöglicht Treffer
$withCanon = locale_lookup($available, 'zh-CN', true, 'fallback');
echo $withCanon; // ZH_cn

fallback ZH_cn

// Wichtig · Fallstricke

Voraussetzung: Die PHP-Erweiterung intl muss installiert und aktiviert sein. Ohne intl ist weder locale_lookup() noch Locale::lookup() verfügbar.

Der Lookup-Algorithmus ist kein Best-Fit-Algorithmus: Er liefert den ersten Treffer aus der Liste beim schrittweisen Kürzen des gesuchten Tags, nicht unbedingt den qualitativ besten. Für detailliertere Sprachaushandlung empfiehlt sich ein vorgelagertes Priorisieren der Liste oder die Verwendung von locale_filter_matches().

Der Vergleich ist standardmäßig case-insensitiv für BCP-47-Tags, jedoch sollten zur Sicherheit alle Tags einheitlich normalisiert werden (z. B. über locale_canonicalize()), besonders wenn Benutzereingaben verarbeitet werden.

Siehe auch

locale_accept_from_http locale_filter_matches locale_canonicalize locale_get_default Locale