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

Signatur

new Intl.RelativeTimeFormat(locales, options)

Beschreibung

Der Konstruktor Intl.RelativeTimeFormat() erzeugt einen Formatierer für relative Zeitangaben. Du gibst ihm eine Zahl und eine Einheit, und er liefert einen sprachlich korrekten Text wie „in 2 Stunden“, „vor 5 Minuten“ oder – mit numeric: "auto" – „gestern“ bzw. „nächste Woche“. Pluralformen, Wortstellung und Sonderwörter übernimmt die Laufzeitumgebung anhand der CLDR-Daten.

Typische Einsatzorte sind Aktivitäts-Feeds, Kommentar-Zeitstempel („vor 3 Stunden“), Countdown-Anzeigen oder Erinnerungen. Wichtig: Der Formatierer berechnet keine Zeitdifferenzen. Du musst selbst die Differenz zwischen zwei Zeitpunkten ermitteln und die passende Einheit wählen; format() übernimmt nur die sprachliche Darstellung.

Der Konstruktor muss mit new aufgerufen werden, sonst wird ein TypeError ausgelöst. Da das Erzeugen eines Formatierers vergleichsweise aufwendig ist, solltest du eine Instanz einmal anlegen und mehrfach verwenden, statt sie in Schleifen oder Render-Funktionen neu zu erstellen.

Parameter

Name	Typ	Default	Beschreibung
$locales	string \| string[] \| Intl.Locale \| undefined	Standard-Locale der Laufzeitumgebung	BCP-47-Sprachkennung wie `"de"`, `"de-AT"` oder `"en-US"` bzw. ein Array davon als Rangfolge. Unterstützt die Unicode-Erweiterung `-u-nu-` (Zahlensystem).
$options	object	{}	Konfigurationsobjekt mit den Eigenschaften: `localeMatcher`: `"best fit"` (Standard) oder `"lookup"`. `numeric`: `"always"` (Standard, z. B. „vor 1 Tag“) oder `"auto"` (z. B. „gestern“). `style`: `"long"` (Standard), `"short"` oder `"narrow"` – Länge der Einheitenbezeichnung. `numberingSystem`: Zahlensystem, z. B. `"arab"` oder `"latn"`.

Rückgabewert

Typ

Intl.RelativeTimeFormat

Beschreibung

Eine neue Formatierer-Instanz mit den Methoden format(value, unit), formatToParts(value, unit) und resolvedOptions().

Beispiele

Grundlegende Instanziierung und Formatierung

const rtf = new Intl.RelativeTimeFormat('de');

console.log(rtf.format(-3, 'day'));
console.log(rtf.format(2, 'hour'));
console.log(rtf.format(1, 'month'));

vor 3 Tagen in 2 Stunden in 1 Monat

numeric: "auto" für natürliche Formulierungen

const rtf = new Intl.RelativeTimeFormat('de', { numeric: 'auto' });

console.log(rtf.format(-1, 'day'));
console.log(rtf.format(0, 'day'));
console.log(rtf.format(1, 'week'));

const kurz = new Intl.RelativeTimeFormat('en', { style: 'short' });
console.log(kurz.format(-5, 'minute'));

gestern heute nächste Woche 5 min. ago

Praxis: Zeitstempel eines Kommentars als „vor X“ anzeigen

const rtf = new Intl.RelativeTimeFormat('de', { numeric: 'auto' });

const EINHEITEN = [
  ['year', 60 * 60 * 24 * 365],
  ['month', 60 * 60 * 24 * 30],
  ['week', 60 * 60 * 24 * 7],
  ['day', 60 * 60 * 24],
  ['hour', 60 * 60],
  ['minute', 60],
  ['second', 1],
];

const relativeZeit = (datum, jetzt = new Date()) => {
  const diffSek = (datum.getTime() - jetzt.getTime()) / 1000;
  for (const [einheit, sekunden] of EINHEITEN) {
    if (Math.abs(diffSek) >= sekunden || einheit === 'second') {
      return rtf.format(Math.round(diffSek / sekunden), einheit);
    }
  }
};

const jetzt = new Date('2024-05-10T12:00:00Z');
console.log(relativeZeit(new Date('2024-05-10T09:00:00Z'), jetzt));
console.log(relativeZeit(new Date('2024-05-09T12:00:00Z'), jetzt));
console.log(relativeZeit(new Date('2024-05-10T12:00:30Z'), jetzt));

vor 3 Stunden gestern in 30 Sekunden

formatToParts() und resolvedOptions()

const rtf = new Intl.RelativeTimeFormat('de', { style: 'short' });

console.log(rtf.formatToParts(-10, 'minute'));
console.log(rtf.resolvedOptions());

[ { type: 'literal', value: 'vor ' }, { type: 'integer', value: '10', unit: 'minute' }, { type: 'literal', value: ' Min.' } ] { locale: 'de', style: 'short', numeric: 'always', numberingSystem: 'latn' }

// Wichtig · Fallstricke

Ohne new geht es nicht: Intl.RelativeTimeFormat() ohne new löst einen TypeError aus (anders als bei Intl.NumberFormat).
Keine Zeitberechnung: Der Formatierer rechnet nicht mit Datumswerten. Differenz und Einheit musst du selbst ermitteln; Monate und Jahre sind dabei nur Näherungen, wenn du über Sekunden rechnest.
Gültige Einheiten: \"year\", \"quarter\", \"month\", \"week\", \"day\", \"hour\", \"minute\", \"second\" (auch im Plural, z. B. \"days\"). Andere Werte wie \"millisecond\" führen zu einem RangeError.
Negative Null: format(-0, 'day') ergibt „vor 0 Tagen“ bzw. mit numeric: \"auto\" „heute“ – achte beim Runden mit Math.round() auf -0.
Ausgabe nicht vergleichen: Die exakten Texte (z. B. „Min.“ vs. „Minuten“, geschützte Leerzeichen) hängen von der CLDR-Version der Engine ab und können sich zwischen Browsern und Versionen unterscheiden. Nicht in Tests auf exakte Strings prüfen.
Performance: Instanzen wiederverwenden statt bei jedem Aufruf neu zu erzeugen.
Kompatibilität: Chrome 71+, Firefox 65+, Safari 14+, Edge 79+, Node.js 12+ (mit vollständigen ICU-Daten). Ungültige Locale-Kennungen lösen einen RangeError aus.

Siehe auch

Intl.RelativeTimeFormat Intl.RelativeTimeFormat.prototype.format() Intl.RelativeTimeFormat.prototype.formatToParts() Intl.RelativeTimeFormat.prototype.resolvedOptions() Intl.DateTimeFormat Intl.NumberFormat Intl.PluralRules