Skip to content

Translation of the hydrate page #531

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tdd merged 2 commits into from
Jul 16, 2023
Merged

Translation of the hydrate page #531

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b9bbf59
copy(hydrate): first full translation
tdd Jul 16, 2023
ba8f3d8
copy(hydrate): final review pass
tdd Jul 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 47 additions & 46 deletions src/content/reference/react-dom/hydrate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@ title: hydrate

<Deprecated>

This API will be removed in a future major version of React.
Cette API sera retirée d'une future version majeure de React.

In React 18, `hydrate` was replaced by [`hydrateRoot`.](/reference/react-dom/client/hydrateRoot) Using `hydrate` in React 18 will warn that your app will behave as if it’s running React 17. Learn more [here.](/blog/2022/03/08/react-18-upgrade-guide#updates-to-client-rendering-apis)
React 18 a remplacé `hydrate` par [`hydrateRoot`](/reference/react-dom/client/hydrateRoot). Utiliser `hydrate` avec React 18 vous avertira que votre appli se comportera comme dans React 17. [Apprenez-en davantage ici](/blog/2022/03/08/react-18-upgrade-guide#updates-to-client-rendering-apis).

</Deprecated>

<Intro>

`hydrate` lets you display React components inside a browser DOM node whose HTML content was previously generated by [`react-dom/server`](/reference/react-dom/server) in React 17 and below.
`hydrate` vous permet d'afficher des composants React au sein d'un nœud DOM dont le contenu HTML a été préalablement généré par [`react-dom/server`](/reference/react-dom/server) dans React 17 et antérieur.

```js
hydrate(reactNode, domNode, callback?)
Expand All @@ -24,68 +24,69 @@ hydrate(reactNode, domNode, callback?)

---

## Reference {/*reference*/}
## Référence {/*reference*/}

### `hydrate(reactNode, domNode, callback?)` {/*hydrate*/}

Call `hydrate` in React 17 and below to “attach” React to existing HTML that was already rendered by React in a server environment.
Appelez `hydrate` dans React 17 et antérieur pour « attacher » React à du HTML existant produit par React dans un environnement serveur.

```js
import { hydrate } from 'react-dom';

hydrate(reactNode, domNode);
```

React will attach to the HTML that exists inside the `domNode`, and take over managing the DOM inside it. An app fully built with React will usually only have one `hydrate` call with its root component.
React s'attachera au HTML existant au sein de `domNode`, et prendra en main la gestion du fragment DOM concerné. Une appli intégralement construite avec React n'aura généralement besoin que d'un appel à `hydrate`, pour son composant racine.

[See more examples below.](#usage)
[Voir d'autres exemples ci-dessous](#usage).

#### Parameters {/*parameters*/}
#### Paramètres {/*parameters*/}

* `reactNode`: The "React node" used to render the existing HTML. This will usually be a piece of JSX like `<App />` which was rendered with a `ReactDOM Server` method such as `renderToString(<App />)` in React 17.
* `reactNode` : le « nœud React » utilisé pour afficher le HTML existant. Ce sera généralement un bout de JSX du genre `<App />`, qui a été rendu côté serveur par une méthode de `ReactDOM Server` du style `renderToString(<App />)` dans React 17.

* `domNode`: A [DOM element](https://developer.mozilla.org/en-US/docs/Web/API/Element) that was rendered as the root element on the server.
* `domNode` : un [élément DOM](https://developer.mozilla.org/docs/Web/API/Element) que le serveur a utilisé comme élément racine dans son rendu.

* **optional**: `callback`: A function. If passed, React will call it after your component is hydrated.
* `callback` **optionnel** : une fonction. Si elle est passée, React l'appellera immédiatement après que le composant a été hydraté.

#### Returns {/*returns*/}
#### Valeur renvoyée {/*returns*/}

`hydrate` returns null.
`hydrate` renvoie `null`.

#### Caveats {/*caveats*/}
* `hydrate` expects the rendered content to be identical with the server-rendered content. React can patch up differences in text content, but you should treat mismatches as bugs and fix them.
* In development mode, React warns about mismatches during hydration. There are no guarantees that attribute differences will be patched up in case of mismatches. This is important for performance reasons because in most apps, mismatches are rare, and so validating all markup would be prohibitively expensive.
* You'll likely have only one `hydrate` call in your app. If you use a framework, it might do this call for you.
* If your app is client-rendered with no HTML rendered already, using `hydrate()` is not supported. Use [render()](/reference/react-dom/render) (for React 17 and below) or [createRoot()](/reference/react-dom/client/createRoot) (for React 18+) instead.
#### Limitations {/*caveats*/}

* `hydrate` s'attend à ce que le contenu produit soit identique à celui du rendu côté serveur. React peut colmater les différences de contenu textuel, mais tout écart doit être vu comme un bug et corrigé.
* En mode développement, React vous avertira de tout écart de correspondance durant l'hydratation. Vous n'avez aucune garantie que les différences d'attributs seront résolues. C'est important pour des raisons de performances parce que dans la plupart des applis, les écarts sont rares, aussi valider tout le balisage serait d'une lourdeur prohibitive.
* Vous n'aurez sans doute besoin que d'un appel à `hydrate` dans votre appli. Si vous utilisez un framework, il le fera peut-être pour vous.
* Si votre appli est entièrement côté client, sans HTML déjà généré par le serveur, appeler `hydrate()` n'est pas autorisé. Utilisez plutôt [`render()`](/reference/react-dom/render) (pour React 17 et antérieur) ou [`createRoot()`](/reference/react-dom/client/createRoot) (pour React 18+).

---

## Usage {/*usage*/}
## Utilisation {/*usage*/}

Call `hydrate` to attach a <CodeStep step={1}>React component</CodeStep> into a server-rendered <CodeStep step={2}>browser DOM node</CodeStep>.
Appelez `hydrate` pour attacher un <CodeStep step={1}>composant React</CodeStep> à un<CodeStep step={2}>nœud du DOM navigateur</CodeStep> dont le HTML était généré côté serveur.

```js [[1, 3, "<App />"], [2, 3, "document.getElementById('root')"]]
import { hydrate } from 'react-dom';

hydrate(<App />, document.getElementById('root'));
```

Using `hydrate()` to render a client-only app (an app without server-rendered HTML) is not supported. Use [`render()`](/reference/react-dom/render) (in React 17 and below) or [`createRoot()`](/reference/react-dom/client/createRoot) (in React 18+) instead.
N'utilisez pas `hydrate()` pour afficher une appli entièrement côté client (une appli sans HTML généré côté serveur). Utilisez plutôt[`render()`](/reference/react-dom/render) (pour React 17 et antérieur) ou [`createRoot()`](/reference/react-dom/client/createRoot) (pour React 18+).

### Hydrating server-rendered HTML {/*hydrating-server-rendered-html*/}
### Hydrater du HTML produit par le serveur {/*hydrating-server-rendered-html*/}

In React, "hydration" is how React "attaches" to existing HTML that was already rendered by React in a server environment. During hydration, React will attempt to attach event listeners to the existing markup and take over rendering the app on the client.
Dans React, « l'hydratation » est le mécanisme par lequel React « s'attache » à du HTML existant, déjà produit par React dans un environnement serveur. Durant l'hydratation, React tentera d'associer les gestionnaires d'événements au balisage existant et de prendre la main sur l'affichage de l'application côté client.

In apps fully built with React, **you will usually only hydrate one "root", once at startup for your entire app**.
Dans des applis entièrement construites avec React, **vous n'aurez généralement besoin d'hydrater qu'une « racine », une seule fois au démarrage de votre appli.**

<Sandpack>

```html public/index.html
<!--
HTML content inside <div id="root">...</div>
was generated from App by react-dom/server.
Le contenu HTML au sein de <div id="root">...</div>
a été généré à partir de App par react-dom/server.
-->
<div id="root"><h1>Hello, world!</h1></div>
<div id="root"><h1>Salut tout le monde !</h1></div>
```

```js index.js active
Expand All @@ -98,32 +99,32 @@ hydrate(<App />, document.getElementById('root'));

```js App.js
export default function App() {
return <h1>Hello, world!</h1>;
return <h1>Salut tout le monde !</h1>;
}
```

</Sandpack>

Usually you shouldn't need to call `hydrate` again or to call it in more places. From this point on, React will be managing the DOM of your application. To update the UI, your components will [use state.](/reference/react/useState)
En temps normal, vous ne devriez pas avoir besoin de rappeler `hydrate` ou de l'appeler à plusieurs endroits. À partir de ce moment-là, c'est React qui gèrera le DOM de votre application. Pour mettre à jour l'UI, vos composants utiliseront [l'état local](/reference/react/useState).

For more information on hydration, see the docs for [`hydrateRoot`.](/reference/react-dom/client/hydrateRoot)
Pour en savoir plus sur l'hydratation, consultez la documentation d'[`hydrateRoot`](/reference/react-dom/client/hydrateRoot).

---

### Suppressing unavoidable hydration mismatch errors {/*suppressing-unavoidable-hydration-mismatch-errors*/}
### Ignorer les incohérences d'hydratation incontournables {/*suppressing-unavoidable-hydration-mismatch-errors*/}

If a single element’s attribute or text content is unavoidably different between the server and the client (for example, a timestamp), you may silence the hydration mismatch warning.
Si un attribut ou contenu textuel d'un seul élément est forcément différent entre le serveur et le client (par exemple, un horodatage), vous pouvez réduire au silence l'avertissement d'écart à l'hydratation.

To silence hydration warnings on an element, add `suppressHydrationWarning={true}`:
Pour éviter les avertissements d'hydratation sur un élément, ajoutez-lui `suppressHydrationWarning={true}`:

<Sandpack>

```html public/index.html
<!--
HTML content inside <div id="root">...</div>
was generated from App by react-dom/server.
Le contenu HTML au sein de <div id="root">...</div>
a été généré à partir de App par react-dom/server.
-->
<div id="root"><h1>Current Date: 01/01/2020</h1></div>
<div id="root"><h1>Nous sommes le 01/01/2020</h1></div>
```

```js index.js
Expand All @@ -138,30 +139,30 @@ hydrate(<App />, document.getElementById('root'));
export default function App() {
return (
<h1 suppressHydrationWarning={true}>
Current Date: {new Date().toLocaleDateString()}
Nous sommes le {new Date().toLocaleDateString()}
</h1>
);
}
```

</Sandpack>

This only works one level deep, and is intended to be an escape hatch. Don’t overuse it. Unless it’s text content, React still won’t attempt to patch it up, so it may remain inconsistent until future updates.
Ça ne marche qu'à un niveau de profondeur, et c'est vraiment à voir comme une échappatoire. N'en abusez pas. À moins qu'il ne s'agisse de contenu textuel, React n'essaiera toujours pas de corriger le tir, ça peut donc rester incohérent jusqu'à des mises à jour ultérieures.

---

### Handling different client and server content {/*handling-different-client-and-server-content*/}
### Gérer des contenus client et serveur différents {/*handling-different-client-and-server-content*/}

If you intentionally need to render something different on the server and the client, you can do a two-pass rendering. Components that render something different on the client can read a [state variable](/reference/react/useState) like `isClient`, which you can set to `true` in an [effect](/reference/react/useEffect):
Si vous cherchez explicitement à produire un contenu différent sur le serveur et sur le client, vous pouvez faire un rendu en deux temps. Les composants qui ont un rendu différent côté client peuvent consulter une [variable d'état](/reference/react/useState) telle que `isClient`, que vous définirez à `true` dans un [Effet](/reference/react/useEffect) :

<Sandpack>

```html public/index.html
<!--
HTML content inside <div id="root">...</div>
was generated from App by react-dom/server.
Le contenu HTML au sein de <div id="root">...</div>
a été généré à partir de App par react-dom/server.
-->
<div id="root"><h1>Is Server</h1></div>
<div id="root"><h1>Côté serveur</h1></div>
```

```js index.js
Expand All @@ -184,18 +185,18 @@ export default function App() {

return (
<h1>
{isClient ? 'Is Client' : 'Is Server'}
{isClient ? 'Côté client' : 'Côté serveur'}
</h1>
);
}
```

</Sandpack>

This way the initial render pass will render the same content as the server, avoiding mismatches, but an additional pass will happen synchronously right after hydration.
Ainsi la passe de rendu initiale a le même contenu que le serveur, ce qui évite les écarts, mais une passe complémentaire survient de façon synchrone juste après l'hydratation.

<Pitfall>

This approach makes hydration slower because your components have to render twice. Be mindful of the user experience on slow connections. The JavaScript code may load significantly later than the initial HTML render, so rendering a different UI immediately after hydration may feel jarring to the user.
Cette approche ralentit l'hydratation parce que vos composants doivent effectuer deux rendus. Pensez à l'expérience utilisateur sur des connexions lentes. Le code JavaScript peut n'arriver que bien après le rendu HTML initial, de sorte que changer l'UI immédiatement après l'hydratation peut être déstabilisant pour l'utilisateur.

</Pitfall>