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

Signatur

Intl.DateTimeFormat.supportedLocalesOf(locales, options)

Beschreibung

Die statische Methode Intl.DateTimeFormat.supportedLocalesOf() prüft eine Liste von BCP-47-Sprachkennungen (z. B. "de-DE", "ja-JP") und gibt nur diejenigen zurück, für die die aktuelle JavaScript-Umgebung Daten zur Datums- und Zeitformatierung besitzt. Gebietsschemas, für die ein Fallback auf das Standard-Gebietsschema nötig wäre, werden herausgefiltert.

Das ist nützlich, wenn Sie vor dem Formatieren wissen möchten, ob die Wunschsprache eines Nutzers tatsächlich unterstützt wird, etwa um eine eigene Fallback-Kette aufzubauen, einen Hinweis anzuzeigen oder eine Sprachauswahl nur mit verfügbaren Optionen zu befüllen. Besonders in Umgebungen mit eingeschränkten ICU-Daten (ältere Node.js-Builds mit small-icu, eingebettete Laufzeiten) liefert die Methode verlässliche Auskunft.

Die Rückgabe enthält die Kennungen in kanonisierter Form (z. B. wird "DE-de" zu "de-DE") und in der Reihenfolge der Eingabe. Ein Gebietsschema gilt auch dann als unterstützt, wenn nur eine übergeordnete Sprache vorhanden ist – beim Standard-Algorithmus "best fit" bzw. "lookup" wird etwa "de-XX" über "de" aufgelöst.

Parameter

Name	Typ	Default	Beschreibung
$locales	string \| string[] \| Intl.Locale \| Intl.Locale[] \| undefined	undefined	Eine BCP-47-Sprachkennung oder ein Array davon. Bei `undefined` wird ein leeres Array zurückgegeben. Ungültige Kennungen lösen einen `RangeError` aus.
$options	object	{}	Optionales Objekt mit der Eigenschaft `localeMatcher`: `"best fit"` (Standard, implementierungsabhängig) oder `"lookup"` (strenger Algorithmus nach BCP 47 / RFC 4647).

Rückgabewert

Typ

string[]

Beschreibung

Ein neues Array mit den kanonisierten Kennungen aller übergebenen Gebietsschemas, die ohne Fallback auf das Standard-Gebietsschema unterstützt werden. Leer, wenn keines unterstützt wird.

Beispiele

Unterstützte Gebietsschemas filtern

const wunsch = ['de-DE', 'ban', 'ja-JP', 'xx-YY'];
const unterstuetzt = Intl.DateTimeFormat.supportedLocalesOf(wunsch);
console.log(unterstuetzt);

[ 'de-DE', 'ja-JP' ] // 'ban' (Balinesisch) je nach ICU-Daten ebenfalls enthalten

Kanonisierung und localeMatcher

const ergebnis = Intl.DateTimeFormat.supportedLocalesOf(
  ['DE-at', 'en-us'],
  { localeMatcher: 'lookup' }
);
console.log(ergebnis);

[ 'de-AT', 'en-US' ]

Datum in der Browsersprache mit eigenem Fallback formatieren

const formatiereDatum = (datum) => {
  const kandidaten = [...navigator.languages, 'en-US'];
  const [locale] = Intl.DateTimeFormat.supportedLocalesOf(kandidaten);
  return new Intl.DateTimeFormat(locale ?? 'en-US', {
    dateStyle: 'long',
    timeStyle: 'short'
  }).format(datum);
};

console.log(formatiereDatum(new Date(2024, 2, 15, 14, 30)));

15. März 2024 um 14:30 // bei deutscher Browsersprache

Ungültige Kennung abfangen

try {
  Intl.DateTimeFormat.supportedLocalesOf(['de-DE', 'kein gültiger tag']);
} catch (err) {
  console.log(err.name);
}

RangeError

// Wichtig · Fallstricke

Ungültige Kennungen (syntaktisch falsche BCP-47-Tags) werfen einen RangeError statt einfach ignoriert zu werden – Nutzereingaben daher mit try...catch absichern.
Das Ergebnis ist umgebungsabhängig: Browser, Node.js-Version und ICU-Build (full-icu vs. small-icu) liefern unterschiedliche Listen. Nie fest davon ausgehen, dass ein Gebietsschema überall verfügbar ist.
Der Standard-Matcher \"best fit\" ist implementierungsabhängig; für reproduzierbare Ergebnisse { localeMatcher: 'lookup' } verwenden.
Unicode-Erweiterungen wie -u-ca-buddhist bleiben in der Rückgabe erhalten, ihre Unterstützung wird aber nicht separat geprüft. Dafür resolvedOptions() einer Instanz nutzen.
Die Methode gehört zu Intl.DateTimeFormat; andere Intl-Konstruktoren (NumberFormat, Collator …) haben eigene supportedLocalesOf()-Methoden mit ggf. abweichenden Ergebnissen.
Kompatibilität: in allen modernen Browsern und Node.js verfügbar; nur sehr alte Umgebungen (IE < 11) kennen die Intl-API nicht.

Siehe auch

Intl.DateTimeFormat Intl.DateTimeFormat.prototype.resolvedOptions() Intl.DateTimeFormat.prototype.format() Intl.getCanonicalLocales() Intl.Locale navigator.languages