i18n(fr): update `reference/plugins` & `guides/i18n` (#2886)

Co-authored-by: Armand Philippot <59021693+ArmandPhilippot@users.noreply.github.com>
Co-authored-by: trueberryless <99918022+trueberryless@users.noreply.github.com>

2 files changed, 195 insertions, 53 deletions

diff --git a/docs/src/content/docs/fr/guides/i18n.mdx b/docs/src/content/docs/fr/guides/i18n.mdx
index 393f8dfb..084d0094 100644
--- a/docs/src/content/docs/fr/guides/i18n.mdx
+++ b/docs/src/content/docs/fr/guides/i18n.mdx
@@ -299,6 +299,9 @@ export const GET = (context) => {
 };
 ```
 
+Dans le contexte d'un module d'extension Starlight, vous pouvez utiliser l'utilitaire [`useTranslations()`](/fr/reference/plugins/#usetranslations) pour accéder à cette API pour une langue spécifique.
+Consultez la [référence des modules d'extension](/fr/reference/plugins/) pour plus d'informations.
+
 ### Afficher une chaîne de l'interface utilisateur
 
 Affichez une chaîne de l'interface utilisateur en utilisant la fonction `locals.t()`.
diff --git a/docs/src/content/docs/fr/reference/plugins.md b/docs/src/content/docs/fr/reference/plugins.md
index 91c136ba..dd7b77c4 100644
--- a/docs/src/content/docs/fr/reference/plugins.md
+++ b/docs/src/content/docs/fr/reference/plugins.md
@@ -15,23 +15,32 @@ Consultez la [référence de configuration](/fr/reference/configuration/#plugins
 Un module d'extension Starlight a la forme suivante.
 Voir ci-dessous pour plus de détails sur les différentes propriétés et paramètres des hooks.
 
+<!-- prettier-ignore-start -->
 ```ts
 interface StarlightPlugin {
   name: string;
   hooks: {
-    setup: (options: {
+    'i18n:setup'?: (options: {
+      injectTranslations: (
+        translations: Record<string, Record<string, string>>
+      ) => void;
+    }) => void | Promise<void>;
+    'config:setup': (options: {
       config: StarlightUserConfig;
       updateConfig: (newConfig: StarlightUserConfig) => void;
       addIntegration: (integration: AstroIntegration) => void;
+      addRouteMiddleware: (config: { entrypoint: string; order?: 'pre' | 'post' | 'default' }) => void;
       astroConfig: AstroConfig;
       command: 'dev' | 'build' | 'preview';
       isRestart: boolean;
       logger: AstroIntegrationLogger;
-      injectTranslations: (Record<string, Record<string, string>>) => void;
+      useTranslations: (lang: string) => I18nT;
+      absolutePathToLang: (path: string) => string;
     }) => void | Promise<void>;
   };
 }
 ```
+<!-- prettier-ignore-end -->
 
 ## `name`
 
@@ -41,12 +50,100 @@ Un module d'extension doit fournir un nom unique qui le décrit. Le nom est util
 
 ## `hooks`
 
-Les hooks sont des fonctions que Starlight appelle pour exécuter le code du module d'extension à des moments spécifiques. Actuellement, Starlight prend en charge un seul hook `setup`.
+Les hooks sont des fonctions que Starlight appelle pour exécuter le code du module d'extension à des moments spécifiques.
+
+Pour référencer le type des arguments d'un hook, utilisez le type utilitaire `HookParameters` et passez le nom du hook.
+Dans l'exemple suivant, le paramètre `options` est typé pour correspondre aux arguments passés au hook `config:setup` :
+
+```ts
+import type { HookParameters } from '@astrojs/starlight/types';
+
+function configSetup(options: HookParameters['config:setup']) {
+  options.useTranslations('fr');
+}
+```
+
+### `i18n:setup`
+
+Fonction de configuration de l'internationalisation du module d'extension appelée lorsque Starlight est initialisé.
+Le hook `i18n:setup` peut être utilisé pour injecter des traductions afin que le module d'extension puisse prendre en charge différentes locales.
+Ces traductions seront disponibles via [`useTranslations()`](#usetranslations) dans le hook `config:setup` et dans les composants d'interface utilisateur via [`Astro.locals.t()`](/fr/guides/i18n/#utiliser-les-traductions-de-linterface-utilisateur).
+
+Le hook `i18n:setup` est appelé avec les options suivantes :
+
+#### `injectTranslations`
+
+**Type :** `(translations: Record<string, Record<string, string>>) => void`
+
+Une fonction appelée pour ajouter ou mettre à jour des chaînes de traduction utilisées dans les [API de localisation](/fr/guides/i18n/#utiliser-les-traductions-de-linterface-utilisateur) de Starlight.
+
+Dans l'exemple suivant, un module d'extension injecte des traductions pour une chaîne d'interface utilisateur personnalisée nommée `myPlugin.doThing` pour les locales `en` et `fr` :
+
+```ts {6-13} /(injectTranslations)[^(]/
+// plugin.ts
+export default {
+  name: 'plugin-avec-traductions',
+  hooks: {
+    'i18n:setup'({ injectTranslations }) {
+      injectTranslations({
+        en: {
+          'myPlugin.doThing': 'Do the thing',
+        },
+        fr: {
+          'myPlugin.doThing': 'Faire le truc',
+        },
+      });
+    },
+  },
+};
+```
+
+Pour utiliser les traductions injectées dans l'interface utilisateur de votre module d'extension, suivez le [guide « Utiliser les traductions de l'interface utilisateur »](/fr/guides/i18n/#utiliser-les-traductions-de-linterface-utilisateur).
+Si vous avez besoin d'accéder aux traductions dans le contexte du hook [`config:setup`](#configsetup) de votre module d'extension, vous pouvez utiliser la fonction [`useTranslations()`](#usetranslations).
+
+Le typage des chaînes de traduction injectées pour un module d'extension est généré automatiquement dans le projet d'un utilisateur, mais n'est pas encore disponible lors du développement dans le code source de votre module d'extension.
+Pour typer l'objet `locals.t` dans le contexte de votre module d'extension, déclarez les espaces de noms globaux suivants dans un fichier de déclaration TypeScript :
+
+```ts
+// env.d.ts
+declare namespace App {
+  type StarlightLocals = import('@astrojs/starlight').StarlightLocals;
+  // Definit l'objet `locals.t` dans le contexte d'un module d'extension.
+  interface Locals extends StarlightLocals {}
+}
+
+declare namespace StarlightApp {
+  // Define les traductions supplémentaires du module d'extension dans l'interface `I18n`.
+  interface I18n {
+    'myPlugin.doThing': string;
+  }
+}
+```
+
+Vous pouvez également inférer le typage de l'interface `StarlightApp.I18n` à partir d'un fichier source si vous avez un objet contenant vos traductions.
+
+Par exemple, étant donné le fichier source suivant :
+
+```ts title="ui-strings.ts"
+export const UIStrings = {
+  en: { 'myPlugin.doThing': 'Do the thing' },
+  fr: { 'myPlugin.doThing': 'Faire le truc' },
+};
+```
+
+La déclaration suivante inférerait le typage à partir des clés anglaises dans le fichier source :
+
+```ts title="env.d.ts"
+declare namespace StarlightApp {
+  type UIStrings = typeof import('./ui-strings').UIStrings.en;
+  interface I18n extends UIStrings {}
+}
+```
 
-### `hooks.setup`
+### `config:setup`
 
 La fonction de configuration du module d'extension appelée lorsque Starlight est initialisé (pendant le hook [`astro:config:setup`](https://docs.astro.build/fr/reference/integrations-reference/#astroconfigsetup) de l'intégration).
-Le hook `setup` peut être utilisé pour mettre à jour la configuration de Starlight ou ajouter des intégrations Astro.
+Le hook `config:setup` peut être utilisé pour mettre à jour la configuration de Starlight ou ajouter des intégrations Astro.
 
 Ce hook est appelé avec les options suivantes :
 
@@ -73,7 +170,7 @@ Dans l'exemple suivant, un nouveau compte de média [`social`](/fr/reference/con
 export default {
   name: 'ajout-twitter-plugin',
   hooks: {
-    setup({ config, updateConfig }) {
+    'config:setup'({ config, updateConfig }) {
       updateConfig({
         social: {
           ...config.social,
@@ -100,7 +197,7 @@ import react from '@astrojs/react';
 export default {
   name: 'plugin-utilisant-react',
   hooks: {
-    setup({ addIntegration, astroConfig }) {
+    'config:setup'({ addIntegration, astroConfig }) {
       const isReactLoaded = astroConfig.integrations.find(
         ({ name }) => name === '@astrojs/react'
       );
@@ -114,6 +211,40 @@ export default {
 };
 ```
 
+#### `addRouteMiddleware`
+
+**Type :** `(config: { entrypoint: string; order?: 'pre' | 'post' | 'default' }) => void`
+
+Une fonction appelée pour ajouter un [middleware de route](/fr/guides/route-data/) pour le site.
+
+La propriété `entrypoint` doit être un spécificateur de module pour le fichier middleware de votre module d'extension qui exporte une fonction `onRequest`.
+
+Dans l'exemple suivant, un module d'extension publié sous `@exemple/starlight-module-extension` ajoute un middleware de route utilisant un spécificateur de module npm :
+
+```js {6-9}
+// module-extension.ts
+export default {
+  name: '@exemple/starlight-module-extension',
+  hooks: {
+    setup({ addRouteMiddleware }) {
+      addRouteMiddleware({
+        entrypoint: '@exemple/starlight-module-extension/route-middleware',
+      });
+    },
+  },
+};
+```
+
+##### Contrôle de l'ordre d'exécution
+
+Par défaut, le middleware du module d'extension s'exécute dans l'ordre d'ajout des modules d'extension.
+
+Utilisez la propriété `order` facultative si vous avez besoin de plus de contrôle sur le moment où votre middleware s'exécute.
+Définissez `order: "pre"` pour s'exécuter avant le middleware d'un utilisateur.
+Définissez `order: "post"` pour s'exécuter après tout autre middleware.
+
+Si deux modules d'extension ajoutent un middleware avec la même valeur `order`, le module d'extension ajouté en premier s'exécutera en premier.
+
 #### `astroConfig`
 
 **Type :** `AstroConfig`
@@ -149,7 +280,7 @@ Tous les messages seront préfixés par le nom du module d'extension.
 export default {
   name: 'plugin-long-processus',
   hooks: {
-    setup({ logger }) {
+    'config:setup'({ logger }) {
       logger.info("Démarrage d'un long processus…");
       // Un long processus…
     },
@@ -163,70 +294,78 @@ L'exemple ci-dessus affichera un message qui inclut le message d'information fou
 [plugin-long-processus] Démarrage d'un long processus…
 ```
 
-#### `injectTranslations`
+#### `useTranslations`
 
-**Type :** `(translations: Record<string, Record<string, string>>) => void`
+**Type :** `(lang: string) => I18nT`
 
-Une fonction de rappel pour ajouter ou mettre à jour des chaînes de traduction utilisées dans les [API de localisation](/fr/guides/i18n/#utiliser-les-traductions-de-linterface-utilisateur) de Starlight.
+Appelez `useTranslations()` avec une étiquette de langue BCP-47 pour générer une fonction utilitaire qui fournit l'accès aux chaînes d'interface utilisateur pour cette langue.
+`useTranslations()` retourne une fonction équivalente à l'API `Astro.locals.t()` disponible dans les composants Astro.
+Pour en savoir plus sur les APIs disponibles, consultez le [guide « Utiliser les traductions de l'interface utilisateur »](/fr/guides/i18n/#utiliser-les-traductions-de-linterface-utilisateur).
 
-Dans l'exemple suivant, un module d'extension injecte des traductions pour une chaîne d'interface utilisateur personnalisée nommée `myPlugin.doThing` pour les locales `en` et `fr` :
-
-```ts {6-13} /(injectTranslations)[^(]/
+```ts {6}
 // module-extension.ts
 export default {
-  name: 'plugin-avec-traductions',
+  name: 'plugin-utilisant-traductions',
   hooks: {
-    setup({ injectTranslations }) {
-      injectTranslations({
-        en: {
-          'myPlugin.doThing': 'Do the thing',
-        },
-        fr: {
-          'myPlugin.doThing': 'Faire le truc',
-        },
-      });
+    'config:setup'({ useTranslations, logger }) {
+      const t = useTranslations('zh-CN');
+      logger.info(t('builtWithStarlight.label'));
     },
   },
 };
 ```
 
-Pour utiliser les traductions injectées dans l'interface utilisateur de votre module d'extension, suivez le [guide « Utiliser les traductions de l'interface utilisateur »](/fr/guides/i18n/#utiliser-les-traductions-de-linterface-utilisateur).
+L'exemple ci-dessus affichera un message qui inclut une chaîne d'interface utilisateur intégrée pour la langue chinoise simplifiée :
 
-Le typage des chaînes de traduction injectées pour un module d'extension est généré automatiquement dans le projet d'un utilisateur, mais n'est pas encore disponible lors du développement dans le code source de votre module d'extension.
-Pour typer l'objet `locals.t` dans le contexte de votre module d'extension, déclarez les espaces de noms globaux suivants dans un fichier de déclaration TypeScript :
+```shell
+[plugin-utilisant-traductions] 基于 Starlight 构建
+```
 
-```ts
-// env.d.ts
-declare namespace App {
-  type StarlightLocals = import('@astrojs/starlight').StarlightLocals;
-  // Definit l'objet `locals.t` dans le contexte d'un module d'extension.
-  interface Locals extends StarlightLocals {}
-}
+#### `absolutePathToLang`
 
-declare namespace StarlightApp {
-  // Définit les traductions supplémentaires du module d'extension dans l'interface `I18n`.
-  interface I18n {
-    'myPlugin.doThing': string;
-  }
-}
-```
+**Type :** `(path: string) => string`
 
-Vous pouvez également inférer le typage de l'interface `StarlightApp.I18n` à partir d'un fichier source si vous avez un objet contenant vos traductions.
+Appelez `absolutePathToLang()` avec un chemin de fichier absolu pour obtenir la langue de ce fichier.
 
-Par exemple, étant donné le fichier source suivant :
+Cela peut être particulièrement utile lors de l'ajout de [modules d'extension remark ou rehype](https://docs.astro.build/fr/guides/markdown-content/#plugins-markdown) pour traiter les fichiers Markdown ou MDX.
+Le [format de fichier virtuel](https://github.com/vfile/vfile) utilisé par ces modules d'extension inclut le [chemin absolu](https://github.com/vfile/vfile#filepath) du fichier en cours de traitement, qui peut être utilisé avec `absolutePathToLang()` pour déterminer la langue du fichier.
+La langue retournée peut être utilisé avec l'utilitaire [`useTranslations()`](#usetranslations) pour obtenir des chaînes d'interface utilisateur pour cette langue.
 
-```ts title="traductions.ts"
-export const UIStrings = {
-  en: { 'myPlugin.doThing': 'Do the thing' },
-  fr: { 'myPlugin.doThing': 'Faire le truc' },
+Par exemple, étant donné la configuration de Starlight suivante :
+
+```js
+starlight({
+  title: 'Ma documentation',
+  defaultLocale: 'fr',
+  locales: {
+    // Documentation en anglais dans `src/content/docs/en/`
+    en: { label: 'English' },
+    // Documentation en français dans `src/content/docs/fr/`
+    fr: { label: 'Français', lang: 'fr' },
+  },
+});
+```
+
+Un module d'extension peut déterminer la langue d'un fichier en utilisant son chemin absolu :
+
+```ts {6-8} /en/
+// module-extension.ts
+export default {
+  name: 'plugin-utilisant-traductions',
+  hooks: {
+    'config:setup'({ absolutePathToLang, useTranslations, logger }) {
+      const lang = absolutePathToLang(
+        '/chemin/absolu/vers/projet/src/content/docs/en/index.mdx'
+      );
+      const t = useTranslations(lang);
+      logger.info(t('aside.tip'));
+    },
+  },
 };
 ```
 
-La déclaration suivante inférerait le typage à partir des clés anglaises dans le fichier source :
+L'exemple ci-dessus affichera un message qui inclut une chaîne d'interface utilisateur intégrée pour la langue anglaise :
 
-```ts title="env.d.ts"
-declare namespace StarlightApp {
-  type UIStrings = typeof import('./traductions').UIStrings.en;
-  interface I18n extends UIStrings {}
-}
+```shell
+[plugin-utilisant-traductions] Tip
 ```