Intl.RelativeTimeFormat.prototype.format() — Methode · JavaScript-Referenz

Signatur

Intl.RelativeTimeFormat.prototype.format(value, unit)

Beschreibung

Die Methode format() wandelt eine Zahl (value) und eine Zeiteinheit (unit) in eine lesbare, sprachabhängige relative Zeitangabe um. Negative Werte stehen für die Vergangenheit („vor 2 Stunden“), positive für die Zukunft („in 2 Stunden“). Sprache, Länge der Ausgabe und die Frage, ob Wörter wie „gestern“ oder „morgen“ verwendet werden, legt man beim Erzeugen des Intl.RelativeTimeFormat-Objekts fest.

Typische Einsatzgebiete sind Zeitstempel in Kommentarbereichen, Chats, Benachrichtigungen oder Aktivitätsprotokollen („zuletzt aktiv vor 5 Minuten“). Weil die Pluralregeln und Satzstellungen jeder Sprache korrekt berücksichtigt werden, entfällt manuelles Zusammenbauen von Zeichenketten.

Wichtig: format() rechnet nicht selbst mit Datumswerten. Die Differenz zwischen zwei Zeitpunkten und die passende Einheit muss man selbst bestimmen. Außerdem sollte die Instanz wiederverwendet werden, da das Erzeugen eines Intl-Formatierers vergleichsweise teuer ist.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	number \| string		Numerischer Wert der relativen Zeitangabe. Negativ = Vergangenheit, positiv = Zukunft. Zeichenketten werden in Zahlen umgewandelt; Nachkommastellen sind erlaubt.
$unit Pflicht	"year" \| "quarter" \| "month" \| "week" \| "day" \| "hour" \| "minute" \| "second"		Zeiteinheit. Pluralformen wie `"days"` oder `"hours"` werden ebenfalls akzeptiert. `"millisecond"` wird nicht unterstützt.

Rückgabewert

Typ

string

Beschreibung

Die formatierte relative Zeitangabe als Zeichenkette, z. B. "vor 3 Tagen" oder "morgen".

Beispiele

Grundlegende Formatierung auf Deutsch

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

console.log(rtf.format(-1, "day"));
console.log(rtf.format(3, "hour"));
console.log(rtf.format(-2, "weeks"));
console.log(rtf.format(1.5, "hour"));

vor 1 Tag in 3 Stunden vor 2 Wochen in 1,5 Stunden

Natürliche Sprache mit numeric: "auto"

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, "day"));
console.log(rtf.format(2, "day"));
console.log(rtf.format(-1, "year"));

gestern heute morgen übermorgen letztes Jahr

Kurzformen und andere Sprachen

const kurz = new Intl.RelativeTimeFormat("de", { style: "short" });
const en = new Intl.RelativeTimeFormat("en", { style: "long" });

console.log(kurz.format(-5, "minute"));
console.log(en.format(3, "month"));
console.log(en.format(-1, "day"));

vor 5 Min. in 3 months 1 day ago

Praxis: „vor X“-Anzeige aus einem Datum berechnen

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 = Math.round((datum - jetzt) / 1000);
  for (const [unit, sek] of EINHEITEN) {
    if (Math.abs(diffSek) >= sek || unit === "second") {
      return rtf.format(Math.round(diffSek / sek), unit);
    }
  }
};

const jetzt = new Date("2024-05-10T12:00:00");
console.log(relativeZeit(new Date("2024-05-10T11:45:00"), jetzt));
console.log(relativeZeit(new Date("2024-05-09T10:00:00"), jetzt));
console.log(relativeZeit(new Date("2024-05-24T12:00:00"), jetzt));

vor 15 Minuten gestern in 2 Wochen

// Wichtig · Fallstricke

RangeError: Eine ungültige Einheit (z. B. \"millisecond\" oder \"decade\") oder ein nicht endlicher Wert (NaN, Infinity) löst einen RangeError aus.
Negative Null: -0 gilt als Vergangenheit: rtf.format(-0, \"second\") ergibt „vor 0 Sekunden“, 0 dagegen „in 0 Sekunden“. Werte, die durch Rundung zu -0 werden, eventuell mit || 0 normalisieren.
Keine Datumsberechnung: Die Methode kennt keine Kalender, Monatslängen oder Zeitzonen – die Differenz und die Wahl der Einheit liegen beim Aufrufer.
Ausgabe nicht fest verdrahten: Die genauen Texte stammen aus den CLDR-Daten der Engine und können sich zwischen Browsern und Versionen leicht unterscheiden. Nicht in Tests auf exakte Zeichenketten vergleichen, ohne die Umgebung festzulegen.
Performance: Formatierer einmal erzeugen und wiederverwenden, statt bei jedem Aufruf new Intl.RelativeTimeFormat() auszuführen.
Kompatibilität: In allen modernen Browsern (Chrome 71+, Firefox 65+, Safari 14+) und Node.js 12+ verfügbar; in älteren Node-Builds ohne volle ICU-Daten fallen viele Sprachen auf Englisch zurück.

Siehe auch

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