Signatur
Beschreibung
Intl.RelativeTimeFormat ist Teil der ECMAScript-Internationalisierungs-API und erlaubt es, numerische Zeitdifferenzen in natürlich klingende, lokalisierte Zeichenketten umzuwandeln. Statt manuell Texte wie „vor 5 Minuten" oder „in 2 Stunden" zusammenzubauen, übernimmt das Objekt die sprachspezifische Grammatik, Pluralregeln und Stilvorgaben automatisch.
Eine Instanz wird mit einem oder mehreren BCP-47-Sprach-Tags (z. B. "de", "fr", "ja") und einem optionalen Optionsobjekt erzeugt. Über die Methode format(value, unit) wird dann ein negativer (Vergangenheit) oder positiver (Zukunft) Zahlenwert zusammen mit einer Zeiteinheit wie "day", "month" oder "year" in eine fertige Zeichenkette umgewandelt.
Mit formatToParts(value, unit) lässt sich das Ergebnis in einzelne Token zerlegen, was nützlich ist, wenn Teile des formatierten Strings individuell gestaltet oder weiterverarbeitet werden sollen (z. B. in React-Komponenten). Die statische Methode Intl.RelativeTimeFormat.supportedLocalesOf() gibt an, welche Sprach-Tags unterstützt werden, ohne auf den Standard-Fallback zurückzufallen.
Typische Einsatzgebiete sind Social-Media-Feeds, Kommentarzeitstempel, Aufgabenlisten oder jede andere Benutzeroberfläche, die dem Nutzer relative Zeitabstände anzeigt – ohne externe Bibliotheken wie moment.js oder date-fns einbinden zu müssen.
Rückgabewert
Intl.RelativeTimeFormat-Objekts, die zur Formatierung relativer Zeitangaben verwendet werden kann.Beispiele
Einfache relative Zeitangaben auf Deutsch
const rtf = new Intl.RelativeTimeFormat("de", { numeric: "auto" });
console.log(rtf.format(-1, "day")); // "gestern"
console.log(rtf.format(0, "day")); // "heute"
console.log(rtf.format(1, "day")); // "morgen"
console.log(rtf.format(-3, "week")); // "vor 3 Wochen"
console.log(rtf.format(2, "month")); // "in 2 Monaten"
console.log(rtf.format(-1, "year")); // "letztes Jahr"Mehrsprachiger Vergleich mit style-Option
const locales = ["de", "en", "fr", "ja"];
const value = -45;
const unit = "minute";
for (const locale of locales) {
const rtf = new Intl.RelativeTimeFormat(locale, { style: "long", numeric: "always" });
console.log(`${locale}: ${rtf.format(value, unit)}`);
}formatToParts – Ausgabe zerlegen
const rtf = new Intl.RelativeTimeFormat("de", { numeric: "always", style: "long" });
const parts = rtf.formatToParts(-3, "day");
console.log(parts);
// Einzelne Teile individuell weiterverarbeiten:
const formatted = parts
.map(p => p.type === "integer" ? `<strong>${p.value}</strong>` : p.value)
.join("");
console.log(formatted); // z. B. für HTML: "vor <strong>3</strong> Tagen"Dynamischer Zeitstempel-Formatter (Praxis-Utility)
const rtf = new Intl.RelativeTimeFormat("de", { numeric: "auto" });
/**
* Gibt eine relative Zeitangabe für ein Date-Objekt zurück.
* @param {Date} date
* @returns {string}
*/
const relativeTime = (date) => {
const diffMs = date - Date.now();
const diffSecs = Math.round(diffMs / 1_000);
const diffMins = Math.round(diffSecs / 60);
const diffHrs = Math.round(diffMins / 60);
const diffDays = Math.round(diffHrs / 24);
if (Math.abs(diffSecs) < 60) return rtf.format(diffSecs, "second");
if (Math.abs(diffMins) < 60) return rtf.format(diffMins, "minute");
if (Math.abs(diffHrs) < 24) return rtf.format(diffHrs, "hour");
return rtf.format(diffDays, "day");
};
const fiveMinutesAgo = new Date(Date.now() - 5 * 60 * 1_000);
console.log(relativeTime(fiveMinutesAgo)); // "vor 5 Minuten"
const inTwoDays = new Date(Date.now() + 2 * 24 * 60 * 60 * 1_000);
console.log(relativeTime(inTwoDays)); // "übermorgen"// Wichtig · Fallstricke
Browser-Kompatibilität: Intl.RelativeTimeFormat ist seit Chrome 71, Firefox 65, Safari 14 und Edge 79 verfügbar. Node.js unterstützt es ab Version 12 (mit vollständigen ICU-Daten). Ältere Umgebungen benötigen ein Polyfill (z. B. @formatjs/intl-relativetimeformat).
numeric: "auto" vs. "always": Die Verfügbarkeit natürlicher Formen (wie „gestern", „morgen", „heute") hängt von der jeweiligen Sprache und dem Locale-Datensatz der Laufzeitumgebung ab. In Node.js kann es je nach Build (Full-ICU vs. Small-ICU) zu abweichenden Ergebnissen kommen.
Keine automatische Berechnung: Intl.RelativeTimeFormat berechnet keine Zeitdifferenzen selbst – es formatiert nur übergebene Zahlenwerte. Die Berechnung der Differenz (z. B. in Minuten oder Tagen) muss die aufrufende Anwendung selbst vornehmen.
Einheiten: Gültige Werte für den unit-Parameter sind: "year", "quarter", "month", "week", "day", "hour", "minute", "second" – jeweils auch in der Pluralform (z. B. "days").