# General Translation Platform: formatRelativeTime
URL: https://generaltranslation.com/fr/docs/platform/core/reference/utility-functions/formatting/format-relative-time.mdx
---

title: formatRelativeTime
description: Met en forme des valeurs de temps relatif sans instance GT. Référence API pour formatRelativeTime.

---

[`formatRelativeTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time) est une fonction utilitaire autonome de la bibliothèque Core de General Translation qui met en forme une valeur de temps relatif avec une unité explicite, selon les conventions du paramètre régional. Elle renvoie des chaînes comme "il y a 2 heures" ou "dans 3 jours".

## Vue d’ensemble [#overview]

Importez `formatRelativeTime` directement depuis `generaltranslation`, puis appelez cette fonction avec une valeur, une unité et un objet d’options. Elle ne nécessite ni clé API ni instance [GT](/docs/platform/core/reference/gt-class/constructor). Pour un formatage via une instance qui hérite du paramètre régional de celle-ci, utilisez plutôt la méthode [`formatRelativeTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time) sur une instance [`GT`](/docs/platform/core/reference/gt-class/constructor). Pour sélectionner automatiquement l’unité à partir d’une `Date`, utilisez [`formatRelativeTimeFromDate`](/docs/platform/core/reference/utility-functions/formatting/format-relative-time-from-date).

```typescript
import { formatRelativeTime } from 'generaltranslation';

const formatted = formatRelativeTime(-1, 'day', {
  locales: 'en-US',
  numeric: 'auto',
});
// Retourne : "yesterday"
```

Signature :

```typescript
formatRelativeTime(
  value: number,
  unit: Intl.RelativeTimeFormatUnit,
  options?: { locales?: string | string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>
): string
```

## Fonctionnement [#how-it-works]

* **API sous-jacente.** S’appuie sur [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) en interne.
* **Convention de signe.** Les valeurs négatives correspondent au passé ; les valeurs positives, au futur.
* **Mode numérique.** La valeur par défaut est `numeric: 'auto'`. Ainsi, des valeurs comme `-1 day` produisent « hier » au lieu de « il y a 1 jour ». Définissez `numeric: 'always'` pour forcer un affichage numérique.
* **Résolution du paramètre régional.** Lorsque `locales` est omis, le système utilise comme valeur de repli le paramètre régional par défaut de la bibliothèque, `en`.
* **Mise en cache.** Les résultats sont mis en cache en interne afin d’améliorer les performances lorsque les mêmes combinaisons de paramètres régionaux et d’options sont réutilisées.

## Paramètres [#parameters]

| Paramètre             | Description                                                                      | Type                                                                                 | Facultatif | Par défaut |
| --------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------- | ---------- |
| [`value`](#value)     | La valeur de temps relatif (négative pour le passé, positive pour le futur).     | `number`                                                                             | Non        | —          |
| [`unit`](#unit)       | L’unité de temps.                                                                | `Intl.RelativeTimeFormatUnit`                                                        | Non        | —          |
| [`options`](#options) | Configuration de mise en forme, y compris le ou les paramètres régionaux cibles. | `{ locales?: string \| string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>` | Oui        | `{}`       |

### `value` [#value]

**Type** `number` · **Obligatoire**

La valeur de temps relatif. Les nombres négatifs représentent le passé, les nombres positifs le futur.

### `unit` [#unit]

**Type** `Intl.RelativeTimeFormatUnit` · **Obligatoire**

L’unité de temps : `'second'`, `'minute'`, `'hour'`, `'day'`, `'week'`, `'month'` ou `'year'`.

### `options` [#options]

**Type** `{ locales?: string | string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>` · **Facultatif** · **Par défaut** `{}`

Options de formatage :

| Propriété       | Description                                                         | Type                            | Facultatif | Par défaut   |
| --------------- | ------------------------------------------------------------------- | ------------------------------- | ---------- | ------------ |
| `locales`       | Paramètre(s) régional(aux) à utiliser pour le formatage.            | `string \| string[]`            | Oui        | `en`         |
| `numeric`       | Indique s’il faut toujours utiliser un format numérique.            | `'always' \| 'auto'`            | Oui        | `'auto'`     |
| `style`         | La longueur de la sortie.                                           | `'long' \| 'short' \| 'narrow'` | Oui        | `'long'`     |
| `localeMatcher` | L’algorithme de correspondance des paramètres régionaux à utiliser. | `'best fit' \| 'lookup'`        | Oui        | `'best fit'` |

## Valeur de retour [#returns]

**Type** `string`

La chaîne de caractères de temps relatif mise en forme.

## Exemples [#examples]

```typescript
import { formatRelativeTime } from 'generaltranslation';

// Temps passé
console.log(formatRelativeTime(-2, 'hour', { locales: 'en-US' }));
// Sortie : "2 hours ago"

// Temps futur
console.log(formatRelativeTime(3, 'day', { locales: 'en-US' }));
// Sortie : "in 3 days"

// Avec numeric : 'auto' (par défaut)
console.log(formatRelativeTime(-1, 'day', { locales: 'en-US' }));
// Sortie : "yesterday"
```

```typescript
// Styles de formatage

// Style long (par défaut)
console.log(formatRelativeTime(-2, 'day', {
  locales: 'en-US',
  style: 'long',
}));
// Résultat : "2 days ago"

// Style court
console.log(formatRelativeTime(-2, 'day', {
  locales: 'en-US',
  style: 'short',
}));
// Résultat : "2 days ago" (peut être abrégé dans certains locales)

// Style condensé
console.log(formatRelativeTime(-2, 'day', {
  locales: 'en-US',
  style: 'narrow',
}));
// Résultat : "2d ago"
```

```typescript
// Plusieurs paramètres régionaux
const locales = ['en-US', 'fr-FR', 'ja-JP', 'de-DE'];

locales.forEach((locale) => {
  console.log(`${locale}: ${formatRelativeTime(-3, 'hour', { locales: locale })}`);
});
// Sortie :
// en-US: 3 hours ago
// fr-FR: il y a 3 heures
// ja-JP: 3 時間前
// de-DE: vor 3 Stunden
```

## Remarques [#notes]

* La valeur par défaut est `numeric: 'auto'` et `style: 'long'`.
* Avec `numeric: 'auto'`, des valeurs comme `-1 day` renvoient « hier » au lieu de « il y a 1 jour ».
* S’appuie en interne sur [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat).
* Les résultats sont mis en cache en interne pour de meilleures performances lorsque les mêmes combinaisons de paramètres régionaux et d’options sont réutilisées.