@intlayer/docs 7.3.0-canary.0 → 7.3.1

package/docs/en/configuration.md

@@ -654,6 +654,8 @@ Intlayer supports multiple AI providers for enhanced flexibility and choice. Cur
   - _Default_: None
   - _Description_: Provides additional context about your application to the AI model, helping it generate more accurate and contextually appropriate translations. This can include information about your app's domain, target audience, tone, or specific terminology.
 
+> If you provide additional parameters, Intlayer will pass them to the AI model as context. It can be used to customize the reasoning effort, text verbosity, etc
+
 ### Build Configuration
 
 Settings that control how Intlayer optimizes and builds your application's internationalization.
@@ -668,9 +670,10 @@ Build options apply to the `@intlayer/babel` and `@intlayer/swc` plugins.
 
 - **optimize**:
   - _Type_: `boolean`
-  - _Default_: `process.env.NODE_ENV === 'production'`
+  - _Default_: `undefined`
   - _Description_: Controls whether the build should be optimized.
-  - _Example_: `true`
+  - _Example_: `process.env.NODE_ENV === 'production'`
+  - _Note_: By default, the build optimization is not fixed. If not set, Intlayer will trigger the build optimization on the build of your application (vite / nextjs / etc). Setting it to `true` will force the build optimization, including during dev mode. Setting it to `false` will disable the build optimization.
   - _Note_: When enabled, Intlayer will replace all calls of dictionaries to optimize chunking. That way the final bundle will import only the dictionaries that are used. All imports will stay as static import to avoid async processing when loading the dictionaries.
   - _Note_: Intlayer will replace all calls of `useIntlayer` with the defined mode by the `importMode` option and `getIntlayer` with `getDictionary`.
   - _Note_: This option relies on the `@intlayer/babel` and `@intlayer/swc` plugins.

package/docs/en/how_works_intlayer.md

@@ -146,7 +146,7 @@ The `vue-intlayer` package is used to interpret Intlayer dictionaries and make t
 
 The `nuxt-intlayer` package is as Nuxt module to make Intlayer dictionaries usable in Nuxt applications. It integrates essential features to make Intlayer work in a Nuxt environment, such as translation middleware, routing, or the `nuxt.config.js` file configuration.
 
-### svelte-intlayer (WIP)
+### svelte-intlayer
 
 The `svelte-intlayer` package is used to interpret Intlayer dictionaries and make them usable in Svelte applications.
 

package/docs/en/vs_code_extension.md

@@ -16,6 +16,9 @@ slugs:
   - doc
   - vs-code-extension
 history:
+  - version: 7.3.0
+    date: 2025-11-25
+    changes: Add extract content command
   - version: 6.1.5
     date: 2025-09-30
     changes: Add demo gif
@@ -42,6 +45,10 @@ Extension link: [https://marketplace.visualstudio.com/items?itemName=Intlayer.in
 
 ## Features
 
+![Extract content](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_extract_content.gif?raw=true)
+
+- **Extract Content** – Extract content from your React / Vue / Svelte components
+
 ![Fill dictionaries](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_fill_active_dictionary.gif?raw=true)
 
 - **Instant Navigation** – Quickly jump to the correct content file when clicking on a `useIntlayer` key.

package/docs/en-GB/bundle_optimization.md

@@ -0,0 +1,180 @@
+---
+createdAt: 2025-11-25
+updatedAt: 2025-11-25
+title: Optimising i18n Bundle Size & Performance
+description: Reduce application bundle size by optimising internationalisation (i18n) content. Learn how to leverage tree shaking and lazy loading for dictionaries with Intlayer.
+keywords:
+  - Bundle Optimisation
+  - Content Automation
+  - Dynamic Content
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - bundle-optimization
+history:
+  - version: 6.0.0
+    date: 2025-11-25
+    changes: Init history
+---
+
+# Optimising i18n Bundle Size & Performance
+
+One of the most common challenges with traditional i18n solutions relying on JSON files is managing content size. If developers do not manually separate content into namespaces, users often end up downloading translations for every page and potentially every language just to view a single page.
+
+For example, an application with 10 pages translated into 10 languages might result in a user downloading the content of 100 pages, even though they only need **one** (the current page in the current language). This leads to wasted bandwidth and slower load times.
+
+> To detect this, you can use bundle analysers such as `rollup-plugin-visualizer` (vite), `@next/bundle-analyser` (next.js), or `webpack-bundle-analyser` (React CRA / Angular / etc).
+
+**Intlayer solves this problem through build-time optimisation.** It analyses your code to detect which dictionaries are actually used per component and reinjects only the necessary content into your bundle.
+
+## Table of Contents
+
+<TOC />
+
+## How It Works
+
+Intlayer uses a **per-component approach**. Unlike global JSON files, your content is defined alongside or within your components. During the build process, Intlayer:
+
+1.  **Analyses** your code to find `useIntlayer` calls.
+2.  **Builds** the corresponding dictionary content.
+3.  **Replaces** the `useIntlayer` call with optimised code based on your configuration.
+
+This ensures that:
+
+- If a component is not imported, its content is not included in the bundle (Dead Code Elimination).
+- If a component is lazy-loaded, its content is also lazy-loaded.
+
+## Setup by Platform
+
+### Next.js
+
+Next.js requires the `@intlayer/swc` plugin to handle the transformation, as Next.js uses SWC for builds.
+
+> This plugin is installed by default because SWC plugins are still experimental for Next.js. It may change in the future.
+
+### Vite
+
+Vite uses the `@intlayer/babel` plugin which is included as a dependency of `vite-intlayer`. The optimisation is enabled by default.
+
+### Webpack
+
+To enable bundle optimisation with Intlayer on Webpack, you need to install and configure the appropriate Babel (`@intlayer/babel`) or SWC (`@intlayer/swc`) plugin.
+
+### Expo / Lynx
+
+Bundle optimisation is **not available yet** for this platform. Support will be added in a future release.
+
+## Configuration
+
+You can control how Intlayer optimises your bundle via the `build` property in your `intlayer.config.ts`.
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  build: {
+    optimize: true,
+    importMode: "static", // or 'dynamic'
+    traversePattern: ["**/*.{js,ts,mjs,cjs,jsx,tsx}", "!**/node_modules/**"],
+  },
+};
+
+export default config;
+```
+
+> Keeping the default option for `optimize` is recommended in the vast majority of cases.
+
+> See doc configuration for more details: [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md)
+
+### Build Options
+
+The following options are available under the `build` configuration object:
+
+| Property              | Type                            | Default                         | Description                                                                                                                                                                                      |
+| :-------------------- | :------------------------------ | :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`optimize`**        | `boolean`                       | `undefined`                     | Controls whether build optimisation is enabled. If `true`, Intlayer replaces dictionary calls with optimised injects. If `false`, optimisation is disabled. Ideally set to `true` in production. |
+| **`importMode`**      | `'static' , 'dynamic' , 'live'` | `'static'`                      | Determines how dictionaries are loaded (see details below).                                                                                                                                      |
+| **`traversePattern`** | `string[]`                      | `['**/*.{js,ts,jsx,tsx}', ...]` | Glob patterns defining which files Intlayer should scan for optimisation. Use this to exclude unrelated files and speed up builds.                                                               |
+| **`outputFormat`**    | `'esm', 'cjs'`                  | `'esm', 'cjs'`                  | Controls the output format of the built dictionaries.                                                                                                                                            |
+
+## Import Modes
+
+The `importMode` setting dictates how the dictionary content is injected into your component.
+
+### 1. Static Mode (`default`)
+
+In static mode, Intlayer replaces `useIntlayer` with `useDictionary` and injects the dictionary directly into the JavaScript bundle.
+
+- **Pros:** Instant rendering (synchronous), zero extra network requests during hydration.
+- **Cons:** The bundle includes translations for **all** available languages for that specific component.
+- **Best for:** Single Page Applications (SPA).
+
+**Transformed Code Example:**
+
+```tsx
+// Your code
+const content = useIntlayer("my-key");
+
+// Optimised code (Static)
+const content = useDictionary({
+  key: "my-key",
+  content: {
+    nodeType: "translation",
+    translation: {
+      en: "My title",
+      fr: "Mon titre",
+    },
+  },
+});
+```
+
+### 2. Dynamic Mode
+
+In dynamic mode, Intlayer replaces `useIntlayer` with `useDictionaryAsync`. This uses `import()` (Suspense-like mechanism) to lazy-load specifically the JSON for the current locale.
+
+- **Pros:** **Locale-level tree shaking.** A user viewing the English version will _only_ download the English dictionary. The French dictionary is never loaded.
+- **Cons:** Triggers a network request (asset fetch) per component during hydration.
+- **Best for:** Large text blocks, articles, or applications supporting many languages where bundle size is critical.
+
+**Transformed Code Example:**
+
+```tsx
+// Your code
+const content = useIntlayer("my-key");
+
+// Optimised code (Dynamic)
+const content = useDictionaryAsync({
+  en: () =>
+    import(".intlayer/dynamic_dictionary/en.json").then((mod) => mod.default),
+  fr: () =>
+    import(".intlayer/dynamic_dictionary/fr.json").then((mod) => mod.default),
+});
+```
+
+> When using `importMode: 'dynamic'`, if you have 100 components using `useIntlayer` on a single page, the browser will attempt 100 separate fetches. To avoid this "waterfall" of requests, group content into fewer `.content` files (e.g., one dictionary per page section) rather than one per atom component.
+
+> Currently, `importMode: 'dynamic'` is not fully supported for Vue and Svelte. It is recommended to use `importMode: 'static'` for these frameworks until further updates.
+
+### 3. Live Mode
+
+Behaves similarly to Dynamic mode but attempts to fetch dictionaries from the Intlayer Live Sync API first. If the API call fails or the content is not marked for live updates, it falls back to the dynamic import.
+
+> See CMS documentation for more details: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md)
+
+## Summary: Static vs Dynamic
+
+| Feature              | Static Mode                                   | Dynamic Mode                         |
+| :------------------- | :-------------------------------------------- | :----------------------------------- |
+| **JS Bundle Size**   | Larger (includes all langs for the component) | Smallest (only code, no content)     |
+| **Initial Load**     | Instant (Content is in bundle)                | Slight delay (Fetches JSON)          |
+| **Network Requests** | 0 extra requests                              | 1 request per dictionary             |
+| **Tree Shaking**     | Component-level                               | Component-level + Locale-level       |
+| **Best Use Case**    | UI Components, Small Apps                     | Pages with much text, Many Languages |

package/docs/en-GB/how_works_intlayer.md

@@ -139,7 +139,7 @@ The `vue-intlayer` package is used to interpret Intlayer dictionaries and make t
 
 The `nuxt-intlayer` package is a Nuxt module to make Intlayer dictionaries usable in Nuxt applications. It integrates essential features to make Intlayer work in a Nuxt environment, such as translation middleware, routing, or the `nuxt.config.js` file configuration.
 
-### svelte-intlayer (WIP)
+### svelte-intlayer
 
 The `svelte-intlayer` package is used to interpret Intlayer dictionaries and make them usable in Svelte applications.
 

package/docs/en-GB/vs_code_extension.md

@@ -42,6 +42,10 @@ Extension link: [https://marketplace.visualstudio.com/items?itemName=Intlayer.in
 
 ## Features
 
+![Extract content](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_extract_content.gif?raw=true)
+
+- **Extract Content** – Extract content from your React / Vue / Svelte components
+
 ![Fill dictionaries](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_fill_active_dictionary.gif?raw=true)
 
 - **Instant Navigation** – Quickly jump to the correct content file when clicking on a `useIntlayer` key.

package/docs/es/bundle_optimization.md

@@ -0,0 +1,190 @@
+---
+createdAt: 2025-11-25
+updatedAt: 2025-11-25
+title: Optimización del Tamaño y Rendimiento del Bundle i18n
+description: Reduce el tamaño del bundle de la aplicación optimizando el contenido de internacionalización (i18n). Aprende a aprovechar tree shaking y lazy loading para diccionarios con Intlayer.
+keywords:
+  - Optimización de Bundle
+  - Automatización de Contenido
+  - Contenido Dinámico
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - bundle-optimization
+history:
+  - version: 6.0.0
+    date: 2025-11-25
+    changes: Historial inicial
+---
+
+# Optimización del Tamaño y Rendimiento del Bundle i18n
+
+Uno de los desafíos más comunes con las soluciones tradicionales de i18n que dependen de archivos JSON es gestionar el tamaño del contenido. Si los desarrolladores no separan manualmente el contenido en namespaces, los usuarios a menudo terminan descargando las traducciones de todas las páginas y potencialmente de todos los idiomas solo para ver una sola página.
+
+Por ejemplo, una aplicación con 10 páginas traducidas a 10 idiomas podría hacer que un usuario descargue el contenido de 100 páginas, aunque solo necesite **una** (la página actual en el idioma actual). Esto conduce a un desperdicio de ancho de banda y tiempos de carga más lentos.
+
+> Para detectarlo, puedes usar analizadores de bundle como `rollup-plugin-visualizer` (vite), `@next/bundle-analyzer` (next.js) o `webpack-bundle-analyzer` (React CRA / Angular / etc).
+
+**Intlayer resuelve este problema mediante la optimización en tiempo de compilación.** Analiza tu código para detectar qué diccionarios se usan realmente por componente y reinserta solo el contenido necesario en tu bundle.
+
+## Tabla de Contenidos
+
+<TOC />
+
+## Cómo Funciona
+
+Intlayer utiliza un **enfoque por componente**. A diferencia de los archivos JSON globales, tu contenido se define junto a tus componentes o dentro de ellos. Durante el proceso de compilación, Intlayer:
+
+1.  **Analiza** tu código para encontrar llamadas a `useIntlayer`.
+2.  **Construye** el contenido del diccionario correspondiente.
+3.  **Reemplaza** la llamada a `useIntlayer` con código optimizado basado en tu configuración.
+
+Esto garantiza que:
+
+- Si un componente no se importa, su contenido no se incluye en el bundle (Eliminación de Código Muerto).
+- Si un componente se carga de forma lazy, su contenido también se carga de forma lazy.
+
+## Configuración por Plataforma
+
+### Next.js
+
+Next.js requiere el plugin `@intlayer/swc` para manejar la transformación, ya que Next.js utiliza SWC para las compilaciones.
+
+> Este plugin está instalado por defecto porque los plugins SWC aún son experimentales para Next.js. Esto podría cambiar en el futuro.
+
+### Vite
+
+Vite utiliza el plugin `@intlayer/babel` que está incluido como dependencia de `vite-intlayer`. La optimización está habilitada por defecto.
+
+### Webpack
+
+Para habilitar la optimización del bundle con Intlayer en Webpack, necesitas instalar y configurar el plugin adecuado de Babel (`@intlayer/babel`) o SWC (`@intlayer/swc`).
+
+### Expo / Lynx
+
+La optimización del bundle **no está disponible aún** para esta plataforma. El soporte será añadido en una versión futura.
+
+## Configuración
+
+Puedes controlar cómo Intlayer optimiza tu bundle a través de la propiedad `build` en tu archivo `intlayer.config.ts`.
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  build: {
+    optimize: true,
+    importMode: "static", // o 'dynamic'
+    traversePattern: ["**/*.{js,ts,mjs,cjs,jsx,tsx}", "!**/node_modules/**"],
+  },
+};
+
+export default config;
+```
+
+> Se recomienda mantener la opción por defecto para `optimize` en la mayoría de los casos.
+
+> Consulta la documentación de configuración para más detalles: [Configuración](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md)
+
+### Opciones de Build
+
+Las siguientes opciones están disponibles bajo el objeto de configuración `build`:
+
+| Propiedad             | Tipo                            | Valor por defecto               | Descripción                                                                                                                                                                                                                                                  |
+| :-------------------- | :------------------------------ | :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`optimize`**        | `boolean`                       | `undefined`                     | Controla si la optimización de la build está habilitada. Si es `true`, Intlayer reemplaza las llamadas al diccionario con inyecciones optimizadas. Si es `false`, la optimización está deshabilitada. Idealmente se debe establecer en `true` en producción. |
+| **`importMode`**      | `'static' , 'dynamic' , 'live'` | `'static'`                      | Determina cómo se cargan los diccionarios (ver detalles a continuación).                                                                                                                                                                                     |
+| **`traversePattern`** | `string[]`                      | `['**/*.{js,ts,jsx,tsx}', ...]` | Patrones glob que definen qué archivos Intlayer debe escanear para la optimización. Úsalo para excluir archivos no relacionados y acelerar las builds.                                                                                                       |
+| **`outputFormat`**    | `'esm', 'cjs'`                  | `'esm', 'cjs'`                  | Controla el formato de salida de los diccionarios construidos.                                                                                                                                                                                               |
+
+## Modos de Importación
+
+La configuración `importMode` dicta cómo se inyecta el contenido del diccionario en tu componente.
+
+### 1. Modo Estático (`default`)
+
+En modo estático, Intlayer reemplaza `useIntlayer` por `useDictionary` e inyecta el diccionario directamente en el bundle de JavaScript.
+
+- **Ventajas:** Renderizado instantáneo (síncrono), sin solicitudes de red adicionales durante la hidratación.
+- **Desventajas:** El bundle incluye traducciones para **todos** los idiomas disponibles para ese componente específico.
+- **Ideal para:** Aplicaciones de una sola página (SPA).
+
+**Ejemplo de código transformado:**
+
+```tsx
+// Tu código
+const content = useIntlayer("my-key");
+
+// Código optimizado (Estático)
+const content = useDictionary({
+  key: "my-key",
+  content: {
+    nodeType: "translation",
+    translation: {
+      en: "My title",
+      fr: "Mon titre",
+    },
+  },
+});
+```
+
+### 2. Modo Dinámico
+
+En modo dinámico, Intlayer reemplaza `useIntlayer` por `useDictionaryAsync`. Esto utiliza `import()` (mecanismo similar a Suspense) para cargar perezosamente específicamente el JSON para la localidad actual.
+
+- **Ventajas:** **Eliminación de código a nivel de localidad.** Un usuario que vea la versión en inglés solo descargará el diccionario en inglés. El diccionario en francés nunca se carga.
+- **Desventajas:** Genera una solicitud de red (descarga de recurso) por componente durante la hidratación.
+- **Ideal para:** Bloques grandes de texto, artículos o aplicaciones que soportan muchos idiomas donde el tamaño del bundle es crítico.
+
+**Ejemplo de código transformado:**
+
+```tsx
+// Tu código
+const content = useIntlayer("my-key");
+
+// Código optimizado (Dinámico)
+const content = useDictionaryAsync({
+  en: () =>
+    import(".intlayer/dynamic_dictionary/en.json").then((mod) => mod.default),
+  fr: () =>
+    import(".intlayer/dynamic_dictionary/fr.json").then((mod) => mod.default),
+});
+```
+
+> Al usar `importMode: 'dynamic'`, si tienes 100 componentes usando `useIntlayer` en una sola página, el navegador intentará realizar 100 solicitudes separadas. Para evitar esta "cascada" de peticiones, agrupa el contenido en menos archivos `.content` (por ejemplo, un diccionario por sección de página) en lugar de uno por componente átomo.
+
+> Actualmente, `importMode: 'dynamic'` no está completamente soportado para Vue y Svelte. Se recomienda usar `importMode: 'static'` para estos frameworks hasta futuras actualizaciones.
+
+### 3. Modo Live
+
+Se comporta de manera similar al modo Dinámico, pero intenta obtener primero los diccionarios desde la API de Intlayer Live Sync. Si la llamada a la API falla o el contenido no está marcado para actualizaciones en vivo, vuelve a la importación dinámica.
+
+> Consulta la documentación del CMS para más detalles: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md)
+
+## Resumen: Estático vs Dinámico
+
+| Característica           | Modo Estático                                             | Modo Dinámico                            |
+| :----------------------- | :-------------------------------------------------------- | :--------------------------------------- |
+| **Tamaño del Bundle JS** | Más grande (incluye todos los idiomas para el componente) | Más pequeño (solo código, sin contenido) |
+
+Se comporta de manera similar al modo Dinámico pero intenta obtener los diccionarios primero desde la API de Intlayer Live Sync. Si la llamada a la API falla o el contenido no está marcado para actualizaciones en vivo, vuelve a la importación dinámica.
+
+> Consulte la documentación del CMS para más detalles: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md)
+
+## Resumen: Estático vs Dinámico
+
+| Característica           | Modo Estático                                             | Modo Dinámico                             |
+| :----------------------- | :-------------------------------------------------------- | :---------------------------------------- |
+| **Tamaño del Bundle JS** | Más grande (incluye todos los idiomas para el componente) | Más pequeño (solo código, sin contenido)  |
+| **Carga Inicial**        | Instantánea (El contenido está en el bundle)              | Ligera demora (Obtiene JSON)              |
+| **Solicitudes de Red**   | 0 solicitudes adicionales                                 | 1 solicitud por diccionario               |
+| **Tree Shaking**         | A nivel de componente                                     | A nivel de componente + a nivel de idioma |
+| **Mejor Caso de Uso**    | Componentes UI, Aplicaciones pequeñas                     | Páginas con mucho texto, Muchos idiomas   |

package/docs/es/how_works_intlayer.md

@@ -142,7 +142,7 @@ El paquete `vue-intlayer` se utiliza para interpretar los diccionarios de Intlay
 
 El paquete `nuxt-intlayer` es un módulo de Nuxt para hacer que los diccionarios de Intlayer sean utilizables en aplicaciones Nuxt. Integra características esenciales para que Intlayer funcione en un entorno Nuxt, como middleware de traducción, enrutamiento o la configuración del archivo `nuxt.config.js`.
 
-### svelte-intlayer (WIP)
+### svelte-intlayer
 
 El paquete `svelte-intlayer` se utiliza para interpretar los diccionarios de Intlayer y hacerlos utilizables en aplicaciones Svelte.
 

package/docs/es/vs_code_extension.md

@@ -42,6 +42,10 @@ Enlace de la extensión: [https://marketplace.visualstudio.com/items?itemName=In
 
 ## Funcionalidades
 
+![Extraer contenido](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_extract_content.gif?raw=true)
+
+- **Extraer Contenido** – Extrae contenido de tus componentes React / Vue / Svelte
+
 ![Rellenar diccionarios](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_fill_active_dictionary.gif?raw=true)
 
 - **Navegación Instantánea** – Salta rápidamente al archivo de contenido correcto al hacer clic en una clave `useIntlayer`.

package/docs/fr/bundle_optimization.md

@@ -0,0 +1,180 @@
+---
+createdAt: 2025-11-25
+updatedAt: 2025-11-25
+title: Optimisation de la taille et des performances du bundle i18n
+description: Réduisez la taille du bundle de votre application en optimisant le contenu d'internationalisation (i18n). Apprenez à exploiter le tree shaking et le lazy loading pour les dictionnaires avec Intlayer.
+keywords:
+  - Optimisation du bundle
+  - Automatisation du contenu
+  - Contenu dynamique
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - bundle-optimization
+history:
+  - version: 6.0.0
+    date: 2025-11-25
+    changes: Historique initial
+---
+
+# Optimisation de la taille et des performances du bundle i18n
+
+L'un des défis les plus courants avec les solutions i18n traditionnelles basées sur des fichiers JSON est la gestion de la taille du contenu. Si les développeurs ne séparent pas manuellement le contenu en namespaces, les utilisateurs finissent souvent par télécharger les traductions de chaque page et potentiellement de chaque langue simplement pour afficher une seule page.
+
+Par exemple, une application avec 10 pages traduites en 10 langues peut entraîner le téléchargement par un utilisateur du contenu de 100 pages, alors qu'il n'a besoin que d'**une seule** (la page actuelle dans la langue actuelle). Cela conduit à un gaspillage de bande passante et à des temps de chargement plus lents.
+
+> Pour le détecter, vous pouvez utiliser un analyseur de bundle comme `rollup-plugin-visualizer` (vite), `@next/bundle-analyzer` (next.js), ou `webpack-bundle-analyzer` (React CRA / Angular / etc).
+
+**Intlayer résout ce problème grâce à une optimisation au moment de la compilation.** Il analyse votre code pour détecter quels dictionnaires sont réellement utilisés par composant et réinjecte uniquement le contenu nécessaire dans votre bundle.
+
+## Table des matières
+
+<TOC />
+
+## Comment ça fonctionne
+
+Intlayer utilise une **approche par composant**. Contrairement aux fichiers JSON globaux, votre contenu est défini à côté ou à l'intérieur de vos composants. Lors du processus de build, Intlayer :
+
+1.  **Analyse** votre code pour trouver les appels à `useIntlayer`.
+2.  **Construit** le contenu du dictionnaire correspondant.
+3.  **Remplace** l'appel à `useIntlayer` par un code optimisé basé sur votre configuration.
+
+Cela garantit que :
+
+- Si un composant n'est pas importé, son contenu n'est pas inclus dans le bundle (élimination de code mort).
+- Si un composant est chargé de manière lazy, son contenu est également chargé de manière lazy.
+
+## Configuration par plateforme
+
+### Next.js
+
+Next.js nécessite le plugin `@intlayer/swc` pour gérer la transformation, car Next.js utilise SWC pour les builds.
+
+> Ce plugin est installé par défaut car les plugins SWC sont encore expérimentaux pour Next.js. Cela pourrait changer à l'avenir.
+
+### Vite
+
+Vite utilise le plugin `@intlayer/babel` qui est inclus en tant que dépendance de `vite-intlayer`. L'optimisation est activée par défaut.
+
+### Webpack
+
+Pour activer l'optimisation du bundle avec Intlayer sur Webpack, vous devez installer et configurer le plugin Babel (`@intlayer/babel`) ou SWC (`@intlayer/swc`) approprié.
+
+### Expo / Lynx
+
+L'optimisation du bundle n'est **pas encore disponible** pour cette plateforme. Le support sera ajouté dans une future version.
+
+## Configuration
+
+Vous pouvez contrôler la manière dont Intlayer optimise votre bundle via la propriété `build` dans votre fichier `intlayer.config.ts`.
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  build: {
+    optimize: true,
+    importMode: "static", // ou 'dynamic'
+    traversePattern: ["**/*.{js,ts,mjs,cjs,jsx,tsx}", "!**/node_modules/**"],
+  },
+};
+
+export default config;
+```
+
+> Il est recommandé de conserver l'option par défaut pour `optimize` dans la grande majorité des cas.
+
+> Voir la documentation de configuration pour plus de détails : [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/configuration.md)
+
+### Options de build
+
+Les options suivantes sont disponibles sous l'objet de configuration `build` :
+
+| Propriété             | Type                            | Par défaut                      | Description                                                                                                                                                                                                                        |
+| :-------------------- | :------------------------------ | :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`optimize`**        | `boolean`                       | `undefined`                     | Contrôle si l'optimisation de la build est activée. Si `true`, Intlayer remplace les appels au dictionnaire par des injections optimisées. Si `false`, l'optimisation est désactivée. Idéalement configuré à `true` en production. |
+| **`importMode`**      | `'static' , 'dynamic' , 'live'` | `'static'`                      | Détermine comment les dictionnaires sont chargés (voir détails ci-dessous).                                                                                                                                                        |
+| **`traversePattern`** | `string[]`                      | `['**/*.{js,ts,jsx,tsx}', ...]` | Modèles globaux définissant les fichiers que Intlayer doit analyser pour l'optimisation. Utilisez ceci pour exclure les fichiers non pertinents et accélérer les builds.                                                           |
+| **`outputFormat`**    | `'esm', 'cjs'`                  | `'esm', 'cjs'`                  | Contrôle le format de sortie des dictionnaires construits.                                                                                                                                                                         |
+
+## Modes d'importation
+
+Le paramètre `importMode` détermine comment le contenu du dictionnaire est injecté dans votre composant.
+
+### 1. Mode statique (`default`)
+
+En mode statique, Intlayer remplace `useIntlayer` par `useDictionary` et injecte le dictionnaire directement dans le bundle JavaScript.
+
+- **Avantages :** Rendu instantané (synchrone), aucune requête réseau supplémentaire lors de l'hydratation.
+- **Inconvénients :** Le bundle inclut les traductions pour **toutes** les langues disponibles pour ce composant spécifique.
+- **Idéal pour :** Applications monopage (SPA).
+
+**Exemple de code transformé :**
+
+```tsx
+// Votre code
+const content = useIntlayer("my-key");
+
+// Code optimisé (Statique)
+const content = useDictionary({
+  key: "my-key",
+  content: {
+    nodeType: "translation",
+    translation: {
+      en: "My title",
+      fr: "Mon titre",
+    },
+  },
+});
+```
+
+### 2. Mode Dynamique
+
+En mode dynamique, Intlayer remplace `useIntlayer` par `useDictionaryAsync`. Cela utilise `import()` (mécanisme similaire à Suspense) pour charger paresseusement le JSON spécifique à la locale courante.
+
+- **Avantages :** **Élimination des modules inutilisés au niveau de la locale.** Un utilisateur visualisant la version anglaise téléchargera _uniquement_ le dictionnaire anglais. Le dictionnaire français n'est jamais chargé.
+- **Inconvénients :** Déclenche une requête réseau (récupération d'asset) par composant lors de l'hydratation.
+- **Idéal pour :** Blocs de texte volumineux, articles, ou applications supportant de nombreuses langues où la taille du bundle est critique.
+
+**Exemple de code transformé :**
+
+```tsx
+// Votre code
+const content = useIntlayer("my-key");
+
+// Code optimisé (Dynamique)
+const content = useDictionaryAsync({
+  en: () =>
+    import(".intlayer/dynamic_dictionary/en.json").then((mod) => mod.default),
+  fr: () =>
+    import(".intlayer/dynamic_dictionary/fr.json").then((mod) => mod.default),
+});
+```
+
+> Lors de l'utilisation de `importMode: 'dynamic'`, si vous avez 100 composants utilisant `useIntlayer` sur une seule page, le navigateur tentera 100 requêtes distinctes. Pour éviter cette "cascade" de requêtes, regroupez le contenu dans moins de fichiers `.content` (par exemple, un dictionnaire par section de page) plutôt qu'un par composant atomique.
+
+> Actuellement, `importMode: 'dynamic'` n'est pas entièrement pris en charge pour Vue et Svelte. Il est recommandé d'utiliser `importMode: 'static'` pour ces frameworks en attendant des mises à jour ultérieures.
+
+### 3. Mode Live
+
+Se comporte de manière similaire au mode Dynamique mais tente d'abord de récupérer les dictionnaires via l'API Intlayer Live Sync. Si l'appel API échoue ou si le contenu n'est pas marqué pour des mises à jour en direct, il revient à l'import dynamique.
+
+> Voir la documentation CMS pour plus de détails : [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/intlayer_CMS.md)
+
+## Résumé : Statique vs Dynamique
+
+| Fonctionnalité          | Mode Statique                                             | Mode Dynamique                                  |
+| :---------------------- | :-------------------------------------------------------- | :---------------------------------------------- |
+| **Taille du bundle JS** | Plus grande (inclut toutes les langues pour le composant) | Plus petite (seulement le code, pas le contenu) |
+| **Chargement initial**  | Instantané (Le contenu est dans le bundle)                | Légère attente (Récupère du JSON)               |
+| **Requêtes réseau**     | 0 requêtes supplémentaires                                | 1 requête par dictionnaire                      |
+| **Tree Shaking**        | Niveau composant                                          | Niveau composant + niveau langue                |
+| **Cas d'utilisation**   | Composants UI, petites applications                       | Pages avec beaucoup de texte, plusieurs langues |