Intl.RelativeTimeFormat

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2020.

L'objet Intl.RelativeTimeFormat permet de mettre en forme des données temporelles relatives en respectant le format des locales.

Exemple interactif

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

console.log(rtf1.format(3, "quarter"));
// Expected output: "in 3 qtrs."

console.log(rtf1.format(-1, "day"));
// Expected output: "1 day ago"

const rtf2 = new Intl.RelativeTimeFormat("es", { numeric: "auto" });

console.log(rtf2.format(2, "day"));
// Expected output: "pasado mañana"

Constructeur

Intl.RelativeTimeFormat(): Crée un nouvel objet Intl.RelativeTimeFormat.

Méthodes statiques

Intl.RelativeTimeFormat.supportedLocalesOf(): Renvoie un tableau qui contient les locales, parmi celles fournies en arguments, qui sont prises en charge sans avoir à recourir à la locale par défaut de l'environnement d'exécution.

Méthodes des instances

Intl.RelativeTimeFormat.prototype.format(): Formate une valeur et une unité en fonction des options de locale et de formatage fournies par l'objet Intl.RelativeTimeFormat courant.
Intl.RelativeTimeFormat.prototype.formatToParts(): Renvoie un tableau d'objets représentant le temps relatif sous forme de fragments qui peuvent être utilisés afin de réaliser un formatage tenant compte de la locale sur mesure.
Intl.RelativeTimeFormat.prototype.resolvedOptions(): Renvoie un nouvel objet dont les propriétés reflètent les options de locale et de collation calculées à l'initialisation de l'objet.

Exemples

Utiliser `format()`

L'exemple suivant illustre comment créer un formateur de temps relatif en anglais :

// On crée un formateur en anglais en utilisant explicitement
// les valeurs par défaut.
const rtf = new Intl.RelativeTimeFormat("en", {
  localeMatcher: "best fit", // autre valeur possible : "lookup"
  numeric: "always", // autre valeur possible : "auto"
  style: "long", // autre valeur possible : "short" ou "narrow"
});

// On formate un temps relatif avec une valeur négative (-1).
rtf.format(-1, "day");
// > "1 day ago"

// On formate un temps relatif avec une valeur positive (1).
rtf.format(1, "day");
// > "in 1 day"

Utiliser `formatToParts()`

L'exemple suivant illustre comment créer un formateur de temps relatif qui renvoie les différents fragments pour exprimer le temps relatif internationalisé.

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

// On crée un temps relatif exprimé en jour.
rtf.formatToParts(-1, "day");
// > [{ type: "literal", value: "yesterday"}]

rtf.formatToParts(100, "day");
// > [{ type: "literal", value: "in " },
// >  { type: "integer", value: "100", unit: "day" },
// >  { type: "literal", value: " days" }]

Spécifications

Specification
ECMAScript® 2026 Internationalization API Specification # relativetimeformat-objects