@intlayer/docs 5.5.10 → 5.5.12

package/frequent_questions/es/static_rendering.md

@@ -0,0 +1,46 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Renderizado Estático vs Dinámico con i18n en Next.js
+description: Aprende a usar renderizado estático vs dinámico con i18n en Next.js.
+keywords:
+  - estático
+  - dinámico
+  - renderizado
+  - i18n
+  - next.js
+  - next-intl
+  - intlayer
+  - framework
+  - middleware
+  - configuración
+slugs:
+  - doc
+  - faq
+  - renderizado-estatico
+---
+
+# Renderizado Estático vs Dinámico con i18n en Next.js
+
+## El problema con **next-intl**
+
+- **¿Qué sucede?**
+  Cuando usas `useTranslations`, `getTranslations` o cualquier helper de next-intl _dentro de un Componente del Servidor_ en una aplicación con rutas i18n (`/en/…`, `/fr/…`), Next.js marca toda la ruta como **dinámica**. ([Next Intl][1])
+
+- **¿Por qué?**
+  next-intl busca la configuración regional actual desde un encabezado exclusivo de la solicitud (`x-next-intl-locale`) a través de `headers()`. Debido a que `headers()` es una **API dinámica**, cualquier componente que la utilice pierde la optimización estática. ([Next Intl][1], [Next.js][2])
+
+- **Solución oficial (boilerplate)**
+
+  1. Exporta `generateStaticParams` con cada configuración regional soportada.
+  2. Llama a `setRequestLocale(locale)` en **cada** layout/página _antes_ de llamar a `useTranslations`. ([Next Intl][1])
+     Esto elimina la dependencia del encabezado, pero ahora tienes código extra que mantener y una API inestable en producción.
+
+## Cómo **intlayer** evita el problema
+
+**Decisiones de diseño**
+
+1. **Solo parámetro de ruta** – La configuración regional proviene del segmento de URL `[locale]` que Next.js ya pasa a cada página.
+2. **Paquetes en tiempo de compilación** – Las traducciones se importan como módulos ES regulares, por lo que se optimizan mediante tree-shaking e incrustan en el momento de la compilación.
+3. **Sin APIs dinámicas** – `useT()` lee desde el contexto de React, no desde `headers()` o `cookies()`.
+4. **Sin configuración adicional** – Una vez que tus páginas están bajo `app/[locale]/`, Next.js prerenderiza automáticamente un archivo HTML por cada configuración regional.

package/frequent_questions/es/translated_path_url.md

@@ -0,0 +1,56 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: ¿Puedo traducir la ruta de la URL?
+description: Aprende cómo traducir la ruta de la URL.
+keywords:
+  - array
+  - contenido
+  - declaración
+  - intlayer
+  - middleware
+  - proxy
+  - reescribir
+  - prefijo
+  - locale
+  - url
+slugs:
+  - doc
+  - faq
+  - ruta-url-traducida
+---
+
+# ¿Es posible traducir la URL como sigue?
+
+```bash
+en -> /product (sin prefijo) o /en/product (con prefijo)
+fr -> /fr/produit
+es -> /es/producto
+```
+
+Desafortunadamente, Intlayer no permite traducir las URLs como se especifica. Para lograr esto, deberías usar tu propio middleware o proxy para reescribir las URLs.
+
+Pero puedes usar la función `getMultilingualUrl` para insertar el prefijo en la URL para un locale dado.
+
+```ts
+import { getMultilingualUrl, Locales } from "intlayer";
+
+const url = getMultilingualUrl("/product");
+
+/**
+ * en -> /product (sin prefijo) o /en/product (con prefijo)
+ * fr -> /fr/product
+ * es -> /es/product
+ */
+console.log(url);
+```
+
+O `getLocalizedUrl`
+
+```ts
+import { getLocalizedUrl, Locales } from "intlayer";
+
+const url = getLocalizedUrl("/product", Locales.FRENCH);
+
+console.log(url); // /fr/product
+```

package/frequent_questions/es/unknown_command.md

@@ -0,0 +1,98 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Comando desconocido
+description: Aprende cómo solucionar el error de comando desconocido.
+keywords:
+  - desconocido
+  - comando
+  - error
+  - intlayer
+  - fill
+  - build
+  - verbose
+  - terminal
+  - reiniciar
+  - local
+slugs:
+  - doc
+  - faq
+  - comando-desconocido
+---
+
+# error: comando desconocido fill / build / etc
+
+Si `npx intlayer fill --verbose` muestra:
+
+```
+error: unknown command 'fill'
+```
+
+pero estás seguro de que el comando `fill` _debería_ existir, aquí están los pasos para resolverlo:
+
+## 1. **Asegúrate de estar usando la última versión**
+
+Ejecuta:
+
+```bash
+npx intlayer --version                  # versión actual local de intlayer
+npx intlayer@latest --version           # versión más reciente de intlayer
+```
+
+Esto fuerza a `npx` a descargar la versión más reciente. Luego intenta de nuevo:
+
+```bash
+npx intlayer@latest build --verbose
+```
+
+## 2. **Verifica si el comando está registrado**
+
+Puedes comprobarlo con:
+
+```bash
+npx intlayer --help                     # proporciona información relacionada con los comandos
+```
+
+Revisa si el comando aparece en la lista de comandos.
+
+Ve al repositorio y confirma que tu comando está exportado y registrado en el punto de entrada de la CLI. Intlayer utiliza `commander` como framework.
+
+Código relacionado con la CLI:
+https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/cli/src/cli.ts
+
+## 4. **Reinicia tu terminal**
+
+A veces es necesario reiniciar el terminal para que reconozca nuevos comandos.
+
+## 5. **Si estás desarrollando `intlayer`, recompílalo y enlázalo**
+
+Si estás desarrollando `intlayer` localmente:
+
+```bash
+# En el directorio de intlayer
+npm install
+npm run build
+npm link
+```
+
+Luego, en otro terminal:
+
+```bash
+intlayer fill --verbose
+```
+
+Esto utiliza la versión local en la que estás trabajando.
+
+## 6. **Limpia la caché de npx (si estás atascado con una versión antigua)**
+
+```bash
+npx clear-npx-cache
+```
+
+O elimina manualmente los paquetes intlayer en caché:
+
+```bash
+rm -rf ~/.npm/_npx
+```
+
+Consulta el equivalente si usas pnpm, yarn, bun u otro gestor de paquetes

package/frequent_questions/fr/SSR_Next_no_[locale].md

@@ -0,0 +1,105 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Est-il possible d'utiliser Intlayer avec Next.js sans `[locale]` dans le chemin de la page ?
+description: Apprenez comment utiliser Intlayer avec Next.js sans `[locale]` dans le chemin de la page.
+keywords:
+  - locale
+  - chemin
+  - intlayer
+  - next.js
+  - vite
+  - framework
+  - middleware
+  - configuration
+  - prefixDefault
+  - noPrefix
+slugs:
+  - doc
+  - faq
+  - ssr-next-no-[locale]
+---
+
+# Est-il possible d'utiliser Intlayer avec Next.js sans `[locale]` dans le chemin de la page ?
+
+Oui, il est possible d'utiliser Intlayer avec Next.js sans `[locale]` dans le chemin de la page. Cependant, ce n'est pas recommandé, car diviser votre page permet de déclencher plus de mots-clés sur les moteurs de recherche. Votre SSR peut également être impacté.
+
+Si vous souhaitez le faire, suivez les mêmes étapes que celles décrites dans le guide [Intlayer avec Next.js](https://intlayer.org/doc/environment/nextjs),
+
+- pas de `src/middleware.ts`
+- pas de `generateStaticParams`
+
+```tsx fileName="src/app/layout.tsx"
+import type { FC, PropsWithChildren } from "react";
+
+const LocaleLayout: FC<PropsWithChildren> = ({ children }) => (
+  <html lang={undefined} dir={undefined}>
+    <body className={inter.className}>{children}</body>
+  </html>
+);
+
+export default LocaleLayout;
+```
+
+```tsx fileName="src/app/page.tsx"
+import type { FC } from "react";
+import { ClientComponentExample } from "@components/ClientComponentExample";
+import { ServerComponentExample } from "@components/ServerComponentExample";
+import { PageContent } from "@components/pageContent";
+import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page: FC = () => {
+  return (
+    <IntlayerServerProvider>
+      <PageContent />
+      <ServerComponentExample />
+
+      <IntlayerClientProvider>
+        <ClientComponentExample />
+      </IntlayerClientProvider>
+    </IntlayerServerProvider>
+  );
+};
+
+export default Page;
+```
+
+```tsx fileName="src/component/pageContent.ts"
+"use client";
+
+import { type FC } from "react";
+import { useIntlayer } from "next-intlayer";
+import { useHTMLLanguage } from "@hooks/htmlTextDir";
+
+const PageContent: FC = () => {
+  useHTMLLanguage();
+  const content = useIntlayer("page");
+
+  return (
+    <>
+      <p>{content.getStarted.main}</p>
+      <code>{content.getStarted.pageLink}</code>
+    </>
+  );
+};
+```
+
+```tsx fileName="src/hooks/htmlTextDir.ts"
+"use client";
+
+import { useEffect } from "react";
+import { getHTMLTextDir } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+export const useHTMLLanguage = () => {
+  const { locale } = useLocale();
+
+  useEffect(() => {
+    if (!document) return;
+
+    document.documentElement.lang = locale;
+    document.documentElement.dir = getHTMLTextDir(locale);
+  }, [locale]);
+};
+```

package/frequent_questions/fr/array_as_content_declaration.md

@@ -0,0 +1,73 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Puis-je utiliser un tableau comme déclaration de contenu ?
+description: Apprenez comment utiliser un tableau comme déclaration de contenu.
+keywords:
+  - tableau
+  - contenu
+  - déclaration
+  - intlayer
+slugs:
+  - doc
+  - faq
+  - tableau-comme-declaration-de-contenu
+---
+
+# Puis-je utiliser un tableau comme déclaration de contenu ?
+
+Oui, vous pouvez utiliser un tableau comme déclaration de contenu.
+
+```ts
+import { t, type Dictionary } from "intlayer";
+
+// Exemple de contenu utilisant un tableau pour la déclaration
+const exampleContent = {
+  key: "example",
+  content: {
+    test: t({
+      en: ["Test", "Test2", "Test3"],
+      fr: ["Test", "Test2", "Test3"],
+      es: ["Test", "Test2", "Test3"],
+    }),
+  },
+};
+
+export default exampleContent;
+```
+
+Ensuite, vous pouvez utiliser le contenu de cette manière :
+
+```tsx
+import { useIntlayer } from "react-intlayer";
+
+const Example = () => {
+  const content = useIntlayer("example");
+
+  return (
+    <div>
+      {content.test.map((item) => (
+        <div key={item.value}>{item}</div>
+      ))}
+    </div>
+  );
+};
+```
+
+```vue
+<script setup lang="ts">
+import { useIntlayer } from "vue-intlayer";
+
+const content = useIntlayer("example");
+</script>
+
+<template>
+  <div>
+    <div v-for="item in content.test" :key="item.value">
+      {{ item }}
+    </div>
+  </div>
+</template>
+```
+
+`.value` vous permet d'obtenir la valeur du contenu, non encapsulée par un `IntlayerNode`.

package/frequent_questions/fr/build_dictionaries.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Comment construire des dictionnaires ?
+description: Apprenez comment construire des dictionnaires.
+keywords:
+  - construire
+  - dictionnaires
+  - intlayer
+  - commande
+  - surveillance
+  - vscode
+  - plugin
+  - framework
+  - next.js
+  - vite
+slugs:
+  - doc
+  - faq
+  - construire-dictionnaires
+---
+
+# Construire des dictionnaires
+
+## Comment construire des dictionnaires
+
+Intlayer fournit un outil en ligne de commande pour construire des dictionnaires.
+
+```bash
+npx intlayer dictionaries build
+```
+
+Cette commande :
+
+- Analyse tous les fichiers de déclaration de contenu (`.content.{ts,tsx,js,mjs,cjs,json,...}`) dans votre projet.
+- Génère des dictionnaires et les stocke dans le dossier `.intlayer/dictionary`.
+
+### Mode Surveillance
+
+Si vous souhaitez mettre à jour automatiquement les dictionnaires lorsque des modifications sont apportées aux fichiers de déclaration de contenu, exécutez la commande suivante :
+
+```bash
+npx intlayer dictionaries build --watch
+```
+
+Dans ce mode, Intlayer analysera et construira les dictionnaires chaque fois que des modifications seront apportées aux fichiers de déclaration de contenu et mettra automatiquement à jour le dossier `.intlayer/dictionary`.
+
+### Utilisation de l'extension VSCode
+
+Vous pouvez également utiliser l’[extension Intlayer pour VSCode](https://github.com/aymericzip/intlayer/tree/main/docs/fr/vs_code_extension.md) pour améliorer votre expérience Intlayer dans VSCode.
+
+### Utilisation du plugin pour votre framework d’application préféré
+
+Si vous utilisez un framework comme Next.js (Webpack / Turbopack), Vite, ou React Native, Lynx, etc., Intlayer fournit un plugin que vous pouvez utiliser pour intégrer Intlayer dans votre application.
+
+Intlayer construira les dictionnaires avant la compilation de votre application.
+De la même manière, en mode développement, Intlayer surveillera les modifications apportées à vos fichiers de déclaration de contenu et reconstruira automatiquement les dictionnaires.
+
+Référez-vous donc à la documentation spécifique de votre framework pour apprendre comment intégrer le plugin.

package/frequent_questions/fr/build_error_CI_CD.md

@@ -0,0 +1,75 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Erreur de build en CI/CD
+description: Apprenez comment corriger les erreurs de build qui surviennent dans les environnements CI/CD.
+keywords:
+  - build
+  - erreur
+  - ci
+  - cd
+  - pipeline
+  - intlayer
+  - dictionnaires
+  - next.js
+  - prébuild
+  - automatisation
+slugs:
+  - doc
+  - faq
+  - build-error-ci-cd
+---
+
+# Erreur lors du build en CI/CD
+
+Si vous obtenez une erreur comme celle-ci sur Next.js :
+
+```text
+Error: An error occurred in the Server Components render. The specific message is omitted in production builds to avoid leaking sensitive details. A digest property is included on this error instance which may provide additional details about the nature of the error
+```
+
+Voici quelques solutions :
+
+## 1. Dictionnaires manquants
+
+Assurez-vous que les dictionnaires sont construits lors de l'étape de build.
+
+Il est fréquent que le build fonctionne localement mais pas en CI/CD. La raison est qu'en local, le répertoire `.intlayer` est présent, mais en CI/CD, il ne l'est pas car il est exclu du build.
+
+Vous pouvez corriger cela en ajoutant un script de prébuild dans le `package.json` de votre projet.
+
+```json5 fileName=package.json
+{
+  // ...
+  "scripts": {
+    "prebuild": "npx intlayer dictionaries build", // S'exécutera avant le build
+    "build": "next build",
+  },
+}
+```
+
+> Notez que si vous utilisez la fonction `withIntlayer`, ou le plugin bundler équivalent pour votre framework, le script de prébuild sera exécuté avant le build.
+
+## 2. Variables d'environnement manquantes au moment du build / de l'exécution
+
+Dans un conteneur, ou une plateforme à déploiement automatique, il est recommandé d'exclure le fichier `.env` du build.
+
+```text fileName=".gitignore or .dockerignore"
+# Variables d'environnement
+.env
+**/.env
+.env.*
+**/.env.*
+```
+
+Si vos variables d'environnement ne sont pas disponibles au moment du build, une erreur sera levée.
+
+```ts
+import { Metadata } from "next";
+
+export const generateMetadata = async ({ params }): Promise<Metadata> => ({
+  metadataBase: new URL(process.env.NEXT_PUBLIC_URL),
+});
+```
+
+Cela n'est probablement pas lié à Intlayer. Vérifiez donc vos variables d'environnement au moment du build sur votre plateforme CI/CD.

package/frequent_questions/fr/customized_locale_list.md

@@ -0,0 +1,65 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Comment personnaliser la liste des langues ?
+description: Apprenez comment personnaliser la liste des langues.
+keywords:
+  - langues
+  - liste
+  - intlayer
+  - configuration
+  - availableLocales
+  - defaultLocale
+  - useLocale
+  - hook
+  - langue
+  - liste
+slugs:
+  - doc
+  - faq
+  - liste-langues-personnalisee
+---
+
+# Est-il possible de bloquer un type de langue, comme l'anglais ? J'ajoute l'anglais dans mes dictionnaires mais je ne veux pas que l'anglais soit encore disponible sur le site web
+
+Oui, vous pouvez bloquer un type de langue, comme l'anglais, en utilisant l'option `availableLocales` dans la configuration d'Intlayer.
+
+```ts
+import { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  locales: [Locales.FRENCH, Locales.SPANISH, Locales.ENGLISH],
+  availableLocales: [Locales.FRENCH, Locales.SPANISH],
+  defaultLocale: Locales.FRENCH,
+};
+```
+
+ou
+
+```ts
+import { IntlayerConfig } from "intlayer";
+
+const locales = [Locales.FRENCH, Locales.SPANISH, Locales.ENGLISH];
+
+const config: IntlayerConfig = {
+  locales,
+  availableLocales: locales.filter((locale) => locale !== Locales.ENGLISH),
+  defaultLocale: Locales.FRENCH,
+};
+```
+
+Cette configuration modifiera les types de votre fonction `t()` pour n'inclure que les langues disponibles.
+
+L'option availableLocales est facultative, si vous ne la fournissez pas, toutes les langues seront disponibles.
+
+Faites attention, toutes les langues incluses dans l'option `availableLocales` doivent être incluses dans l'option `locales`.
+
+Notez que si vous utilisez le hook `useLocale`, l'option `availableLocales` sera utilisée pour définir l'accès à la liste des langues.
+
+```ts
+import { useLocale } from "intlayer";
+
+const { availableLocales } = useLocale();
+
+console.log(availableLocales); // [Locales.FRENCH, Locales.SPANISH]
+```

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