@intlayer/docs 7.3.0 → 7.3.2-canary.0

package/docs/en-GB/bundle_optimization.md

@@ -0,0 +1,184 @@
+---
+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/my-key/en.json").then(
+      (mod) => mod.default
+    ),
+  fr: () =>
+    import(".intlayer/dynamic_dictionary/my-key/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/compiler.md

@@ -0,0 +1,133 @@
+---
+createdAt: 2025-09-09
+updatedAt: 2025-09-09
+title: Intlayer Compiler | Automated Content Extraction for i18n
+description: Automate your internationalisation process with the Intlayer Compiler. Extract content directly from your components for faster, more efficient i18n in Vite, Next.js, and more.
+keywords:
+  - Intlayer
+  - Compiler
+  - Internationalisation
+  - i18n
+  - Automation
+  - Extraction
+  - Speed
+  - Vite
+  - Next.js
+  - React
+  - Vue
+  - Svelte
+slugs:
+  - doc
+  - compiler
+history:
+  - version: 7.3.1
+    date: 2025-11-27
+    changes: Release Compiler
+---
+
+# Intlayer Compiler | Automated Content Extraction for i18n
+
+## What is the Intlayer Compiler?
+
+The **Intlayer Compiler** is a powerful tool designed to automate the process of internationalisation (i18n) in your applications. It scans your source code (JSX, TSX, Vue, Svelte) for content declarations, extracts them, and automatically generates the necessary dictionary files. This allows you to keep your content co-located with your components while Intlayer handles the management and synchronisation of your dictionaries.
+
+## Why Use the Intlayer Compiler?
+
+- **Automation**: Eliminates manual copy-pasting of content into dictionaries.
+- **Speed**: Optimised content extraction ensuring your build process remains fast.
+- **Developer Experience**: Keep content declarations right where they are used, improving maintainability.
+- **Live Updates**: Supports Hot Module Replacement (HMR) for instant feedback during development.
+
+See the [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/compiler_vs_declarative_i18n.md) blog post for a deeper comparison.
+
+## Why not use the Intlayer Compiler?
+
+Whilst the compiler offers an excellent "just works" experience, it also introduces some trade-offs you should be aware of:
+
+- **Heuristic ambiguity**: The compiler must guess what is user-facing content vs. application logic (e.g., `className="active"`, status codes, product IDs). In complex codebases, this can lead to false positives or missed strings that require manual annotations and exceptions.
+- **Static-only extraction**: Compiler-based extraction relies on static analysis. Strings that only exist at runtime (API error codes, CMS fields, etc.) cannot be discovered or translated by the compiler alone, so you still need a complementary runtime i18n strategy.
+
+For a deeper architectural comparison, see the blog post [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/compiler_vs_declarative_i18n.md).
+
+As an alternative, to automate your i18n process whilst keeping full control of your content, Intlayer also provides an auto-extraction command `intlayer transform` (see [CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/transform.md)), or the `Intlayer: extract content to Dictionary` command from the Intlayer VS Code extension (see [VS Code extension documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/vs_code_extension.md)).
+
+## Usage
+
+### Vite
+
+For Vite-based applications (React, Vue, Svelte, etc.), the easiest way to use the compiler is through the `vite-intlayer` plugin.
+
+#### Installation
+
+```bash
+npm install vite-intlayer
+```
+
+#### Configuration
+
+Update your `vite.config.ts` to include the `intlayerCompiler` plugin:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer, intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer(),
+    intlayerCompiler(), // Adds the compiler plugin
+  ],
+});
+```
+
+#### Framework Support
+
+The Vite plugin automatically detects and handles different file types:
+
+- **React / JSX / TSX**: Handled natively.
+- **Vue**: Requires `@intlayer/vue-compiler`.
+- **Svelte**: Requires `@intlayer/svelte-compiler`.
+
+Make sure to install the appropriate compiler package for your framework:
+
+```bash
+# For Vue
+npm install @intlayer/vue-compiler
+
+# For Svelte
+npm install @intlayer/svelte-compiler
+```
+
+### Next.js (Babel)
+
+For Next.js or other Webpack-based applications using Babel, you can configure the compiler using the `@intlayer/babel` plugin.
+
+#### Installation
+
+```bash
+npm install @intlayer/babel
+```
+
+#### Configuration
+
+Update your `babel.config.js` (or `babel.config.json`) to include the extraction plugin. We provide a helper `getExtractPluginOptions` to load your Intlayer configuration automatically.
+
+```js fileName="babel.config.js"
+const {
+  intlayerExtractBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    // Extract content from components into dictionaries
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    // Optimize imports by replacing useIntlayer with direct dictionary imports
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+This configuration ensures that content declared in your components is automatically extracted and used to generate dictionaries during your build process.

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,194 @@
+---
+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/my-key/en.json").then(
+      (mod) => mod.default
+    ),
+  fr: () =>
+    import(".intlayer/dynamic_dictionary/my-key/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/compiler.md

@@ -0,0 +1,133 @@
+---
+createdAt: 2025-09-09
+updatedAt: 2025-09-09
+title: Intlayer Compiler | Extracción Automática de Contenido para i18n
+description: Automatiza tu proceso de internacionalización con el Intlayer Compiler. Extrae contenido directamente de tus componentes para una i18n más rápida y eficiente en Vite, Next.js y más.
+keywords:
+  - Intlayer
+  - Compiler
+  - Internacionalización
+  - i18n
+  - Automatización
+  - Extracción
+  - Velocidad
+  - Vite
+  - Next.js
+  - React
+  - Vue
+  - Svelte
+slugs:
+  - doc
+  - compiler
+history:
+  - version: 7.3.1
+    date: 2025-11-27
+    changes: Lanzamiento del Compiler
+---
+
+# Intlayer Compiler | Extracción Automática de Contenido para i18n
+
+## ¿Qué es el Intlayer Compiler?
+
+El **Intlayer Compiler** es una herramienta poderosa diseñada para automatizar el proceso de internacionalización (i18n) en tus aplicaciones. Escanea tu código fuente (JSX, TSX, Vue, Svelte) en busca de declaraciones de contenido, las extrae y genera automáticamente los archivos de diccionario necesarios. Esto te permite mantener tu contenido junto a tus componentes mientras Intlayer se encarga de la gestión y sincronización de tus diccionarios.
+
+## ¿Por qué usar el Intlayer Compiler?
+
+- **Automatización**: Elimina el copiado manual de contenido en los diccionarios.
+- **Velocidad**: Extracción de contenido optimizada que asegura que tu proceso de build siga siendo rápido.
+- **Experiencia del desarrollador**: Mantén las declaraciones de contenido justo donde se usan, mejorando la mantenibilidad.
+- **Actualizaciones en vivo**: Soporta Hot Module Replacement (HMR) para retroalimentación instantánea durante el desarrollo.
+
+Consulta el artículo del blog [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/compiler_vs_declarative_i18n.md) para una comparación más profunda.
+
+## ¿Por qué no usar el Intlayer Compiler?
+
+Si bien el compilador ofrece una excelente experiencia de "funciona sin más", también introduce algunos compromisos de los que debes ser consciente:
+
+- **Ambigüedad heurística**: El compilador debe adivinar qué es contenido orientado al usuario frente a la lógica de la aplicación (por ejemplo, `className="active"`, códigos de estado, IDs de productos). En bases de código complejas, esto puede llevar a falsos positivos o cadenas omitidas que requieren anotaciones manuales y excepciones.
+- **Extracción solo estática**: La extracción basada en compilador se basa en análisis estático. Las cadenas que solo existen en tiempo de ejecución (códigos de error de API, campos CMS, etc.) no pueden ser descubiertas o traducidas por el compilador solo, por lo que aún necesitas una estrategia i18n de tiempo de ejecución complementaria.
+
+Para una comparación arquitectónica más profunda, consulta el artículo del blog [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/compiler_vs_declarative_i18n.md).
+
+Como alternativa, para automatizar tu proceso i18n mientras mantienes el control total de tu contenido, Intlayer también proporciona un comando de auto-extracción `intlayer transform` (consulta la [documentación CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/transform.md)), o el comando `Intlayer: extract content to Dictionary` de la extensión Intlayer VS Code (consulta la [documentación de la extensión VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/vs_code_extension.md)).
+
+## Uso
+
+### Vite
+
+Para aplicaciones basadas en Vite (React, Vue, Svelte, etc.), la forma más sencilla de usar el compilador es a través del plugin `vite-intlayer`.
+
+#### Instalación
+
+```bash
+npm install vite-intlayer
+```
+
+#### Configuración
+
+Actualiza tu `vite.config.ts` para incluir el plugin `intlayerCompiler`:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer, intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer(),
+    intlayerCompiler(), // Añade el plugin del compilador
+  ],
+});
+```
+
+#### Soporte de Framework
+
+El plugin de Vite detecta y maneja automáticamente diferentes tipos de archivos:
+
+- **React / JSX / TSX**: Manejado de forma nativa.
+- **Vue**: Requiere `@intlayer/vue-compiler`.
+- **Svelte**: Requiere `@intlayer/svelte-compiler`.
+
+Asegúrate de instalar el paquete de compilador adecuado para tu framework:
+
+```bash
+# Para Vue
+npm install @intlayer/vue-compiler
+
+# Para Svelte
+npm install @intlayer/svelte-compiler
+```
+
+### Next.js (Babel)
+
+Para Next.js u otras aplicaciones basadas en Webpack que usan Babel, puedes configurar el compilador usando el plugin `@intlayer/babel`.
+
+#### Instalación
+
+```bash
+npm install @intlayer/babel
+```
+
+#### Configuración
+
+Actualiza tu `babel.config.js` (o `babel.config.json`) para incluir el plugin de extracción. Proporcionamos un helper `getExtractPluginOptions` para cargar automáticamente tu configuración de Intlayer.
+
+```js fileName="babel.config.js"
+const {
+  intlayerExtractBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    // Extract content from components into dictionaries
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    // Optimize imports by replacing useIntlayer with direct dictionary imports
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+Esta configuración asegura que el contenido declarado en tus componentes se extraiga automáticamente y se utilice para generar diccionarios durante tu proceso de compilación.