@intlayer/docs 9.5.4 → 9.5.6

package/docs/fr/packages/astro-intlayer/exports.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2026-01-21
-updatedAt: 2026-01-21
+updatedAt: 2026-09-19
 title: Documentation du paquet astro-intlayer
-description: Intégration Astro pour Intlayer, fournissant la configuration pour le routage basé sur la locale et la gestion des dictionnaires.
+description: Intégration Astro pour Intlayer, fournissant la configuration pour le routage basé sur la locale, le middleware, les hooks, le store client et la gestion des dictionnaires.
 keywords:
   - astro-intlayer
   - astro
@@ -14,6 +14,9 @@ slugs:
   - astro-intlayer
   - exports
 history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Ajout de la documentation des hooks useIntlayer, useDictionary, useLocale, du middleware et des formateurs"
   - version: 8.0.0
     date: 2026-01-21
     changes: "Documentation unifiée pour tous les exports"
@@ -22,7 +25,7 @@ author: aymericzip
 
 # Paquet astro-intlayer
 
-Le paquet `astro-intlayer` fournit les outils nécessaires pour intégrer Intlayer dans des applications Astro. Il configure le routage par locale et la gestion des dictionnaires.
+Le paquet `astro-intlayer` fournit les outils nécessaires pour intégrer Intlayer dans des applications Astro. Il configure le routage basé sur la locale, la gestion des dictionnaires, la réécriture des pages lors du build, le middleware de requête et les hooks pour accéder au contenu multilingue à la fois dans les composants `.astro` rendus côté serveur et dans les scripts côté client.
 
 ## Installation
 
@@ -34,22 +37,171 @@ npm install astro-intlayer
 
 ### Intégration
 
-Le package `astro-intlayer` fournit une intégration Astro pour configurer Intlayer dans votre projet.
+Le paquet `astro-intlayer` fournit une intégration Astro qui configure Intlayer dans votre projet.
 
-Importer :
+Importation :
 
 ```tsx
-import "astro-intlayer";
+import { intlayer } from "astro-intlayer";
 ```
 
-ou en l'ajoutant à `astro.config.mjs` :
+ou importation par défaut dans `astro.config.mjs` :
 
 ```ts
+import { defineConfig } from "astro/config";
+import intlayer from "astro-intlayer";
+
 export default defineConfig({
   integrations: [intlayer()],
 });
 ```
 
-| Fonction   | Description                                                 |
-| ---------- | ----------------------------------------------------------- |
-| `intlayer` | Intégration Astro qui configure Intlayer dans votre projet. |
+| Fonction   | Description                                                                                                                                                                                                          | Documentation associée                                                                                        |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `intlayer` | Intégration Astro qui prépare les dictionnaires, configure les plugins Vite (alias, proxy de routage, élagage), enregistre automatiquement le middleware de requête et émet des pages pré-rendues aux URL réécrites. | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/intlayer.md) |
+
+### Hooks (Serveur et Client)
+
+Importation :
+
+```tsx
+import { useIntlayer, useDictionary, useLocale } from "astro-intlayer";
+```
+
+| Hook            | Description                                                                                                                                                                                               | Documentation associée                                                                                                  |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `useIntlayer`   | Sélectionne un dictionnaire par sa clé et retourne son contenu localisé. Dans le frontmatter `.astro`, il lit la locale de requête depuis `Astro.locals`. Dans `<script>`, il lit depuis le store client. | [useIntlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/useIntlayer.md)     |
+| `useDictionary` | Transforme un objet dictionnaire et retourne le contenu pour la locale résolue. Fonctionne dans le frontmatter et les scripts client.                                                                     | [useDictionary](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/useDictionary.md) |
+| `useLocale`     | Retourne la locale actuelle, la locale par défaut, les locales disponibles et une fonction pour mettre à jour la locale.                                                                                  | [useLocale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/useLocale.md)         |
+
+### Middleware (astro-intlayer/middleware)
+
+Importation :
+
+```tsx
+import { onRequest } from "astro-intlayer/middleware";
+```
+
+| Export      | Type                | Description                                                                                                                                                                  | Documentation associée                                                                                          |
+| ----------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `onRequest` | `MiddlewareHandler` | Middleware Astro qui détecte la locale de la requête et attache `Astro.locals.intlayer`. Enregistré automatiquement par `intlayer()`, ou importé manuellement pour composer. | [onRequest](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/onRequest.md) |
+
+### Utilitaires
+
+Importation :
+
+```tsx
+import { getIntlayerLocals } from "astro-intlayer";
+```
+
+| Fonction            | Description                                                                                                                 | Documentation associée |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| `getIntlayerLocals` | Fonction d'aide pour récupérer l'objet `IntlayerLocals` actuel depuis la portée de stockage de requête hors d'Astro.locals. | -                      |
+
+### Utilitaires Client (astro-intlayer/client)
+
+Importation :
+
+```tsx
+import {
+  useIntlayer,
+  useDictionary,
+  useDictionaryDynamic,
+  useLocale,
+  useLocaleStorage,
+  useLocaleCookie,
+  getIntlayer,
+  getDictionary,
+  installIntlayer,
+  setLocaleInStorage,
+  setLocaleCookie,
+  localeInStorage,
+  localeCookie,
+} from "astro-intlayer/client";
+```
+
+Lorsqu'il est importé dans le navigateur ou à l'intérieur de balises client `<script>`, `astro-intlayer` bascule automatiquement vers `astro-intlayer/client` (alimenté par `vanilla-intlayer`), fournissant les getters de dictionnaire côté client, les abonnements au store et les outils de persistance de locale.
+
+### Formateurs (astro-intlayer/format)
+
+Importation :
+
+```tsx
+import {
+  useIntl,
+  useDate,
+  useNumber,
+  useCurrency,
+  usePercentage,
+  useRelativeTime,
+  useList,
+  useUnit,
+  useCompact,
+} from "astro-intlayer/format";
+```
+
+| Hook              | Description                                                                                                     |
+| ----------------- | --------------------------------------------------------------------------------------------------------------- |
+| `useIntl`         | Retourne une instance Intl liée à la locale de requête ou client avec fonctionnalités de cache et d'abonnement. |
+| `useDate`         | Retourne une fonction de formatage de date pré-liée à la locale actuelle (`Intl.DateTimeFormat`).               |
+| `useNumber`       | Retourne une fonction de formatage de nombre pré-liée à la locale actuelle (`Intl.NumberFormat`).               |
+| `useCurrency`     | Retourne une fonction de formatage de devise pré-liée à la locale actuelle.                                     |
+| `usePercentage`   | Retourne une fonction de formatage de pourcentage pré-liée à la locale actuelle.                                |
+| `useRelativeTime` | Retourne une fonction de formatage de temps relatif pré-liée à la locale actuelle (`Intl.RelativeTimeFormat`).  |
+| `useList`         | Retourne une fonction de formatage de liste pré-liée à la locale actuelle (`Intl.ListFormat`).                  |
+| `useUnit`         | Retourne une fonction de formatage d'unité pré-liée à la locale actuelle.                                       |
+| `useCompact`      | Retourne une fonction de formatage de nombre compact pré-liée à la locale actuelle (ex. `1.5K`).                |
+
+### Utilitaires HTML (astro-intlayer/html)
+
+Importation :
+
+```tsx
+import { renderHTML, useHTML, useHTMLRenderer } from "astro-intlayer/html";
+```
+
+| Export            | Type       | Description                                                            |
+| ----------------- | ---------- | ---------------------------------------------------------------------- |
+| `renderHTML`      | `Function` | Fonction utilitaire autonome pour rendre les nœuds HTML.               |
+| `useHTML`         | `Hook`     | Hook pour obtenir le contexte du fournisseur HTML et sa configuration. |
+| `useHTMLRenderer` | `Hook`     | Hook pour obtenir une fonction de rendu HTML préconfigurée.            |
+
+### Utilitaires Markdown (astro-intlayer/markdown)
+
+Importation :
+
+```tsx
+import {
+  compileMarkdown,
+  renderMarkdown,
+  parseMarkdown,
+  useMarkdown,
+  useMarkdownRenderer,
+} from "astro-intlayer/markdown";
+```
+
+| Export                | Type       | Description                                                     |
+| --------------------- | ---------- | --------------------------------------------------------------- |
+| `compileMarkdown`     | `Function` | Compile des chaînes markdown en représentation structurée.      |
+| `renderMarkdown`      | `Function` | Rend le contenu markdown en nœuds de sortie.                    |
+| `parseMarkdown`       | `Function` | Analyse le contenu markdown brut en un AST.                     |
+| `useMarkdown`         | `Hook`     | Hook pour obtenir le contexte du fournisseur markdown.          |
+| `useMarkdownRenderer` | `Hook`     | Hook pour obtenir une fonction de rendu Markdown préconfigurée. |
+
+### Types
+
+Importation :
+
+```tsx
+import type {
+  IntlayerLocals,
+  UseLocaleProps,
+  UseLocaleResult,
+} from "astro-intlayer";
+```
+
+| Type              | Description                                                                                              |
+| ----------------- | -------------------------------------------------------------------------------------------------------- |
+| `IntlayerLocals`  | L'objet attaché à `Astro.locals.intlayer` contenant `locale`, `defaultLocale` et `availableLocales`.     |
+| `UseLocaleProps`  | Propriétés de configuration facultatives acceptées par `useLocale()`.                                    |
+| `UseLocaleResult` | Le type de retour de `useLocale()`, fournissant les propriétés de locale et les méthodes de mise à jour. |

package/docs/fr/packages/astro-intlayer/intlayer.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2026-01-21
+updatedAt: 2026-09-19
+title: Documentation de l'intégration intlayer | astro-intlayer
+description: Découvrez comment configurer et utiliser l'intégration Astro intlayer dans astro.config.mjs.
+keywords:
+  - intlayer
+  - astro
+  - astro-intlayer
+  - intégration
+  - i18n
+  - internationalisation
+  - documentation
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - intlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Mise à jour de la documentation de l'intégration avec détails du middleware et des hooks"
+  - version: 8.0.0
+    date: 2026-01-21
+    changes: "Doc initiale"
+author: aymericzip
+---
+
+# Documentation de l'intégration Astro intlayer
+
+L'intégration `intlayer` pour Astro configure votre projet pour l'internationalisation (i18n) multilingue. Elle prend en charge la préparation des dictionnaires au moment du build, l'injection de plugins Vite, l'enregistrement automatique du middleware de requête et l'émission des pages pré-rendues localisées.
+
+## Utilisation
+
+Ajoutez `intlayer()` dans votre `astro.config.mjs` :
+
+```ts fileName="astro.config.mjs"
+import { defineConfig } from "astro/config";
+import { intlayer } from "astro-intlayer";
+
+export default defineConfig({
+  integrations: [intlayer()],
+});
+```
+
+Le codemod de l'Astro CLI (`astro add astro-intlayer`) génère également un import par défaut qui est pris en charge :
+
+```ts
+import intlayer from "astro-intlayer";
+```
+
+## Description
+
+L'intégration s'insère dans le cycle de vie de build et d'exécution d'Astro :
+
+1. **Configuration (`astro:config:setup`)** :
+   - **Préparation des dictionnaires** : Prépare les dictionnaires Intlayer et les types générés avant l'exécution du build.
+   - **Plugins Vite** : Injecte les plugins pour les alias Vite (permettant des imports directs de dictionnaires), les proxys de routage de locale et l'élagage du build.
+   - **Enregistrement du Middleware** : Injecte automatiquement `astro-intlayer/middleware` dans la chaîne de middlewares de votre projet, remplissant `Astro.locals.intlayer` sur chaque requête entrante.
+2. **Build terminé (`astro:build:done`)** :
+   - **Réécritures de pages** : Inspecte les règles de réécriture d'URL localisées et émet les pages HTML pré-rendues à leurs chemins localisés correspondants.
+
+## Ce qui est fourni immédiatement
+
+Une fois configurée, votre application Astro peut immédiatement utiliser :
+
+- Les hooks `useIntlayer`, `useDictionary` et `useLocale` dans le frontmatter des composants `.astro`.
+- L'objet `Astro.locals.intlayer` dans les points de terminaison et pages Astro.
+- Les imports côté client dans les blocs `<script>` qui reproduisent la même API avec des mises à jour réactives.
+- Les formateurs intégrés sous `astro-intlayer/format` (`useDate`, `useNumber`, `useCurrency`, etc.).
+
+## Documentation associée
+
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/useIntlayer.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/useLocale.md)
+- [Middleware `onRequest`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/onRequest.md)

package/docs/fr/packages/astro-intlayer/onRequest.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Documentation du middleware onRequest | astro-intlayer
+description: Découvrez comment utiliser le middleware onRequest dans les applications Astro pour résoudre la locale de la requête et remplir Astro.locals.intlayer.
+keywords:
+  - onRequest
+  - middleware
+  - astro
+  - astro-intlayer
+  - Astro.locals
+  - internationalisation
+  - documentation
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - onRequest
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Doc initiale"
+author: aymericzip
+---
+
+# Documentation du middleware Astro onRequest
+
+Le middleware `onRequest` de `astro-intlayer/middleware` résout la locale de chaque requête HTTP entrante et remplit `Astro.locals.intlayer`.
+
+Lorsque vous enregistrez l'intégration `intlayer()` dans `astro.config.mjs`, ce middleware est injecté automatiquement. Vous n'avez besoin de l'importer directement que si vous composez manuellement le middleware Astro avec `sequence(...)`.
+
+## Utilisation
+
+```ts fileName="src/middleware.ts"
+import { onRequest as intlayer } from "astro-intlayer/middleware";
+import { sequence } from "astro:middleware";
+
+export const onRequest = sequence(intlayer, async (context, next) => {
+  // Accédez à la locale résolue dans votre middleware personnalisé
+  const { locale } = context.locals.intlayer;
+  console.log(`Traitement de la requête pour la locale : ${locale}`);
+
+  return next();
+});
+```
+
+## Description
+
+Le middleware effectue les actions suivantes :
+
+1. **Détection de la locale** :
+   - **URL** : Analyse le préfixe de chemin d'URL ou le paramètre de recherche `?locale=` (sauf si `routing.mode` est défini sur `no-prefix`).
+   - **Cookies / En-têtes** : Vérifie les cookies de locale persistants ou les valeurs d'en-tête personnalisées.
+   - **Accept-Language** : Utilise en dernier recours la négociation de langue préférée du navigateur.
+   - Pour les pages pré-rendues (`context.isPrerendered`), la locale est extraite strictement de l'URL afin d'éviter les avertissements de build Astro.
+2. **Remplissage du contexte** : Remplit `Astro.locals.intlayer` avec :
+   - `locale` : La locale résolue.
+   - `defaultLocale` : La locale de secours par défaut.
+   - `availableLocales` : Le tableau des locales configurées.
+3. **Portée AsyncLocalStorage** : Enveloppe le traitement de la requête en aval dans une portée `AsyncLocalStorage`, permettant à `useIntlayer()`, `useDictionary()` et `useLocale()` d'accéder à l'état de la requête sans passer d'arguments.
+
+## Type `IntlayerLocals`
+
+```ts
+export type IntlayerLocals = {
+  locale: DeclaredLocales;
+  defaultLocale: DeclaredLocales;
+  availableLocales: DeclaredLocales[];
+};
+```
+
+## Documentation associée
+
+- [Intégration `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/intlayer.md)
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/useIntlayer.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/useLocale.md)

package/docs/fr/packages/astro-intlayer/useDictionary.md

@@ -0,0 +1,94 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Documentation du hook useDictionary | astro-intlayer
+description: Découvrez comment utiliser le hook useDictionary dans les composants et scripts Astro pour résoudre des objets de dictionnaire.
+keywords:
+  - useDictionary
+  - dictionary
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - internationalisation
+  - documentation
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useDictionary
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Doc initiale"
+author: aymericzip
+---
+
+# Documentation du hook useDictionary
+
+Le hook `useDictionary` résout un objet dictionnaire importé ou inline et retourne son contenu pour la locale actuelle dans les applications Astro.
+
+Contrairement à `useIntlayer`, qui récupère les dictionnaires par clé depuis le registre global de dictionnaires, `useDictionary` fonctionne directement avec un objet dictionnaire.
+
+## Utilisation
+
+```astro fileName="src/pages/index.astro"
+---
+import { useDictionary } from "astro-intlayer";
+import homeContent from "../content/home.content";
+
+const content = useDictionary(homeContent);
+---
+
+<main>
+  <h1>{content.title}</h1>
+  <p>{content.description}</p>
+</main>
+```
+
+Vous pouvez également passer des dictionnaires inline définis avec `t()` :
+
+```astro fileName="src/components/Footer.astro"
+---
+import { useDictionary } from "astro-intlayer";
+import { t } from "intlayer";
+
+const footer = useDictionary({
+  key: "footer",
+  content: {
+    copyright: t({
+      fr: "Tous droits réservés.",
+      en: "All rights reserved.",
+      es: "Todos los derechos reservados.",
+    }),
+  },
+});
+---
+
+<footer>
+  <p>{footer.copyright}</p>
+</footer>
+```
+
+## Paramètres
+
+```ts
+useDictionary(dictionary, localeOrSelector?)
+```
+
+1. **`dictionary`** : Un objet dictionnaire ou un groupe de dictionnaires qualifié.
+2. **`localeOrSelector`** (optionnel) : Une locale spécifique ou un objet sélecteur (`{ item }`, `{ variant }`, éventuellement avec `locale`).
+
+## Description
+
+Le hook effectue les tâches suivantes :
+
+1. **Détection de la locale** : Côté serveur, il obtient la locale depuis `Astro.locals.intlayer`. Dans le navigateur, il utilise la locale du store côté client.
+2. **Traitement du contenu** : Résout les traductions (`t()`), énumérations, conditions et structures imbriquées selon la locale résolue.
+3. **Sélecteurs** : Applique les sélecteurs d'éléments ou de variantes fournis dans les arguments.
+
+## Documentation associée
+
+- [Intégration `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/intlayer.md)
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/useIntlayer.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/useLocale.md)

package/docs/fr/packages/astro-intlayer/useIntlayer.md

@@ -0,0 +1,98 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Documentation du hook useIntlayer | astro-intlayer
+description: Découvrez comment utiliser le hook useIntlayer dans les composants Astro et les scripts client pour accéder au contenu localisé.
+keywords:
+  - useIntlayer
+  - dictionary
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - internationalisation
+  - documentation
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useIntlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Doc initiale"
+author: aymericzip
+---
+
+# Documentation du hook useIntlayer
+
+Le hook `useIntlayer` vous permet de récupérer du contenu de dictionnaire localisé par clé dans les applications Astro.
+
+Il peut être appelé dans deux contextes distincts en utilisant le même chemin d'import :
+
+1. **Serveur / Frontmatter** : Dans les fichiers `.astro`, il résout automatiquement le contenu en utilisant la locale de la requête stockée dans `Astro.locals.intlayer`.
+2. **Navigateur / Balise `<script>` client** : Dans les scripts client ou les composants de framework UI, il résout vers l'implémentation du store côté client (`vanilla-intlayer`).
+
+## Utilisation
+
+### Dans le frontmatter de composant Astro
+
+```astro fileName="src/pages/index.astro"
+---
+import { useIntlayer } from "astro-intlayer";
+
+const content = useIntlayer("home");
+---
+
+<main>
+  <h1>{content.title}</h1>
+  <p>{content.description}</p>
+</main>
+```
+
+### Dans les blocs `<script>` client
+
+```astro fileName="src/components/InteractiveWidget.astro"
+---
+import { useIntlayer } from "astro-intlayer";
+
+const content = useIntlayer("home");
+---
+
+<button id="alert-btn">{content.buttonText}</button>
+
+<script>
+  import { useIntlayer } from "astro-intlayer";
+
+  const content = useIntlayer("home");
+
+  document.getElementById("alert-btn")?.addEventListener("click", () => {
+    alert(content.buttonText);
+  });
+</script>
+```
+
+## Paramètres
+
+```ts
+useIntlayer(key, localeOrSelector?)
+```
+
+1. **`key`** : La clé unique du dictionnaire (telle que définie dans vos fichiers de déclaration `.content.ts`).
+2. **`localeOrSelector`** (optionnel) : Une locale spécifique ou un objet sélecteur (`{ item }`, `{ variant }`, éventuellement avec `locale`). Lorsqu'il est fourni, il remplace la locale détectée depuis le contexte de la requête ou le store client.
+
+## Description
+
+Le hook effectue les tâches suivantes :
+
+1. **Résolution de la locale** :
+   - Côté serveur, lit la locale active depuis `Astro.locals.intlayer` via une portée `AsyncLocalStorage` initialisée par `astro-intlayer/middleware`.
+   - Dans le navigateur, lit la locale active depuis le stockage/store client.
+2. **Récupération du dictionnaire** : Injecte le contenu du dictionnaire correspondant à la clé spécifiée.
+3. **Traitement de la traduction** : Résout les traductions (`t()`), énumérations, conditions et markdown en contenu prêt à être affiché.
+
+## Documentation associée
+
+- [Intégration `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/intlayer.md)
+- [Hook `useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/useDictionary.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/useLocale.md)

package/docs/fr/packages/astro-intlayer/useLocale.md

@@ -0,0 +1,126 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Documentation du hook useLocale | astro-intlayer
+description: Découvrez comment utiliser le hook useLocale dans les applications Astro pour accéder à la locale actuelle et la gérer.
+keywords:
+  - useLocale
+  - locale
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - internationalisation
+  - documentation
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useLocale
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Doc initiale"
+author: aymericzip
+---
+
+# Documentation du hook useLocale
+
+Le hook `useLocale` de `astro-intlayer` fournit un accès à la locale de requête actuelle, à la locale par défaut configurée et à toutes les locales disponibles dans les applications Astro.
+
+Il se comporte de manière cohérente dans le frontmatter `.astro` rendu côté serveur et dans les blocs `<script>` côté client.
+
+## Utilisation
+
+### Dans le frontmatter de composant (Rendu côté serveur)
+
+```astro fileName="src/layouts/Layout.astro"
+---
+import { useLocale } from "astro-intlayer";
+import { getLocalizedUrl, getPathWithoutLocale } from "intlayer";
+
+const { locale, defaultLocale, availableLocales } = useLocale();
+const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
+---
+
+<!DOCTYPE html>
+<html lang={locale}>
+  <head>
+    <meta charset="utf-8" />
+    <title>Astro + Intlayer</title>
+  </head>
+  <body>
+    <header>
+      <span>Actuelle : {locale}</span>
+      <span>Par défaut : {defaultLocale}</span>
+      <nav>
+        <ul>
+          {availableLocales.map((localeItem) => (
+            <li key={localeItem} className="p-1">
+              <a
+                href={getLocalizedUrl(pathWithoutLocale, localeItem)}
+                aria-current={localeItem === locale ? "page" : undefined}
+              >
+                {localeItem.toUpperCase()}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </nav>
+    </header>
+    <slot />
+  </body>
+</html>
+```
+
+### Dans un `<script>` client (Interactif)
+
+```astro fileName="src/components/LocaleSwitcher.astro"
+---
+import { useLocale } from "astro-intlayer";
+
+const { locale, availableLocales } = useLocale();
+---
+
+<select id="locale-select">
+  {availableLocales.map((loc) => (
+    <option value={loc} selected={loc === locale}>
+      {loc.toUpperCase()}
+    </option>
+  ))}
+</select>
+
+<script>
+  import { useLocale, setLocaleInStorage } from "astro-intlayer";
+
+  const { setLocale } = useLocale();
+
+  document.getElementById("locale-select")?.addEventListener("change", (e) => {
+    const target = e.target as HTMLSelectElement;
+    setLocale(target.value);
+  });
+</script>
+```
+
+## Valeurs de retour
+
+Le hook retourne un objet de type `UseLocaleResult` :
+
+| Propriété          | Type                                   | Description                                                                                |
+| ------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `locale`           | `DeclaredLocales`                      | La locale active.                                                                          |
+| `defaultLocale`    | `DeclaredLocales`                      | La locale de repli par défaut configurée dans `intlayer.config.ts`.                        |
+| `availableLocales` | `DeclaredLocales[]`                    | Tableau de toutes les locales supportées configurées pour le projet.                       |
+| `setLocale`        | `(locale: LocalesValues) => void`      | Fonction pour mettre à jour la locale. (Interactive dans `<script>`, avertit lors du SSR). |
+| `subscribe`        | `(callback: () => void) => () => void` | S'abonne aux changements de locale côté client.                                            |
+
+## Comportement Serveur vs Client
+
+- **Pendant le SSR / Rendu Serveur** : Une requête est rendue une seule fois avec des paramètres fixes. Appeler `setLocale()` pendant un rendu serveur n'a aucun effet et émet un avertissement ; le changement de locale doit être effectué côté client ou en naviguant vers l'URL de la locale cible.
+- **Dans les scripts client** : `setLocale` met à jour le store client et met à jour les cookies persistants ou le stockage local selon votre configuration Intlayer.
+
+## Documentation associée
+
+- [Intégration `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/intlayer.md)
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/useIntlayer.md)
+- [Hook `useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/astro-intlayer/useDictionary.md)