i18n(fr): add guides/route-data and reference/route-data (#2884)

Co-authored-by: Armand Philippot <[email protected]>
Co-authored-by: trueberryless <[email protected]>

docs/src/content/docs/fr/guides/route-data.mdx

@@ -0,0 +1,139 @@
+---
+title: Données de route
+description: Apprenez comment le modèle de données de page de Starlight est utilisé pour afficher vos pages et comment vous pouvez le personnaliser.
+---
+
+import { Steps } from '@astrojs/starlight/components';
+
+Lorsque Starlight affiche une page dans votre documentation, un objet de données de route est d'abord créé pour représenter ce qui se trouve sur cette page.
+Ce guide explique comment les données de route sont générées, comment les utiliser et comment vous pouvez les personnaliser pour modifier le comportement par défaut de Starlight.
+
+Consultez la [« Référence des données de route »](/fr/reference/route-data/) pour une liste complète des propriétés disponibles.
+
+## Qu'est-ce que les données de route?
+
+Les données de route de Starlight sont un objet contenant toutes les informations nécessaires pour afficher une seule page.
+Il inclut des informations pour la page courante ainsi que des données générées à partir de votre configuration de Starlight.
+
+## Utilisation des données de route
+
+Tous les composants de Starlight utilisent les données de route pour décider de ce qui doit être affiché pour chaque page.
+Par exemple, la chaîne de caractères [`siteTitle`](/fr/reference/route-data/#sitetitle) est utilisée pour afficher le titre du site et le tableau [`sidebar`](/fr/reference/route-data/#sidebar) est utilisé pour afficher la barre latérale de navigation.
+
+Vous pouvez accéder à ces données à partir de la variable globale `Astro.locals.starlightRoute` dans les composants Astro :
+
+```astro title="exemple.astro" {2}
+---
+const { siteTitle } = Astro.locals.starlightRoute;
+---
+
+<p>Le titre de ce site est « {siteTitle} »</p>
+```
+
+Cela peut être utile, par exemple, lors de la mise en place de redéfinitions de composants pour personnaliser ce que vous affichez.
+
+## Personnalisation des données de route
+
+Les données de route de Starlight sont prêtes à l'emploi et ne nécessitent aucune configuration.
+Cependant, pour des cas d'utilisation avancés, vous pourriez vouloir personnaliser les données de route pour certaines ou toutes les pages afin de modifier le rendu de votre site.
+
+Il s'agit d'un concept similaire aux [redéfinitions de composants](/fr/guides/overriding-components/), mais au lieu de modifier la façon dont Starlight affiche vos données, vous modifiez les données que Starlight affiche.
+
+### Quand personnaliser les données de route
+
+Personnaliser les données de route peut être utile lorsque vous souhaitez modifier la façon dont Starlight traite vos données d'une manière qui n'est pas possible avec les options de configuration existantes.
+
+Par exemple, vous pourriez vouloir filtrer les éléments de la barre latérale de navigation ou personnaliser les titres de certaines pages.
+Ce type de modification ne nécessite pas de modifier les composants par défaut de Starlight, seulement les données transmises à ces composants.
+
+### Comment personnaliser les données de route
+
+Vous pouvez personnaliser les données de route en utilisant une forme spéciale de « middleware ».
+C'est une fonction qui est appelée à chaque fois que Starlight affiche une page et peut modifier les valeurs contenues dans l'objet de données de route.
+
+<Steps>
+
+1. Créez un nouveau fichier exportant une fonction `onRequest` en utilisant l'utilitaire `defineRouteMiddleware()` de Starlight :
+
+   ```ts
+   // src/routeData.ts
+   import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+
+   export const onRequest = defineRouteMiddleware(() => {});
+   ```
+
+2. Indiquez à Starlight où se trouve le fichier contenant votre middleware de données de route dans `astro.config.mjs` :
+
+   ```js ins={9}
+   // astro.config.mjs
+   import { defineConfig } from 'astro/config';
+   import starlight from '@astrojs/starlight';
+
+   export default defineConfig({
+   	integrations: [
+   		starlight({
+   			title: 'Mon ravissant site de documentation',
+   			routeMiddleware: './src/routeData.ts',
+   		}),
+   	],
+   });
+   ```
+
+3. Mettez à jour votre fonction `onRequest` pour modifier les données de route.
+
+   Le premier argument que votre middleware recevra est [l'objet `context` d'Astro](https://docs.astro.build/fr/reference/api-reference/).
+   Celui-ci contient toutes les informations concernant le rendu de la page courante, y compris l'URL actuelle et les `locals`.
+
+   Dans cet exemple, nous allons rendre notre documentation plus passionnante en ajoutant un point d'exclamation à la fin du titre de chaque page.
+
+   ```ts
+   // src/routeData.ts
+   import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+
+   export const onRequest = defineRouteMiddleware((context) => {
+   	// Récupérer l'entrée de la collection de contenus pour cette page.
+   	const { entry } = context.locals.starlightRoute;
+   	// Mettre à jour le titre pour ajouter un point d'exclamation.
+   	entry.data.title = entry.data.title + ' !';
+   });
+   ```
+
+</Steps>
+
+#### Plusieurs middleware de route
+
+Starlight accepte également d'utiliser plusieurs middlewares.
+Définissez `routeMiddleware` comme un tableau de chemins pour ajouter plus d'un middleware :
+
+```js {9}
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+	integrations: [
+		starlight({
+			title: 'Mon site avec plusieurs middlewares',
+			routeMiddleware: ['./src/middleware-un.ts', './src/middleware-deux.ts'],
+		}),
+	],
+});
+```
+
+#### Attendre des middlewares de route ultérieurs
+
+Pour attendre que des middlewares ultérieurs s'exécutent avant d'exécuter votre code, vous pouvez attendre la fin de l'appel à `next()` passé en deuxième argument à votre fonction middleware.
+Cela peut être utile pour attendre que le middleware d'un module d'extension s'exécute avant de faire des modifications par exemple.
+
+```ts "next" "await next();"
+// src/routeData.ts
+import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+
+export const onRequest = defineRouteMiddleware(async (context, next) => {
+	// Attendre que des middlewares ultérieurs s'exécutent.
+	await next();
+	// Modifier les données de route.
+	const { entry } = context.locals.starlightRoute;
+	entry.data.title = entry.data.title + ' !';
+});
+```

docs/src/content/docs/fr/reference/route-data.mdx

@@ -0,0 +1,197 @@
+---
+title: Référence des données de route
+description: La documentation de référence complète pour l'objet de données de route de Starlight.
+---
+
+L'objet de données de route de Starlight contient des informations sur la page courante.
+Apprenez-en plus sur le fonctionnement du modèle de données de Starlight dans le [guide « Données de route »](/fr/guides/route-data/).
+
+Dans les composants Astro, accédez aux données de route à partir de `Astro.locals.starlightRoute` :
+
+```astro {4}
+---
+// src/components/Custom.astro
+
+const { hasSidebar } = Astro.locals.starlightRoute;
+---
+```
+
+Dans un [middleware de route](/fr/guides/route-data/#personnalisation-des-données-de-route), accédez aux données de route à partir de l'objet de contexte passé à votre fonction middleware :
+
+```ts {5}
+// src/routeData.ts
+import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+
+export const onRequest = defineRouteMiddleware((context) => {
+	const { hasSidebar } = context.locals.starlightRoute;
+});
+```
+
+## `starlightRoute`
+
+L'objet `starlightRoute` contient les propriétés suivantes :
+
+### `dir`
+
+**Type :** `'ltr' | 'rtl'`
+
+Le sens d’écriture de la page.
+
+### `lang`
+
+**Type :** `string`
+
+L'étiquette d'identification BCP-47 pour la langue de la page, par exemple `en`, `zh-CN` ou `pt-BR`.
+
+### `locale`
+
+**Type :** `string | undefined`
+
+Le chemin de base utilisé pour servir une langue. `undefined` pour les slugs de la locale racine.
+
+### `siteTitle`
+
+**Type :** `string`
+
+Le titre du site pour la langue de cette page.
+
+### `siteTitleHref`
+
+**Type :** `string`
+
+La valeur de l'attribut `href` du titre du site, renvoyant à la page d'accueil, par exemple `/`.
+Pour les sites multilingues, cette valeur inclura la locale actuelle, par exemple `/fr/` ou `/zh-cn/`.
+
+### `slug`
+
+**Type :** `string`
+
+Le slug de la page généré à partir du nom du fichier du contenu.
+
+Cette propriété est dépréciée et sera supprimée dans une version future de Starlight.
+Migrez vers la nouvelle API Content Layer en utilisant le [`docsLoader` de Starlight](/fr/manual-setup/#configurer-les-collections-de-contenu) et utilisez la propriété [`id`](#id) à la place.
+
+### `id`
+
+**Type :** `string`
+
+Le slug de cette page ou l'identifiant unique de cette page basé sur le nom du fichier du contenu si l'option [`legacy.collections`](https://docs.astro.build/fr/reference/legacy-flags/#collections) est utilisée.
+
+### `isFallback`
+
+**Type :** `true | undefined`
+
+`true` si cette page n'est pas traduite dans la langue actuelle et utilise le contenu de la langue par défaut en tant que repli.
+Utilisé uniquement dans les sites multilingues.
+
+### `entryMeta`
+
+**Type :** `{ dir: 'ltr' | 'rtl'; lang: string }`
+
+Métadonnées de la locale pour le contenu de la page. Peut être différent des valeurs de locale de premier niveau lorsque la page utilise un contenu de repli.
+
+### `entry`
+
+L'entrée de la collection de contenu Astro pour la page courante.
+Inclut les valeurs du frontmatter pour la page courante dans `entry.data`.
+
+```ts
+entry: {
+	data: {
+		title: string;
+		description: string | undefined;
+		// etc.
+	}
+}
+```
+
+Pour en savoir plus sur le format de cet objet, consultez la [référence du type d'entrée de collection](https://docs.astro.build/fr/reference/modules/astro-content/#collectionentry).
+
+### `sidebar`
+
+**Type :** `SidebarEntry[]`
+
+Les entrées de la barre latérale de navigation du site pour cette page.
+
+### `hasSidebar`
+
+**Type :** `boolean`
+
+Indique si la barre latérale est affichée sur cette page.
+
+### `pagination`
+
+**Type :** `{ prev?: Link; next?: Link }`
+
+Liens vers la page précédente et suivante dans la barre latérale si celle-ci est activée.
+
+### `toc`
+
+**Type :** `{ minHeadingLevel: number; maxHeadingLevel: number; items: TocItem[] } | undefined`
+
+Table des matières de la page courante si celle-ci est activée.
+
+### `headings`
+
+**Type :** `{ depth: number; slug: string; text: string }[]`
+
+Un tableau de toutes les en-têtes Markdown extraites de la page courante.
+Utilisez [`toc`](#toc) à la place si vous souhaitez construire un composant de table des matières qui respecte les options de configuration de Starlight.
+
+### `lastUpdated`
+
+**Type :** `Date | undefined`
+
+Un objet JavaScript de type `Date` représentant la date de dernière mise à jour de cette page si cette fonctionnalité est activée.
+
+### `editUrl`
+
+**Type :** `URL | undefined`
+
+Un objet `URL` de l'adresse où cette page peut être modifiée si cette fonctionnalité est activée.
+
+## Utilitaires
+
+### `defineRouteMiddleware()`
+
+Utilisez l'utilitaire `defineRouteMiddleware()` pour vous aider à typer votre module de middleware de route :
+
+```ts "defineRouteMiddleware"
+// src/routeData.ts
+import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+
+export const onRequest = defineRouteMiddleware((context) => {
+	// ...
+});
+```
+
+### Type `StarlightRouteData`
+
+Si vous écrivez du code qui utilise les données de route de Starlight, vous pouvez importer le type `StarlightRouteData` qui correspond au format de `Astro.locals.starlightRoute`.
+
+Dans l'exemple suivant, une fonction `usePageTitleInTOC()` met à jour les données de route pour utiliser le titre de la page courante comme libellé du premier élément de la table des matières, remplaçant le libellé par défaut « Sur cette page ».
+Le type `StarlightRouteData` vous permet de vérifier si les modifications des données de route sont valides.
+
+```ts "StarlightRouteData"
+// src/route-utils.ts
+import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+
+export function usePageTitleInTOC(starlightRoute: StarlightRouteData) {
+	const overviewLink = starlightRoute.toc?.items[0];
+	if (overviewLink) {
+		overviewLink.text = starlightRoute.entry.data.title;
+	}
+}
+```
+
+Cette fonction peut ensuite être appelée à partir d'un middleware de route :
+
+```ts {3,6}
+// src/route-middleware.ts
+import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+import { usePageTitleInTOC } from './route-utils';
+
+export const onRequest = defineRouteMiddleware((context) => {
+	usePageTitleInTOC(context.locals.starlightRoute);
+});
+```