Intl.DisplayNames.supportedLocalesOf() — Methode · JavaScript-Referenz

Signatur

Intl.DisplayNames.supportedLocalesOf(locales, options)

Beschreibung

Die statische Methode Intl.DisplayNames.supportedLocalesOf() prüft eine Liste von Sprach-Tags (BCP 47) und liefert nur die zurück, für die die aktuelle JavaScript-Umgebung lokalisierte Anzeigenamen bereitstellen kann, also Namen von Sprachen, Regionen, Schriften oder Währungen. Locales, bei denen die Umgebung auf ihre eigene Standard-Locale ausweichen müsste, werden weggelassen.

Das ist praktisch, bevor man eine Intl.DisplayNames-Instanz erzeugt. So lässt sich zum Beispiel aus den Wunschsprachen des Nutzers (navigator.languages) die beste unterstützte Sprache auswählen, oder man zeigt in einem Sprachauswahlmenü nur Einträge an, die die Umgebung wirklich lokalisieren kann.

Die zurückgegebenen Tags sind kanonisiert: Aus "DE-de" wird z. B. "de-DE". Die Reihenfolge der Eingabe bleibt erhalten und Duplikate werden entfernt. Eine Locale gilt auch dann als unterstützt, wenn die Umgebung nur eine allgemeinere Variante kennt (z. B. "de" für "de-CH"). In diesem Fall wird der angefragte Tag zurückgegeben.

Parameter

Name	Typ	Default	Beschreibung
$locales	string \| string[] \| Intl.Locale \| Intl.Locale[] \| undefined	undefined	Ein BCP-47-Sprach-Tag, ein `Intl.Locale`-Objekt oder ein Array davon. Bei `undefined` wird ein leeres Array zurückgegeben.
$options	object	{}	Optionales Objekt mit der Eigenschaft `localeMatcher`: `"best fit"` (Standard) oder `"lookup"`. Damit wählt man den Algorithmus für den Locale-Abgleich.

Rückgabewert

Typ

string[]

Beschreibung

Ein neues Array mit den kanonisierten Tags der unterstützten Locales, in der Reihenfolge der Eingabe. Es ist leer, wenn keine der Locales unterstützt wird.

Beispiele

Unterstützte Locales filtern

const wunsch = ['de-DE', 'ban', 'fr', 'xx-INVALIDX'.slice(0, 2)];
const unterstuetzt = Intl.DisplayNames.supportedLocalesOf(wunsch);
console.log(unterstuetzt);

["de-DE", "fr"] // abhängig von der Umgebung; "ban" (Balinesisch) und "xx" fehlen meist

Beste Sprache für Anzeigenamen aus navigator.languages wählen

const kandidaten = navigator.languages ?? ['en'];
const [beste = 'en'] = Intl.DisplayNames.supportedLocalesOf(kandidaten, {
  localeMatcher: 'lookup'
});

const regionen = new Intl.DisplayNames([beste], { type: 'region' });
console.log(beste, regionen.of('JP'));

de-DE Japan // z. B. bei deutschsprachigem Browser

Kanonisierung und Duplikate

const ergebnis = Intl.DisplayNames.supportedLocalesOf(['EN-us', 'en-US', 'de-ch']);
console.log(ergebnis);

["en-US", "de-CH"]

Fehler bei ungültigem Tag abfangen

try {
  Intl.DisplayNames.supportedLocalesOf(['de_DE']);
} catch (err) {
  console.log(err.name, err.message);
}

RangeError Incorrect locale information provided

// Wichtig · Fallstricke

Ungültige Tags wie "de_DE" (Unterstrich statt Bindestrich) oder leere Strings lösen einen RangeError aus. Nicht unterstützte, aber syntaktisch gültige Tags werden dagegen still herausgefiltert.
Das Ergebnis hängt von der Umgebung ab. Ein Browser liefert je nach mitgelieferten ICU-Daten andere Ergebnisse als Node.js. Node.js-Builds mit small-icu (vor Version 13) unterstützen oft nur en.
Die Unterstützung für eine Locale bedeutet nicht, dass jeder type (language, region, script, currency, calendar, dateTimeField) für jeden Code einen übersetzten Namen liefert. of() kann trotzdem den Code selbst oder undefined zurückgeben (bei fallback: "none").
Die Methode ist statisch. Man ruft sie also auf Intl.DisplayNames auf, nicht auf einer Instanz.
Kompatibilität: Chrome 81+, Firefox 86+, Safari 14.1+, Edge 81+ und Node.js 14+. In älteren Umgebungen gibt es Intl.DisplayNames nicht. Prüfe das vorher mit typeof Intl.DisplayNames !== 'undefined'.

Siehe auch

Intl.DisplayNames Intl.DisplayNames.prototype.of() Intl.Locale Intl.DateTimeFormat.supportedLocalesOf() navigator.languages