# gt-next: General Translation Next.js SDK: RelativeTime
URL: https://generaltranslation.com/fr/docs/next/api/components/relativetime.mdx
---
title: RelativeTime
description: Référence API du composant RelativeTime
---

{/* GÉNÉRÉ AUTOMATIQUEMENT : ne modifiez pas ce fichier 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 au format de temps relatif, comme &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’un `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é en local à 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 de 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 servant à calculer le temps relatif.',
      type: 'Date',
      optional: true,
      default: 'undefined',
  },
  "date?": {
      description: 'Objet Date servant à calculer le temps relatif. Est prioritaire 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 si vous utilisez 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: 'string',
      optional: true,
      default: 'undefined',
  },
  "options?": {
      type: 'Intl.RelativeTimeFormatOptions',
      optional: true,
      default: "{ numeric: 'auto', style: 'long' }",
  },
  "locales?": {
      type: 'string[]',
      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 formate la date en temps relatif par rapport à `baseDate`.                                                                                                                              |
| `date`              | Un objet `Date` servant à calculer le temps relatif. Si `date` et `children` sont tous deux fournis, `date` est prioritaire.                                                                                                                                                                                                                 |
| `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 utilisée pour calculer le temps relatif. La valeur par défaut est `new Date()` 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`           | `locales` facultatifs pour spécifier le paramètre régional de formatage. Si aucune valeur n’est fournie, le paramètre régional de l’utilisateur est utilisé. Pour en savoir plus sur la façon de spécifier `locales`, cliquez [ici](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument). |

### Valeur de retour

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

***

## Exemples

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

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

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

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` au lieu de `children`.

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

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


### Valeur et unité explicites

Spécifiez une valeur exacte et une unité, à l’image de l’API `Intl.RelativeTimeFormat`.

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

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 pour un paramètre régional donné.

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

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


### Traduire RelativeTime

Entourez `<RelativeTime>` d’un composant `<T>` pour l’inclure dans une phrase traduite.

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

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 format de sortie à l’aide des options de `Intl.RelativeTimeFormat`.

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

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 client et qu’ils ne correspondent pas, une erreur d’hydratation se produit.

Cela se produit généralement lorsque :

* **`baseDate` prend par défaut la valeur `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 change d’unité entre ces deux moments (par ex., &quot;59 seconds ago&quot; → &quot;1 minute ago&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 différer (par ex., &quot;hace 2 horas&quot; vs &quot;2 hours ago&quot;).

### Comment résoudre ce 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 formate 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 [Utilisation des composants variables](/docs/next/guides/variables).