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

Signatur

Intl.ListFormat.supportedLocalesOf(locales, options)

Beschreibung

Die statische Methode Intl.ListFormat.supportedLocalesOf() prüft, welche der übergebenen Sprach-Tags (BCP-47, z. B. "de-DE", "en") die Laufzeitumgebung für die Listenformatierung unterstützt. Zurück kommt ein neues Array mit den unterstützten Locales in kanonischer Schreibweise und in der Reihenfolge der Eingabe. Nicht unterstützte Einträge fallen einfach weg.

Das ist vor allem nützlich, bevor man einen Intl.ListFormat-Formatierer anlegt. Der Konstruktor weicht bei einer unbekannten Locale nämlich stillschweigend auf die Standard-Locale aus. Mit supportedLocalesOf() lässt sich vorher feststellen, ob die gewünschte Sprache wirklich verfügbar ist. So kann man eine eigene Ersatzkette bauen oder die Nutzereinstellungen (z. B. navigator.languages) filtern.

Über die Option localeMatcher legt man den Abgleich-Algorithmus fest: "best fit" (Standardwert, von der Implementierung bestimmt) oder "lookup" (streng nach BCP 47 / RFC 4647). Wird eine regionale Variante wie "de-CH" angefragt und nur "de" ist vorhanden, gilt die Locale trotzdem als unterstützt und wird in der angefragten Form zurückgegeben.

Parameter

Name	Typ	Default	Beschreibung
$locales	string \| string[] \| Intl.Locale \| Intl.Locale[] \| undefined	undefined	Ein BCP-47-Sprach-Tag oder ein Array davon (auch `Intl.Locale`-Objekte sind erlaubt). Bei `undefined` wird ein leeres Array zurückgegeben.
$options	object	{}	Objekt mit der optionalen Eigenschaft `localeMatcher`: `"best fit"` (Standardwert) oder `"lookup"`.

Rückgabewert

Typ

string[]

Beschreibung

Ein neues Array mit den unterstützten Locales als kanonische Sprach-Tags. Die Reihenfolge der Eingabe bleibt erhalten; nicht unterstützte Einträge werden weggelassen.

Beispiele

Unterstützte Locales ermitteln

const angefragt = ['de-DE', 'ban', 'en-US', 'xx-YY'];
const unterstuetzt = Intl.ListFormat.supportedLocalesOf(angefragt);
console.log(unterstuetzt);

["de-DE", "en-US"] // 'ban' (Balinesisch) je nach ICU-Datenumfang

Nutzersprache mit eigener Ersatzsprache wählen

const waehleLocale = (wunsch, fallback = 'en') => {
  const [treffer] = Intl.ListFormat.supportedLocalesOf(wunsch, { localeMatcher: 'lookup' });
  return treffer ?? fallback;
};

const locale = waehleLocale(['tlh', 'fr-CA', 'de']);
const lf = new Intl.ListFormat(locale, { type: 'conjunction' });
console.log(locale, '→', lf.format(['Äpfel', 'Birnen', 'Kirschen']));

fr-CA → Äpfel, Birnen et Kirschen

Kanonisierung und ungültige Tags

console.log(Intl.ListFormat.supportedLocalesOf('EN-gb'));

try {
  Intl.ListFormat.supportedLocalesOf('de_DE'); // Unterstrich ist kein gültiges BCP-47
} catch (err) {
  console.log(err.name);
}

["en-GB"] RangeError

// Wichtig · Fallstricke

Ungültige Tags (z. B. "de_DE" oder ein leerer String) lösen einen RangeError aus, sie werden nicht einfach herausgefiltert. Eingaben von Nutzern deshalb in try/catch einschließen.
Das Ergebnis hängt von den ICU-Daten der Umgebung ab. Node.js-Builds mit small-icu (vor Node 13) kennen oft nur "en", Browser unterstützen in der Regel deutlich mehr Sprachen.
"best fit" und "lookup" können unterschiedliche Ergebnisse liefern. Wer auf allen Plattformen gleiches Verhalten braucht, verwendet "lookup".
Andere Optionen des Konstruktors wie type oder style werden hier ignoriert. Nur localeMatcher hat eine Wirkung.
Kompatibilität: Intl.ListFormat gibt es ab Chrome 72, Firefox 78, Safari 14.1 und Node.js 12. Für ältere Umgebungen vorher auf typeof Intl.ListFormat !== 'undefined' prüfen oder ein Polyfill wie @formatjs/intl-listformat einsetzen.

Siehe auch

Intl.ListFormat Intl.ListFormat.prototype.format() Intl.ListFormat.prototype.resolvedOptions() Intl.Locale navigator.languages