Signatur
Beschreibung
Intl.getCanonicalLocales() ist eine statische Methode des Intl-Namensraums. Sie nimmt ein oder mehrere Sprach-Tags entgegen und gibt sie in ihrer kanonischen Form nach BCP 47 bzw. Unicode-CLDR zurück. Dabei wird die Groß-/Kleinschreibung vereinheitlicht ("EN-us" → "en-US"), Subtags werden sortiert, veraltete Aliase werden durch aktuelle Codes ersetzt und doppelte Einträge fallen weg.
Die Methode ist nützlich, wenn Sprach-Tags aus unsicheren Quellen stammen, etwa aus Benutzereingaben, HTTP-Headern wie Accept-Language, URL-Parametern oder Konfigurationsdateien. Sie prüft die Syntax und liefert eine einheitliche Schreibweise, die man zuverlässig vergleichen, als Schlüssel in einer Map verwenden oder cachen kann.
Wichtig: Die Methode prüft nur die Syntax und kanonisiert die Tags. Sie sagt nicht, ob die Laufzeitumgebung die Locale auch unterstützt. Dafür gibt es Intl.DateTimeFormat.supportedLocalesOf() und die entsprechenden Methoden der anderen Intl-Konstruktoren. Ein syntaktisch ungültiges Tag löst einen RangeError aus.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $locales | string | Intl.Locale | Array<string | Intl.Locale> | undefined | undefined | Ein Sprach-Tag, ein Intl.Locale-Objekt oder ein Array davon. Bei undefined wird ein leeres Array zurückgegeben. |
Rückgabewert
undefined ist es leer.Beispiele
Schreibweise vereinheitlichen und Duplikate entfernen
const tags = Intl.getCanonicalLocales(['EN-us', 'de-de', 'en-US', 'fr']);
console.log(tags);Einzelnes Tag und Aliase kanonisieren
console.log(Intl.getCanonicalLocales('ZH-hant-tw'));
// Veralteter Sprachcode 'iw' wird zu 'he'
console.log(Intl.getCanonicalLocales('iw'));
console.log(Intl.getCanonicalLocales());Benutzereingaben sicher prüfen
const normalizeLocale = (input, fallback = 'de-DE') => {
try {
const [canonical] = Intl.getCanonicalLocales(input.trim());
return canonical ?? fallback;
} catch (err) {
if (err instanceof RangeError) {
console.warn(`Ungültiges Sprach-Tag: "${input}"`);
return fallback;
}
throw err;
}
};
console.log(normalizeLocale('en-gb'));
console.log(normalizeLocale('en_GB'));Accept-Language-Header auswerten (Node.js)
const parseAcceptLanguage = (header) => {
const raw = header
.split(',')
.map((part) => part.split(';')[0].trim())
.filter((tag) => tag && tag !== '*');
// Ungültige Tags einzeln verwerfen, statt alles abzubrechen
const valid = raw.filter((tag) => {
try { Intl.getCanonicalLocales(tag); return true; } catch { return false; }
});
return Intl.getCanonicalLocales(valid);
};
console.log(parseAcceptLanguage('de-de,de;q=0.9,EN-us;q=0.8,xx_invalid;q=0.5,*;q=0.1'));// Wichtig · Fallstricke
- RangeError: Enthält das Array ein einziges ungültiges Tag (z. B.
"en_US"mit Unterstrich oder""), wirft der ganze Aufruf einen Fehler. Gemischte Listen daher vorher einzeln prüfen. - TypeError: Array-Elemente, die weder String noch Objekt sind (z. B. Zahlen oder
null), lösen einenTypeErroraus. - Keine Prüfung der Unterstützung:
"xx-YY"ist syntaktisch gültig und wird zurückgegeben, auch wenn es keine solche Sprache gibt. Welche Locales tatsächlich unterstützt werden, zeigen diesupportedLocalesOf()-Methoden. - Unterschiedliche Engines: Die Ersetzung von Aliasen hängt von der CLDR-Version der Engine ab. Ergebnisse können sich zwischen Browsern und Node.js-Versionen leicht unterscheiden, etwa bei veralteten Regionscodes.
- Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome 54+, Firefox 48+, Safari 11+, Edge 16+) und von Node.js ab Version 7. In Node-Builds mit
small-icuist der Umfang der Locale-Daten eventuell eingeschränkt.