# gt-react: General Translation React SDK: RelativeTime
URL: https://generaltranslation.com/fr/docs/react/api/components/relativetime.mdx
---
title: RelativeTime
description: Référence de l’API du composant RelativeTime
---

{/* GÉNÉRÉ AUTOMATIQUEMENT : ne modifiez pas directement. Modifiez plutôt le template dans content/docs-templates/. */}


## Vue d’ensemble

Le composant `<RelativeTime>` affiche une chaîne de caractères localisée de temps relatif, telle que &quot;il y a 2 heures&quot; ou &quot;dans 3 jours&quot;.
Il prend en charge deux modes d’utilisation : sélectionner automatiquement l’unité la plus appropriée à partir d’une `Date`, ou spécifier explicitement une valeur et une unité.

```jsx
<RelativeTime>{someDate}</RelativeTime>
// Résultat : "il y a 2 heures"
```

Le formatage est entièrement géré localement à l’aide de l’API [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat).

<Callout type="warn">
  `<RelativeTime>` peut provoquer des **erreurs d’hydratation React** dans les applications rendues côté serveur. Voir [Éviter les erreurs d’hydratation](#avoiding-hydration-errors) ci-dessous.
</Callout>


## Référence

### Props

<TypeTable
  type={{
  "children?": {
      description: 'Objet Date à partir duquel calculer le temps relatif.',
      type: 'Date',
      optional: true,
      default: 'undefined',
  },
  "date?": {
      description: 'Objet Date à partir duquel calculer le temps relatif. Prend le pas sur children.',
      type: 'Date',
      optional: true,
      default: 'undefined',
  },
  "value?": {
      description: 'Valeur numérique explicite pour le temps relatif. Nécessite unit.',
      type: 'number',
      optional: true,
      default: 'undefined',
  },
  "unit?": {
      description: 'Unité de temps. Obligatoire lors de l’utilisation de value.',
      type: 'Intl.RelativeTimeFormatUnit',
      optional: true,
      default: 'undefined',
  },
  "baseDate?": {
      description: 'Date de base pour calculer le temps relatif. Par défaut, new Date() au moment du rendu.',
      type: 'Date',
      optional: true,
      default: 'new Date()',
  },
  "name?": {
      type: 'chaîne de caractères',
      optional: true,
      default: 'undefined',
  },
  "options?": {
      type: 'Intl.RelativeTimeFormatOptions',
      optional: true,
      default: "{ numeric: 'auto', style: 'long' }",
  },
  "locales?": {
      type: 'chaîne de caractères[]',
      optional: true,
      default: 'undefined',
  },
}}
/>

### Description

| Nom de la propriété | Description                                                                                                                                                                                                                                                                                                                                                             |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children`          | Un objet `Date`. Le composant sélectionne automatiquement l’unité la plus appropriée (secondes, minutes, heures, jours, semaines, mois ou années) et met en forme le temps relatif par rapport à `baseDate`.                                                                                                                                                            |
| `date`              | Un objet `Date` à partir duquel calculer le temps relatif. Si `date` et `children` sont tous deux fournis, `date` prévaut.                                                                                                                                                                                                                                              |
| `value`             | Une valeur numérique explicite pour le temps relatif (par exemple, `-1` pour « hier »). Doit être utilisée avec `unit`.                                                                                                                                                                                                                                                 |
| `unit`              | L’unité de temps (par exemple, `'second'`, `'minute'`, `'hour'`, `'day'`, `'week'`, `'month'`, `'year'`). Obligatoire lors de l’utilisation de `value`.                                                                                                                                                                                                                 |
| `baseDate`          | La date de base pour calculer le temps relatif. Par défaut, `new Date()` est utilisé au moment du rendu. **Définissez-la explicitement pour éviter les erreurs d’hydratation** — voir [ci-dessous](#avoiding-hydration-errors).                                                                                                                                         |
| `options`           | Options de formatage facultatives conformes à la spécification [`Intl.RelativeTimeFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat). Les valeurs par défaut sont `numeric: 'auto'` et `style: 'long'`.                                                                                          |
| `locales`           | Paramètres régionaux facultatifs pour définir le paramètre régional de formatage. S’ils ne sont pas fournis, le paramètre régional de l’utilisateur est utilisé. Pour en savoir plus sur la manière de spécifier les paramètres régionaux, consultez [ce lien](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument). |

### Renvoie

`JSX.Element` contenant le temps relatif formaté sous forme de chaîne de caractères, ou `null` si aucune date ou valeur n’est fournie.

***

## Exemples

### Sélection automatique de l’unité à partir d’une `Date`

Passez une `Date` comme enfant et le composant choisit automatiquement l’unité la plus adaptée.

```jsx title="PostTimestamp.jsx" copy
import { RelativeTime } from 'gt-react';

export default function PostTimestamp({ post }) {
    return (
        <RelativeTime>{post.createdAt}</RelativeTime> // [!code highlight]
    );
    // Résultat : "il y a 2 heures", "il y a 3 jours", "dans 5 minutes", etc.
}
```


### Utilisation de la propriété date

Vous pouvez également transmettre la date via la propriété `date` plutôt que via `children`.

```jsx title="PostTimestamp.jsx" copy
import { RelativeTime } from 'gt-react';

export default function PostTimestamp({ post }) {
    return (
        <RelativeTime date={post.createdAt} /> // [!code highlight]
    );
}
```


### Valeur et unité explicites

Spécifiez une valeur et une unité précises, comme dans l’API `Intl.RelativeTimeFormat`.

```jsx title="Reminder.jsx" copy
import { RelativeTime } from 'gt-react';

export default function Reminder() {
    return (
        <p>
            Your trial ends <RelativeTime value={3} unit="day" />. // [!code highlight]
        </p>
    );
    // Résultat : "Your trial ends in 3 days."
}
```


### Spécifier les paramètres régionaux

Affichez le temps relatif dans un paramètre régional spécifique.

```jsx title="FrenchTimestamp.jsx" copy
import { RelativeTime } from 'gt-react';

export default function FrenchTimestamp({ date }) {
    return (
        <RelativeTime locales={['fr-FR']}>{date}</RelativeTime> // [!code highlight]
    );
    // Résultat : "il y a 2 heures"
}
```


### Traduction de RelativeTime

Encapsulez `<RelativeTime>` dans un composant `<T>` pour l’intégrer dans une phrase traduite.

```jsx title="Comment.jsx" copy
import { T, RelativeTime } from 'gt-react';

export default function Comment({ comment }) {
    return (
        <T id="commentPosted">
            Posted <RelativeTime>{comment.createdAt}</RelativeTime> // [!code highlight]
        </T>
    );
}
```


### Options de formatage personnalisées

Contrôlez le rendu avec les options de `Intl.RelativeTimeFormat`.

```jsx title="NumericTimestamp.jsx" copy
import { RelativeTime } from 'gt-react';

export default function NumericTimestamp({ date }) {
    return (
        <RelativeTime
            options={{
                numeric: 'always', // [!code highlight]
                style: 'narrow', // [!code highlight]
            }}
        >
            {date}
        </RelativeTime>
    );
    // Avec numeric: 'always', affiche "il y a 1 jour" au lieu de "hier"
}
```

***


## Éviter les erreurs d’hydratation

Comme `<RelativeTime>` calcule le temps relatif localement, il peut produire **un résultat différent côté serveur et côté client**. Lorsque React compare le HTML généré côté serveur au rendu côté client et qu’ils ne correspondent pas, cela provoque une erreur d’hydratation.

Cela se produit généralement dans les cas suivants :

* **`baseDate` utilise par défaut `new Date()` au moment du rendu.** Le serveur effectue le rendu à un instant donné, puis le client s’hydrate quelques secondes (ou plus) plus tard. Si le temps relatif franchit une limite d’unité entre ces deux instants (par ex., &quot;il y a 59 secondes&quot; → &quot;il y a 1 minute&quot;), le résultat ne correspondra pas.
* **Le paramètre régional par défaut diffère selon l’environnement.** Si le paramètre régional par défaut du serveur ne correspond pas à celui du client, la chaîne de caractères formatée peut être différente (par ex., &quot;hace 2 horas&quot; vs &quot;2 hours ago&quot;).

### Comment corriger le problème

**Définissez un `baseDate` explicite** pour garantir que le serveur et le client calculent le même temps relatif :

```jsx
const now = new Date(); // calculé une fois, transmis au serveur et au client

<RelativeTime baseDate={now}>{post.createdAt}</RelativeTime>
```

**Spécifiez explicitement `locales`** pour éviter les discordances de paramètres régionaux :

```jsx
<RelativeTime locales={['en-US']} baseDate={now}>
  {post.createdAt}
</RelativeTime>
```

En fixant à la fois le paramètre régional et la date de référence, le serveur et le client produiront toujours la même chaîne de caractères formatée.


## Remarques

* Le composant `<RelativeTime>` est un composant variable qui assure le formatage des valeurs de temps relatif.
* En mode auto (avec un `Date`), le composant sélectionne automatiquement l’unité la plus appropriée.
* Le composant utilise [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) en interne.
* Les options de formatage par défaut sont `numeric: 'auto'` et `style: 'long'`.

## Étapes suivantes

* Pour plus de détails et d’exemples d’utilisation du composant `<RelativeTime>` et d’autres composants variables comme `<DateTime>`, `<Currency>`, `<Num>` et `<Var>`, consultez la documentation [Utiliser les composants variables](/docs/react/guides/variables).