Intl.RelativeTimeFormat

L'objet Intl.RelativeTimeFormat est un constructeur fournissant des objets pour mettre en forme des données temporelles relatives en respectant le format des locales.

Le code source de cet exemple interactif est disponible dans un dépôt GitHub. Si vous souhaitez contribuez à ces exemples, n'hésitez pas à cloner https://github.com/mdn/interactive-examples et à envoyer une pull request !

new Intl.RelativeTimeFormat([locales[, options]])

locales

Une chaine de caractères avec un identifiant de langue BCP 47, ou un tableau de ce type de chaine de caractères. Pour le format général et l'interprétation de l'argument locales, voir la page Intl.

options Facultatif

Optionnel, un objet possédant tout ou partie des propriétés suivantes :

localeMatcher

L'algorithme de correspondance à utiliser pour la locale. Les valeurs possibles sont "lookup" et "best fit" ; le défaut est "best fit". Pour des informations sur cette option, voir la page Intl.

numeric

Le format du message de sortie. Les valeurs possibles sont "always" (par exemple 1 day ago) ou  "auto" (par exemple yesterday). "auto" permet de ne pas toujours avoir de valeurs numériques dans le message produit.

style

La longueur du message internationalisé. Les valeurs possibles sont : "long" (la valeur par défaut) (par exemple : in 1 month), "short" (par exemple : in 1 mo.) ou  "narrow" (par exemple : in 1 mo.). Le style narrow peut être semblable au style short pour certaines locales.

Intl.RelativeTimeFormat.prototype

Cette propriété permet d'ajouter des propriétés à l'ensemble des instances.

Intl.RelativeTimeFormat.supportedLocalesOf()

Cette méthode renvoie un tableau des locales, parmi celles passées en argument, qui sont pris en charge pour le formatage internationalisé des temps relatifs sans qu'il y ait besoin d'utiliser la locale par défaut de l'environnement d'exécution.

Les instances de RelativeTimeFormat héritent des propriétés suivantes grâce à leur prototype :

Intl.RelativeTimeFormat.prototype.constructor

Une référence à Intl.RelativeTimeFormat.

Les instances de RelativeTimeFormat héritent des méthodes suivantes grâce à leur prototype :

Intl.RelativeTimeFormat.prototype.format()

Une méthode qui formate une valeur, accompagnée d'une unité selon des options de locales et de formatage stockées dans l'objet Intl.RelativeTimeFormat.

Intl.RelativeTimeFormat.prototype.formatToParts()

Une méthode qui formate une valeur comme la méthode format() mais qui renvoie un tableau (Array) contenant les différentes parties de la valeur formatée.

Intl.RelativeTimeFormat.prototype.resolvedOptions()

Une méthode qui renvoie un objet dont les propriétés indique les options de locale et de formatage calculées lors de l'initialisation du formateur.

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"

Si l'option numeric:auto est passée, on aura la chaîne de caractères yesterday ou tomorrow plutôt que 1 day ago ou in 1 day. De cette façon, on peut ne pas avoir de valeur numérique dans la valeur produite.

// On crée un formateur en anglais avec l'option
// numeric: "auto".
const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });

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

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

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" }]

• L'API Intl.RelativeTimeFormat, un billet de Mathias Bynens (en anglais)