@intlayer/docs 5.5.10 → 5.5.11

package/frequent_questions/fr/domain_routing.md

@@ -0,0 +1,114 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Comment configurer le routage basé sur le domaine ?
+description: Apprenez à configurer le routage basé sur le domaine.
+keywords:
+  - domaine
+  - routage
+  - intlayer
+  - configuration
+  - middleware
+  - react-router
+  - vue-router
+  - next.js
+  - vite
+  - framework
+slugs:
+  - doc
+  - faq
+  - routage-domaine
+---
+
+# Comment configurer le **routage basé sur le domaine** avec Intlayer au lieu des chemins `/[locale]/` ?
+
+## Réponse courte
+
+Le routage basé sur le domaine est plus simple que le routage basé sur le chemin (`example.com/[locale]/`) car vous pouvez éviter toute la configuration du middleware et du routage. Il suffit de déployer votre application sur chaque domaine de langue et de définir une variable d’environnement par domaine.
+
+## Étape par étape
+
+1. **Déployez une fois par domaine** (`example.com`, `exemple.fr`, `ejemplo.es`, …).
+2. Pour chaque déploiement, définissez `LOCALE` (et les variables d’environnement Intlayer habituelles) sur la locale que ce domaine doit servir.
+3. Référencez cette variable comme `defaultLocale` dans votre fichier `intlayer.config.[ts|js]`.
+
+```ts
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: process.env.LOCALE, // 👈 le domaine décide de la locale
+  },
+  // ... reste de votre configuration
+};
+
+export default config;
+```
+
+C’est tout — cela fonctionne de la même manière pour **Next.js**, **Vite + React**, **Vite + Vue**, etc.
+
+## Que faire si tous les domaines pointent vers le **même** déploiement ?
+
+Si tous les domaines pointent vers le même bundle d’application, vous devrez détecter l’hôte à l’exécution et passer la locale manuellement via le provider.
+
+### Pour Next.js
+
+```tsx
+// src/IntlayerProvider.tsx
+import {
+  IntlayerClientProvider,
+  type IntlayerClientProviderProps,
+} from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+import type { FC } from "react";
+
+export const IntlayerProvider: FC<IntlayerClientProviderProps> = ({
+  children,
+  locale,
+}) => {
+  const resolvedLocale = locale ?? getLocaleFromHostname(); // 👈 détecte la locale depuis le nom d’hôte si non fournie
+  return (
+    <IntlayerServerProvider locale={resolvedLocale}>
+      <IntlayerClientProvider locale={resolvedLocale}>
+        {children}
+      </IntlayerClientProvider>
+    </IntlayerServerProvider>
+  );
+};
+```
+
+### Pour Vue
+
+```ts
+import { createApp } from "vue";
+import { installIntlayer } from "vue-intlayer";
+import App from "./App.vue";
+import { router } from "./routes";
+
+const app = createApp(App);
+app.use(router);
+installIntlayer(app, getLocaleFromHostname());
+app.mount("#app");
+```
+
+Remplacez `getLocaleFromHostname()` par votre propre logique de recherche.
+
+## Mettez à jour votre sélecteur de langue
+
+Lors de l’utilisation du routage basé sur les domaines, changer de langue signifie naviguer vers un autre domaine :
+
+```ts
+const { locale } = useLocale();
+
+function changeLanguage(target: Locale) {
+  window.location.href = domainForLocale[target];
+}
+```
+
+## Avantages du routage basé sur les domaines
+
+1. **Configuration plus simple** : Pas besoin de configurer `intlayerMiddleware`, `generateStaticParams`, `react-router` ou `vue-router`
+2. **Meilleur SEO** : Chaque langue dispose de son propre domaine
+3. **URLs plus propres** : Pas de préfixe de langue dans le chemin
+4. **Maintenance facilitée** : Chaque déploiement de langue est indépendant

package/frequent_questions/fr/esbuild_error.md

@@ -0,0 +1,30 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Erreur ESBuild
+description: Apprenez à corriger les erreurs ESBuild.
+keywords:
+  - esbuild
+  - erreur
+  - intlayer
+  - plugin
+  - framework
+  - next.js
+  - vite
+  - react-native
+  - lynx
+slugs:
+  - doc
+  - faq
+  - erreur-esbuild
+---
+
+# Erreur ESBuild
+
+Si vous rencontrez une erreur ESBuild lors du processus de compilation, il est probable que le plugin Intlayer n'ait pas été configuré correctement.
+
+ESBuild est responsable de la lecture des fichiers de déclaration de contenu (`.content.{ts,js,mjs,cjs,json}`) et de la génération des dictionnaires correspondants dans le dossier `.intlayer/dictionary`. Il lit également le fichier de configuration (`intlayer.config.ts`).
+
+Intlayer fournit des plugins pour s'intégrer à vos bundlers. Il est conçu pour aliaser les composants destinés à s'exécuter uniquement côté serveur.
+
+Si vous utilisez un framework comme Next.js (Webpack / Turbopack), Vite, React Native, Lynx, etc., Intlayer propose un plugin que vous pouvez utiliser pour intégrer Intlayer dans votre application. Référez-vous donc à la documentation spécifique de votre framework pour apprendre comment intégrer le plugin.

package/frequent_questions/fr/get_locale_cookie.md

@@ -0,0 +1,143 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Comment récupérer la locale depuis les cookies / headers ?
+description: Apprenez comment récupérer la locale depuis les cookies / headers.
+keywords:
+  - cookie
+  - headers
+  - intlayer
+  - locale
+  - hook
+  - useLocale
+  - useLocaleCookie
+  - next.js
+  - react-intlayer
+  - vue-intlayer
+slugs:
+  - doc
+  - faq
+  - get-locale-cookie
+---
+
+# Comment récupérer la locale depuis les cookies / headers
+
+## Utilisation des Hooks (Recommandé)
+
+Pour la plupart des cas d'utilisation, il est recommandé de récupérer la locale actuelle en utilisant le hook `useLocale` car il est résolu automatiquement. Cela fonctionne de manière similaire au composable `useLocale` dans Vue.js.
+
+```ts
+import { useLocale } from "next-intlayer";
+// or import { useLocale } from "react-intlayer";
+// or import { useLocale } from "vue-intlayer";
+
+// Utilisation côté client
+const { locale } = useLocale();
+```
+
+Pour les composants serveur, vous pouvez l'importer depuis :
+
+```tsx
+import { useLocale } from "next-intlayer/server";
+
+const Test = () => {
+  const { locale } = useLocale();
+  return <>{locale}</>;
+};
+
+const Page = async ({ params }) => {
+  const { locale } = await params;
+
+  return (
+    <IntlayerServerProvider locale={locale}>
+      <Test />
+    </IntlayerServerProvider>
+  );
+};
+```
+
+Il existe également un hook `useLocaleCookie` qui ne résout que la valeur du cookie.
+
+## Configuration manuelle du cookie
+
+Vous pouvez déclarer un nom de cookie personnalisé comme suit
+
+```ts
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  middleware: {
+    cookieName: "myCustomLocaleCookie", // par défaut c'est 'intlayer-locale'
+  },
+};
+
+export default config;
+```
+
+le récupérer comme
+
+### Côté client
+
+```ts
+// Utilisation du nom de cookie par défaut
+const locale = document.cookie
+  .split("; ")
+  .find((row) => row.startsWith("intlayer-locale="))
+  ?.split("=")[1];
+
+// Utilisation d'un nom de cookie personnalisé
+const locale = document.cookie
+  .split("; ")
+  .find((row) => row.startsWith("myCustomLocaleCookie="))
+  ?.split("=")[1];
+```
+
+### Côté serveur (Next.js)
+
+```ts
+import { cookies } from "next/headers";
+
+// Utilisation du nom de cookie par défaut
+const locale = cookies().get("intlayer-locale")?.value;
+
+// Utilisation d'un nom de cookie personnalisé
+const locale = cookies().get("myCustomLocaleCookie")?.value;
+```
+
+### Si la locale n'est pas encore définie
+
+La locale est définie en tant que cookie uniquement une fois que l'utilisateur sélectionne explicitement la locale. Par défaut, pour les nouveaux visiteurs, la locale est interprétée à partir des champs d'en-tête.
+
+Vous pouvez détecter la locale préférée de l'utilisateur à partir des en-têtes de la requête. Voici un exemple de gestion :
+
+```ts
+/**
+ * Détecte la locale à partir des en-têtes de la requête
+ *
+ * L'en-tête accept-language est le plus important pour la détection de la locale.
+ * Il contient une liste de codes de langue avec des valeurs de qualité (q-values) qui indiquent
+ * les langues préférées de l'utilisateur par ordre de préférence.
+ *
+ * Exemple : "en-US,en;q=0.9,fr;q=0.8,es;q=0.7"
+ * - en-US est la langue principale (q=1.0 est implicite)
+ * - en est le deuxième choix (q=0.9)
+ * - fr est le troisième choix (q=0.8)
+ * - es est le quatrième choix (q=0.7)
+ */
+import { localeDetector } from "@intlayer/core";
+
+/**
+ * Exemple d'en-têtes de négociation que les navigateurs envoient typiquement
+ * Ces en-têtes aident à déterminer la langue préférée de l'utilisateur
+ */
+const exampleNegotiatorHeaders: Record<string, string> = {
+  "accept-language": "en-US,en;q=0.9,fr;q=0.8,es;q=0.7",
+  "accept":
+    "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
+  "user-agent":
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
+};
+
+// Exemple d'utilisation :
+const detectedLocale = localeDetector(exampleNegotiatorHeaders);
+```

package/frequent_questions/fr/intlayer_command_undefined.md

@@ -0,0 +1,157 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Commande Intlayer non définie
+description: Apprenez comment résoudre l'erreur de commande intlayer non définie.
+keywords:
+  - intlayer
+  - commande
+  - non définie
+  - erreur
+  - vscode
+  - extension
+  - plugin
+  - framework
+  - next.js
+  - vite
+slugs:
+  - doc
+  - faq
+  - commande-intlayer-non-definie
+---
+
+# Commande Intlayer non définie
+
+## Vue d'ensemble
+
+L'interface en ligne de commande (CLI) Intlayer offre un moyen pratique de gérer votre contenu intlayer, y compris la construction de dictionnaires, la poussée des traductions, et plus encore. Cependant, elle n'est pas indispensable au fonctionnement de votre projet. Si vous utilisez le plugin de bundler (comme `withIntlayer()` pour Next.js ou `intlayerPlugin()` pour Vite), Intlayer construira automatiquement les dictionnaires lors de la compilation de l'application ou au démarrage du serveur de développement. En mode développement, il surveillera également les modifications et reconstruira automatiquement les fichiers de déclaration de contenu.
+
+Vous pouvez accéder aux commandes intlayer de différentes manières :
+
+- En utilisant directement la commande CLI `intlayer`
+- En utilisant l'[extension VSCode](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/vs_code_extension.md)
+- En utilisant le SDK `@intlayer/cli`
+
+## Problème
+
+Lorsque vous essayez d'utiliser la commande `intlayer`, vous pouvez rencontrer cette erreur :
+
+```bash
+'intlayer' n'est pas reconnu en tant que commande interne ou externe,
+un programme exécutable ou un fichier de commandes.
+```
+
+## Solutions
+
+Essayez ces solutions dans l'ordre :
+
+1. **Vérifiez que la commande est installée**
+
+```bash
+npx intlayer -h
+```
+
+Sortie attendue :
+
+```bash
+Usage: intlayer [options] [command]
+
+Intlayer CLI
+
+Options:
+    -V, --version            affiche le numéro de version
+    -h, --help               affiche l'aide pour la commande
+
+Commands:
+    dictionary|dictionaries  Opérations sur les dictionnaires
+    configuration|config     Opérations de configuration
+    help [command]           affiche l'aide pour la commande
+```
+
+2. **Installez globalement le paquet intlayer-cli**
+
+```bash
+npm install intlayer-cli -g -g
+```
+
+> Il ne devrait pas être nécessaire de le faire si vous avez déjà installé le package `intlayer`
+
+3. **Installez le package globalement**
+
+```bash
+npm install intlayer -g
+```
+
+4. **Redémarrez votre terminal**
+   Parfois, un redémarrage du terminal est nécessaire pour reconnaître les nouvelles commandes.
+
+5. **Nettoyez et réinstallez**
+   Si les solutions ci-dessus ne fonctionnent pas :
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+6. **Vérifiez les fichiers d'installation**
+   Si le problème persiste, vérifiez que ces fichiers existent :
+
+   - `node_modules/intlayer/dist/cjs/cli.cjs`
+   - `node_modules/intlayer/package.json` (devrait contenir un champ `bin` pointant vers `./dist/cjs/cli.cjs`)
+
+7. **Vérifiez la variable d'environnement PATH**
+   Assurez-vous que le répertoire global des binaires npm est dans votre PATH :
+
+```bash
+# Pour les systèmes Unix (macOS/Linux)
+echo $PATH
+# Devrait inclure quelque chose comme /usr/local/bin ou ~/.npm-global/bin
+
+# Pour Windows
+echo %PATH%
+# Devrait inclure le répertoire global bin de npm
+```
+
+8. **Utilisez npx avec le chemin complet**
+   Si la commande n'est toujours pas trouvée, essayez d'utiliser npx avec le chemin complet :
+
+```bash
+npx ./node_modules/intlayer/ dictionaries build
+```
+
+9. **Vérifiez les installations conflictuelles**
+
+```bash
+# Listez tous les packages installés globalement
+npm list -g --depth=0
+
+# Supprimez toutes installations globales conflictuelles
+npm uninstall -g intlayer
+npm uninstall -g intlayer-cli
+# Puis réinstallez
+npm install -g intlayer
+```
+
+10. **Vérifiez les versions de Node.js et npm**
+    Assurez-vous d'utiliser des versions compatibles :
+
+```bash
+node --version
+npm --version
+```
+
+    Si vous utilisez une version obsolète, envisagez de mettre à jour Node.js et npm.
+
+11. **Vérifiez les problèmes de permissions**  
+    Si vous rencontrez des erreurs de permission :
+
+    ```bash
+    # Pour les systèmes basés sur Unix
+    sudo npm install -g intlayer
+
+    # Ou changez le répertoire par défaut de npm
+    mkdir ~/.npm-global
+    npm config set prefix '~/.npm-global'
+    # Ajoutez à votre ~/.profile ou ~/.bashrc :
+    export PATH=~/.npm-global/bin:$PATH
+    ```

package/frequent_questions/fr/locale_incorect_in_url.md

@@ -0,0 +1,79 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Locale incorrect récupérée depuis l'URL
+description: Apprenez comment corriger la locale incorrecte récupérée depuis l'URL.
+keywords:
+  - locale
+  - url
+  - intlayer
+  - next.js
+  - vite
+  - framework
+  - middleware
+  - configuration
+  - prefixDefault
+  - noPrefix
+slugs:
+  - doc
+  - faq
+  - locale-incorect-in-url
+---
+
+# Locale incorrect récupérée depuis l'URL
+
+## Description du problème
+
+Lorsque vous essayez d'accéder au paramètre locale depuis l'URL, vous pouvez rencontrer un problème où la valeur de la locale est incorrecte :
+
+```js
+const { locale } = await params;
+console.log(locale); // retourne "about" au lieu de la locale attendue
+```
+
+## Solution
+
+### 1. Vérifier la structure des fichiers
+
+Assurez-vous que le chemin de votre routeur d'application Next.js suit cette structure :
+
+```bash
+src/app/[locale]/about/page.tsx
+```
+
+### 2. Vérifier la configuration du middleware
+
+Le problème survient souvent lorsque le middleware est absent ou non déclenché. Le fichier middleware doit se trouver à l'emplacement suivant :
+
+```bash
+src/middleware.ts
+```
+
+Ce middleware est responsable de la réécriture des routes lorsque `prefixDefault` est défini sur `false`. Par exemple, il réécrit `/en/about` en `/about`.
+
+### 3. Modèles d'URL selon la configuration
+
+#### Configuration par défaut (`prefixDefault: false`, `noPrefix: false`)
+
+- Anglais : `/about`
+- Français : `/fr/about`
+- Espagnol : `/es/about`
+
+#### Avec `prefixDefault: true`
+
+- Anglais : `/en/about`
+- Français : `/fr/about`
+- Espagnol : `/es/about`
+
+#### Avec `noPrefix: true`
+
+- Anglais : `/about`
+- Français : `/about`
+- Espagnol : `/about`
+
+src/app/[locale]/about/page.tsx
+
+```
+
+Pour plus de détails sur ces options de configuration, consultez la [Documentation de Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/configuration.md).
+```

package/frequent_questions/fr/static_rendering.md

@@ -0,0 +1,46 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Rendu statique vs dynamique avec i18n dans Next.js
+description: Apprenez à utiliser le rendu statique vs dynamique avec i18n dans Next.js.
+keywords:
+  - statique
+  - dynamique
+  - rendu
+  - i18n
+  - next.js
+  - next-intl
+  - intlayer
+  - framework
+  - middleware
+  - configuration
+slugs:
+  - doc
+  - faq
+  - rendu-statique
+---
+
+# Rendu statique vs dynamique avec i18n dans Next.js
+
+## Le problème avec **next-intl**
+
+- **Que se passe-t-il ?**
+  Lorsque vous utilisez `useTranslations`, `getTranslations` ou tout autre helper next-intl _à l'intérieur d'un composant serveur_ dans une application routée i18n (`/en/…`, `/fr/…`), Next.js marque toute la route comme **dynamique**. ([Next Intl][1])
+
+- **Pourquoi ?**
+  next-intl recherche la locale actuelle à partir d'un en-tête disponible uniquement dans la requête (`x-next-intl-locale`) via `headers()`. Comme `headers()` est une **API dynamique**, tout composant qui l'utilise perd l'optimisation statique. ([Next Intl][1], [Next.js][2])
+
+- **Solution officielle (boilerplate)**
+
+  1. Exporter `generateStaticParams` avec toutes les locales supportées.
+  2. Appeler `setRequestLocale(locale)` dans **chaque** layout/page _avant_ d'appeler `useTranslations`. ([Next Intl][1])
+     Cela supprime la dépendance à l'en-tête, mais vous avez maintenant du code supplémentaire à maintenir et une API instable en production.
+
+## Comment **intlayer** contourne le problème
+
+**Choix de conception**
+
+1. **Paramètre de route uniquement** – La locale provient du segment d'URL `[locale]` que Next.js transmet déjà à chaque page.
+2. **Bundles à la compilation** – Les traductions sont importées comme des modules ES classiques, elles sont donc optimisées par élimination des codes morts (tree-shaken) et intégrées lors de la compilation.
+3. **Pas d’API dynamiques** – `useT()` lit depuis le contexte React, pas depuis `headers()` ou `cookies()`.
+4. **Aucune configuration supplémentaire** – Une fois que vos pages résident sous `app/[locale]/`, Next.js pré-rend automatiquement un fichier HTML par locale.

package/frequent_questions/fr/translated_path_url.md

@@ -0,0 +1,56 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Puis-je traduire le chemin de l'URL ?
+description: Apprenez comment traduire le chemin de l'URL.
+keywords:
+  - tableau
+  - contenu
+  - déclaration
+  - intlayer
+  - middleware
+  - proxy
+  - réécriture
+  - préfixe
+  - locale
+  - url
+slugs:
+  - doc
+  - faq
+  - chemin-url-traduit
+---
+
+# Est-il possible de traduire l'URL comme suit :
+
+```bash
+en -> /product (pas de préfixe) ou /en/product (avec préfixe)
+fr -> /fr/produit
+es -> /es/producto
+```
+
+Intlayer ne permet malheureusement pas de traduire les URLs comme spécifié. Pour cela, vous devez utiliser votre propre middleware ou proxy pour réécrire les URLs.
+
+Mais vous pouvez utiliser la fonction `getMultilingualUrl` pour insérer le préfixe dans l'URL pour une locale donnée.
+
+```ts
+import { getMultilingualUrl, Locales } from "intlayer";
+
+const url = getMultilingualUrl("/product");
+
+/**
+ * en -> /product (pas de préfixe) ou /en/product (avec préfixe)
+ * fr -> /fr/product
+ * es -> /es/product
+ */
+console.log(url);
+```
+
+Ou `getLocalizedUrl`
+
+```ts
+import { getLocalizedUrl, Locales } from "intlayer";
+
+const url = getLocalizedUrl("/product", Locales.FRENCH);
+
+console.log(url); // /fr/product
+```