@intlayer/docs 9.5.4-canary.0 → 9.5.5

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)

package/docs/fr/packages/remix-intlayer/Intlayer.md

@@ -0,0 +1,77 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Documentation du contexte Intlayer | remix-intlayer
+description: Découvrez comment utiliser la clé et la propriété de contexte de requête Intlayer dans les applications Remix 3.
+keywords:
+  - Intlayer
+  - remix
+  - remix-3
+  - context
+  - RequestContext
+  - Internationalisation
+  - Documentation
+slugs:
+  - doc
+  - packages
+  - remix-intlayer
+  - Intlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Init doc"
+author: aymericzip
+---
+
+# Documentation du contexte Intlayer
+
+Dans `remix-intlayer`, `Intlayer` est la clé de `RequestContext` utilisée pour accéder à l'état d'internationalisation dans les gestionnaires de requêtes Remix 3.
+
+## Utilisation
+
+Lorsque le middleware `intlayer()` s'exécute, il stocke un objet `IntlayerState` dans le contexte de requête sous la clé `Intlayer`. Vous pouvez le récupérer dans n'importe quel gestionnaire de route :
+
+```ts fileName="src/server.ts"
+import { createRouter } from "remix/router";
+import { intlayer, Intlayer } from "remix-intlayer";
+
+const router = createRouter({
+  middleware: [intlayer()],
+});
+
+router.get("/api/profile", (context) => {
+  // Accès via context.get(Intlayer)
+  const { locale, defaultLocale, availableLocales } = context.get(Intlayer);
+
+  return Response.json({
+    locale,
+    defaultLocale,
+    availableLocales,
+  });
+});
+```
+
+Vous pouvez également y accéder à l'aide du raccourci de propriété directe `context.intlayer` :
+
+```ts
+router.get("/api/status", (context) => {
+  const currentLocale = context.intlayer.locale;
+  return Response.json({ status: "ok", locale: currentLocale });
+});
+```
+
+## Structure de `IntlayerState`
+
+L'objet `IntlayerState` contient :
+
+| Propriété          | Type                | Description                                                |
+| ------------------ | ------------------- | ---------------------------------------------------------- |
+| `locale`           | `DeclaredLocales`   | La locale résolue pour la requête en cours.                |
+| `defaultLocale`    | `DeclaredLocales`   | La locale de secours configurée dans `intlayer.config.ts`. |
+| `availableLocales` | `DeclaredLocales[]` | La liste de toutes les locales configurées dans le projet. |
+
+## Documentation associée
+
+- [Middleware `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/remix-intlayer/intlayerMiddleware.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/remix-intlayer/useLocale.md)
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/remix-intlayer/useIntlayer.md)