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

Signatur

Intl.RelativeTimeFormat.supportedLocalesOf(locales, options)

Beschreibung

Die statische Methode Intl.RelativeTimeFormat.supportedLocalesOf() prüft eine Liste von Sprach-Tags (BCP 47) und gibt nur die zurück, für die die JavaScript-Laufzeit tatsächlich Daten zur relativen Zeitformatierung mitbringt, z. B. für Ausgaben wie „vor 3 Tagen“ oder „in 2 Stunden“. Locales, die nur über den Rückfall auf die Standard-Locale bedient würden, fehlen im Ergebnis.

Das ist nützlich, wenn du vor dem Erzeugen eines Formatierers wissen willst, ob die gewünschte Sprache wirklich verfügbar ist. So kannst du z. B. die Spracheinstellung eines Nutzers gegen die Fähigkeiten des Browsers bzw. von Node.js abgleichen und sonst gezielt eine eigene Rückfallsprache wählen, statt stillschweigend die Systemsprache zu bekommen.

Die Tags im Ergebnis werden in kanonischer Schreibweise zurückgegeben (z. B. "de-DE" statt "DE-de"), und die Reihenfolge der Eingabe bleibt erhalten. Ein Tag wie "de-AT" gilt meist als unterstützt, sobald die Laufzeit eine passende Basissprache ("de") kennt, sofern der gewählte Abgleich-Algorithmus das zulässt.

Parameter

Name	Typ	Default	Beschreibung
$locales	string \| string[] \| Intl.Locale \| Intl.Locale[] \| undefined	undefined	Ein BCP-47-Sprach-Tag oder ein Array davon, z. B. `"de-DE"` oder `["fr", "ja"]`. Bei `undefined` wird ein leeres Array zurückgegeben.
$options	object	{}	Optionsobjekt mit der Eigenschaft `localeMatcher`: `"best fit"` (Standard, abgleichender Algorithmus der Laufzeit) oder `"lookup"` (strikter BCP-47-Lookup-Algorithmus).

Beispiele

Unterstützte Locales ermitteln

const requested = ['de-DE', 'ban', 'fr-CA', 'xx-XX'];
const supported = Intl.RelativeTimeFormat.supportedLocalesOf(requested);
console.log(supported);

["de-DE", "fr-CA"] // abhängig von der Laufzeit; "ban" (Balinesisch) fehlt oft

Nutzersprache mit eigener Rückfallsprache verwenden

const pickLocale = (preferred, fallback = 'en') => {
  const [match] = Intl.RelativeTimeFormat.supportedLocalesOf(preferred);
  return match ?? fallback;
};

const locale = pickLocale(navigator.languages ?? ['de-DE']);
const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
console.log(rtf.format(-1, 'day'));

"gestern" // bei deutscher Browsersprache

Abgleich-Algorithmus 'lookup' und Kanonisierung

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

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

// Wichtig · Fallstricke

Das Ergebnis hängt von der Laufzeit ab: Browser und Node.js bringen unterschiedlich viele ICU-Sprachdaten mit. Ältere Node.js-Versionen mit small-icu (vor Node.js 13) unterstützen oft nur Englisch.
Ungültige Sprach-Tags (z. B. "de_DE" mit Unterstrich oder "") lösen einen RangeError aus, ungültige Werte für localeMatcher ebenfalls.
Mit "best fit" kann die Laufzeit großzügiger abgleichen als mit "lookup". Die Ergebnisse können sich also je nach Option unterscheiden.
Wenn eine Locale im Ergebnis steht, heißt das nicht, dass jede Einheit oder jeder Stil ("narrow", "short") eigene Übersetzungen hat. Die Formatierung kann trotzdem auf allgemeinere Daten zurückgreifen.
Intl.RelativeTimeFormat gibt es seit Chrome 71, Firefox 65, Safari 14 und Node.js 12. In älteren Umgebungen braucht man ein Polyfill (z. B. @formatjs/intl-relativetimeformat).

Siehe auch

Intl.RelativeTimeFormat Intl.RelativeTimeFormat.prototype.format() Intl.RelativeTimeFormat.prototype.resolvedOptions() Intl.Locale Intl.DateTimeFormat.supportedLocalesOf()