# General Translation React SDKs (gt-react, gt-next, gt-react-native): `<RelativeTime>`
URL: https://generaltranslation.com/fr/docs/react/reference/components/relative-time.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Référence API du composant `<RelativeTime>` pour formater un temps relatif localisé, par exemple il y a 2 heures.

Le composant `<RelativeTime>` affiche une formulation de temps relatif conforme aux conventions d’unité et de phrasé du paramètre régional actif. Il fonctionne soit en sélectionnant automatiquement l’unité la plus appropriée à partir d’un `Date`, soit à partir d’une valeur et d’une unité explicites.

*Disponible dans `gt-react`, `gt-next`, `gt-tanstack-start` et `gt-react-native`.*

## Vue d’ensemble [#overview]

Passez une valeur `Date` comme élément enfant, et `<RelativeTime>` choisira automatiquement l’unité la plus appropriée pour formater la date de manière relative à `baseDate`.

```tsx
<RelativeTime>{someDate}</RelativeTime>
// Résultat : "2 hours ago"
```

Toute la mise en forme est gérée localement avec [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat).

*Remarque : `<RelativeTime>` peut provoquer des erreurs d’hydratation de React dans les applications à rendu côté serveur. Voir [Éviter les erreurs d’hydratation](#hydration).*

## Fonctionnement [#how-it-works]

* **Deux modes.** Fournissez un `Date` (via `élément enfant` ou `date`) et le composant sélectionne automatiquement l’unité la plus appropriée par rapport à `baseDate`, ou fournissez un `value` et une `unit` explicites, à l’image de `Intl.RelativeTimeFormat`.
* **Formatage local.** Le temps relatif est calculé et mis en forme dans le navigateur ; la valeur n’est jamais envoyée à l’API de General Translation.
* **Aucun rendu sans entrée.** Si aucune date ni aucune valeur n’est fournie, le composant renvoie `null`.

## Props [#props]

| Prop                     | Description                                                                         | Type                             | Facultatif | Par défaut                           |
| ------------------------ | ----------------------------------------------------------------------------------- | -------------------------------- | ---------- | ------------------------------------ |
| [`children`](#children)  | Une valeur `Date` à partir de laquelle calculer le temps relatif.                   | `Date`                           | Oui        | —                                    |
| [`date`](#date)          | Une valeur `Date` à partir de laquelle effectuer le calcul. Prévaut sur `élément enfant`. | `Date`                           | Oui        | —                                    |
| [`value`](#value)        | Valeur numérique explicite. Nécessite `unit`.                                       | `number`                         | Oui        | —                                    |
| [`unit`](#unit)          | Unité de temps, utilisée avec `value`.                                              | `Intl.RelativeTimeFormatUnit`    | Oui        | —                                    |
| [`baseDate`](#base-date) | Date de référence pour le calcul.                                                   | `Date`                           | Oui        | `new Date()`                         |
| [`options`](#options)    | Options de `Intl.RelativeTimeFormat`.                                               | `Intl.RelativeTimeFormatOptions` | Oui        | `{ numeric: 'auto', style: 'long' }` |
| [`locales`](#locales)    | Paramètre régional à utiliser à la place de celui par défaut pour le formatage.     | `string[]`                       | Oui        | Paramètre régional actif             |
| [`name`](#name)          | Nom de variable pour l’entrée.                                                      | `string`                         | Oui        | —                                    |

### `children` [#children]

**Type** `Date` · **Facultatif**

Un objet `Date`. Le composant sélectionne automatiquement l’unité la plus appropriée (des secondes aux années) et met en forme l’heure de manière relative à `baseDate`.

### `date` [#date]

**Type** `Date` · **Facultatif**

Une valeur `Date` à partir de laquelle calculer le temps relatif. Lorsque `date` et `élément enfant` sont tous les deux fournis, `date` est prioritaire.

### `value` [#value]

**Type** `number` · **Facultatif**

Valeur numérique explicite du temps relatif (par exemple, `-1` pour « hier »). Doit être utilisée avec `unit`.

### `unit` [#unit]

**Type** `Intl.RelativeTimeFormatUnit` · **Facultatif**

L’unité de temps, par exemple `'second'`, `'minute'`, `'hour'`, `'day'`, `'week'`, `'month'` ou `'year'`. Obligatoire si vous utilisez `value`.

### `baseDate` [#base-date]

**Type** `Date` · **Facultatif** · **Par défaut** `new Date()`

La date de référence utilisée pour calculer le temps relatif. Par défaut, elle vaut `new Date()` au moment du rendu. Définissez-la explicitement pour éviter les erreurs d’hydratation — voir [ci-dessous](#hydration).

### `options` [#options]

**Type** `Intl.RelativeTimeFormatOptions` · **Facultatif** · **Par défaut** `{ numeric: 'auto', style: 'long' }`

La prop utilise [`Intl.RelativeTimeFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options). `<RelativeTime>` prend actuellement en charge les options suivantes :

| Option          | Description                                                                                                        | Type                            | Facultatif | Par défaut   |
| --------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------- | ---------- | ------------ |
| `localeMatcher` | Algorithme de correspondance des paramètres régionaux.                                                             | `'lookup' \| 'best fit'`        | Oui        | `'best fit'` |
| `style`         | Longueur de la formulation du temps relatif.                                                                       | `'long' \| 'short' \| 'narrow'` | Oui        | `'long'`     |
| `numeric`       | Indique s&#39;il faut toujours utiliser un nombre ou autoriser des formulations telles que « hier » et « demain ». | `'always' \| 'auto'`            | Oui        | `'auto'`     |

Les autres champs du type TypeScript plus large `Intl.RelativeTimeFormatOptions` ne sont pas transmis par `<RelativeTime>`.

Consultez la [documentation des options de `Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options) pour connaître les dernières options standard. Reportez-vous au tableau ci-dessus pour les options actuellement prises en charge par `<RelativeTime>`.

### `locales` [#locales]

**Type** `string[]` · **Facultatif** · **Par défaut** paramètre régional actif

Paramètres régionaux à utiliser pour le formatage. Si cette propriété est omise, le paramètre régional actif est utilisé. Consultez l’[argument locales](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).

### `name` [#name]

**Type** `string` · **Facultatif**

Nom facultatif de l’entrée, utilisé comme métadonnée.

## Exemples [#examples]

*Les exemples importent depuis `gt-react` ; importez plutôt depuis le paquet correspondant à votre framework.*

```tsx title="PostTimestamp.tsx"
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.
}
```

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

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

```tsx title="Reminder.tsx"
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."
}
```

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

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

```tsx title="NumericTimestamp.tsx"
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 "1 day ago" au lieu de "yesterday"
}
```

## Éviter les erreurs d’hydratation [#hydration]

Comme `<RelativeTime>` calcule le temps relatif localement, il peut produire un résultat différent sur le serveur et côté client, ce qui provoque une erreur d’hydratation. Cela se produit généralement lorsque :

* **`baseDate` utilise `new Date()` par défaut au moment du rendu.** Le serveur et le client effectuent le rendu à des moments légèrement différents. Si le temps relatif franchit une limite d’unité entre les deux (par exemple, &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**, ce qui produit des chaînes différentes (par exemple, &quot;hace 2 horas&quot; vs. &quot;2 hours ago&quot;).

Fixez à la fois le paramètre régional et une `baseDate` commune pour que le serveur et le client produisent toujours la même chaîne :

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

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

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.