@intlayer/docs 8.12.2 → 8.12.4-canary.0

package/docs/es/bundle_optimization.md

@@ -1,10 +1,10 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-04-08
-title: Optimización del tamaño y rendimiento del bundle i18n
-description: Reduzca el tamaño del bundle de su aplicación optimizando el contenido de internacionalización (i18n). Aprenda a aprovechar el tree shaking y la carga diferida para los diccionarios con Intlayer.
+updatedAt: 2026-06-07
+title: Optimización del tamaño y rendimiento del paquete i18n
+description: Reduce el tamaño del paquete de tu aplicación optimizando el contenido de internacionalización (i18n). Aprende cómo aprovechar el tree shaking y el lazy loading para diccionarios con Intlayer.
 keywords:
-  - Optimización de bundle
+  - Optimización de paquete
   - Automatización de contenido
   - Contenido dinámico
   - Intlayer
@@ -16,33 +16,36 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 8.12.0
+    date: 2026-06-07
+    changes: "Añadidos `intlayerPurgeBabelPlugin` y `intlayerMinifyBabelPlugin` para Babel/Webpack; aclaración del flujo de plugins"
   - version: 8.7.0
     date: 2026-04-08
-    changes: "Se añadieron las opciones `minify` y `purge` a la configuración de construcción"
+    changes: "Añadidas las opciones `minify` y `purge` a la configuración de compilación"
 ---
 
-# Optimización del tamaño y rendimiento del bundle i18n
+# Optimización del tamaño y rendimiento del paquete i18n
 
-Uno de los desafíos más comunes con las soluciones i18n tradicionales que dependen de archivos JSON es la gestión del tamaño del contenido. Si los desarrolladores no separan manualmente el contenido en namespaces, los usuarios a menudo terminan descargando traducciones para cada página y potencialmente para cada idioma solo para ver una sola página.
+Uno de los desafíos más comunes con las soluciones i18n tradicionales basadas en archivos JSON es la gestión del tamaño del contenido. Si los desarrolladores no separan manualmente el contenido en espacios de nombres (namespaces), a menudo los usuarios terminan descargando traducciones para cada página y potencialmente para todos los idiomas solo para ver una página en concreto.
 
-Por ejemplo, una aplicación con 10 páginas traducidas a 10 idiomas podría resultar en 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.
+Por ejemplo, una aplicación con 10 páginas traducidas a 10 idiomas podría provocar que un usuario descargue el contenido de 100 páginas, aunque solo necesite **una** (la página actual en el idioma actual). Esto genera un desperdicio de ancho de banda y tiempos de carga más lentos.
 
-**Intlayer resuelve este problema a través de la optimización en tiempo de compilación (build time).** Analiza su código para detectar qué diccionarios se usan realmente por componente y reinyecta solo el contenido necesario en su bundle.
+**Intlayer resuelve este problema a través de la optimización en el momento de la compilación.** Analiza tu código para detectar qué diccionarios se utilizan realmente por cada componente y reinyecta en tu paquete (bundle) solo el contenido necesario.
 
 ## Tabla de contenidos
 
 <TOC />
 
-## Escanee su bundle
+## Analiza tu paquete
 
-Analizar su bundle es el primer paso para identificar archivos JSON "pesados" y oportunidades de división de código (code-splitting). Estas herramientas generan un mapa de árbol visual del código compilado de su aplicación, lo que le permite ver exactamente qué librerías están consumiendo más espacio.
+Analizar tu paquete es el primer paso para identificar archivos JSON "pesados" y oportunidades de división de código (code-splitting). Estas herramientas generan un treemap visual del código compilado de tu aplicación, permitiéndote ver exactamente qué bibliotecas consumen más espacio.
 
 <Tabs>
  <Tab value="vite">
 
 ### Vite / Rollup
 
-Vite utiliza Rollup internamente. El complemento `rollup-plugin-visualizer` genera un archivo HTML interactivo que muestra el tamaño de cada módulo en su gráfico.
+Vite utiliza Rollup bajo el capó. El complemento `rollup-plugin-visualizer` genera un archivo HTML interactivo que muestra el tamaño de cada módulo en tu gráfico de dependencias.
 
 ```bash
 npm install -D rollup-plugin-visualizer
@@ -55,7 +58,7 @@ import { visualizer } from "rollup-plugin-visualizer";
 export default defineConfig({
   plugins: [
     visualizer({
-      open: true, // Abrir automáticamente el informe en su navegador
+      open: true, // Abre automáticamente el informe en tu navegador
       filename: "stats.html",
       gzipSize: true,
       brotliSize: true,
@@ -69,7 +72,7 @@ export default defineConfig({
 
 ### Next.js (Turbopack)
 
-Para proyectos que utilizan App Router y Turbopack, Next.js proporciona un analizador experimental integrado que no requiere dependencias adicionales.
+Para proyectos que usan App Router y Turbopack, Next.js incluye un analizador experimental incorporado que no requiere dependencias adicionales.
 
 ```bash packageManager='npm'
 npx next experimental-analyze
@@ -92,7 +95,7 @@ bun next experimental-analyze
 
 ### Next.js (Webpack)
 
-Si está utilizando el empaquetador Webpack predeterminado en Next.js, use el analizador de bundle oficial. Actívelo configurando una variable de entorno durante su construcción.
+Si estás usando el bundler predeterminado de Webpack en Next.js, usa el analizador de paquetes oficial. Actívalo definiendo una variable de entorno durante la compilación.
 
 ```bash packageManager='npm'
 npm install -D @next/bundle-analyzer
@@ -116,7 +119,7 @@ const withBundleAnalyzer = require("@next/bundle-analyzer")({
 });
 
 module.exports = withBundleAnalyzer({
-  // Su configuración de Next.js
+  // Tu configuración de Next.js
 });
 ```
 
@@ -131,7 +134,7 @@ ANALYZE=true npm run build
 
 ### Webpack estándar
 
-Para Create React App (ejected), Angular o configuraciones personalizadas de Webpack, use el estándar de la industria `webpack-bundle-analyzer`.
+Para Create React App (ejected), Angular, o configuraciones de Webpack personalizadas, utiliza el estándar de la industria `webpack-bundle-analyzer`.
 
 ```bash packageManager='npm'
 npm install -D webpack-bundle-analyzer
@@ -168,16 +171,53 @@ export default {
 
 ## Cómo funciona
 
-Intlayer utiliza un **enfoque por componente**. A diferencia de los archivos JSON globales, su contenido se define junto o dentro de sus componentes. Durante el proceso de construcción, Intlayer:
+Intlayer utiliza un **enfoque por componente**. A diferencia de los archivos JSON globales, el contenido se define junto a o dentro de tus componentes. Durante el proceso de compilación, Intlayer:
 
-1.  **Analiza** su 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 su configuración.
+1. **Analiza** tu código para encontrar llamadas a `useIntlayer`.
+2. **Construye** el contenido del diccionario correspondiente.
+3. **Reemplaza** la llamada a `useIntlayer` con un código optimizado basado en tu configuración.
 
-Esto garantiza que:
+Esto asegura 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 diferida (lazy-loading), su contenido también se carga de forma diferida.
+- Si un componente no se importa, su contenido no se incluye en el paquete (Eliminación de código muerto o Dead Code Elimination).
+- Si un componente se carga mediante lazy loading, su contenido también se carga dinámicamente.
+
+## Referencia de Plugins
+
+La optimización de compilación de Intlayer se divide en varios complementos discretos, cada uno con una responsabilidad única. Entender lo que hace cada uno evita la confusión al configurarlos.
+
+### Plugins de Babel (`@intlayer/babel`)
+
+Se utilizan directamente en `babel.config.js` para configuraciones basadas en Webpack (Next.js con Babel, CRA, Webpack personalizado, etc.).
+
+| Plugin                        | Qué hace                                                                                                                                    |
+| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
+| `intlayerExtractBabelPlugin`  | Analiza archivos `.content.ts` y escribe los diccionarios compilados en `.intlayer/`                                                        |
+| `intlayerOptimizeBabelPlugin` | Reescribe `useIntlayer('key')` → `useDictionary(hash)` e inyecta la declaración `import` del diccionario correspondiente                    |
+| `intlayerPurgeBabelPlugin`    | Analiza todos los archivos fuente y elimina **los campos de contenido no utilizados** de los archivos JSON `.intlayer/**/*.json`            |
+| `intlayerMinifyBabelPlugin`   | **Renombra las claves de campos de contenido** por alias alfabéticos cortos (`title` → `a`) tanto en archivos JSON como en el código fuente |
+
+> **El orden de los plugins es importante.** En tu `babel.config.js`, los complementos de purga (purge) y minificación (minify) deben aparecer **antes** del complemento de optimización. La fase de optimización reemplaza `useIntlayer('key')` con una llamada opaca `useDictionary(hash)`, lo que borra la información de clave del diccionario que las fases de purga y minificación necesitan para saber qué campos se usan.
+
+Cada complemento de Babel cuenta con una función auxiliar de opciones que lee tu `intlayer.config.ts` una vez en tiempo de carga y devuelve los valores pre-resueltos:
+
+| Helper de opciones           | Utilizado con                 |
+| :--------------------------- | :---------------------------- |
+| `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
+| `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
+| `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+
+### Plugins de Vite (`vite-intlayer`)
+
+Los usuarios de Vite **nunca los configuran directamente**. Se vinculan de forma automática al invocar `withIntlayer()` en `vite.config.ts`. Las variables `build.purge` y `build.minify` en `intlayer.config.ts` alternan el comportamiento correspondiente sin necesidad de registrar ningún otro complemento.
+
+| Plugin interno de Vite | Comportamiento equivalente                                                                                   |
+| :--------------------- | :----------------------------------------------------------------------------------------------------------- |
+| Analizador de uso      | Igual que la fase de análisis del `intlayerPurgeBabelPlugin`                                                 |
+| Poda de diccionarios   | Igual que la fase de escritura JSON del `intlayerPurgeBabelPlugin`                                           |
+| Minificar diccionario  | Igual que la fase de escritura JSON del `intlayerMinifyBabelPlugin`                                          |
+| Transformación Babel   | Igual que la fase de renombramiento en código de `intlayerMinifyBabelPlugin` + `intlayerOptimizeBabelPlugin` |
 
 ## Configuración por plataforma
 
@@ -186,9 +226,9 @@ Esto garantiza que:
 
 ### Next.js
 
-Next.js requiere el complemento `@intlayer/swc` para manejar la transformación, ya que Next.js utiliza SWC para las construcciones.
+Next.js requiere el complemento `@intlayer/swc` para la fase de optimización (reescritura de importaciones) ya que Next.js emplea SWC en las compilaciones.
 
-> Este complemento no se instala de forma predeterminada porque los complementos de SWC todavía son experimentales para Next.js. Podría cambiar en el futuro.
+> Este complemento no se instala por defecto ya que los complementos SWC son experimentales en Next.js. Podría cambiar en el futuro.
 
 ```bash packageManager="npm"
 npm install -D @intlayer/swc
@@ -208,19 +248,61 @@ bun add -d @intlayer/swc
 
 Una vez instalado, Intlayer detectará y utilizará automáticamente el complemento.
 
+Para las fases de **purga y minificación** (eliminación de campos y renombramiento), instala de manera adicional `@intlayer/babel` y añade los complementos de Babel. Debido a que Next.js usa SWC para la transformación pero aún evalúa `babel.config.js` para la configuración, estos complementos de Babel se ejecutan en un paso previo antes de SWC.
+
+```bash packageManager="npm"
+npm install -D @intlayer/babel
+```
+
+```javascript fileName="babel.config.js"
+const {
+  intlayerPurgeBabelPlugin,
+  intlayerMinifyBabelPlugin,
+  getPurgePluginOptions,
+  getMinifyPluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    // Purga: eliminar los campos de contenido no usados de .intlayer/**/*.json
+    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
+    // Minificar: renombrar claves de campos en el JSON y el código fuente
+    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
+    // Nota: intlayerOptimizeBabelPlugin NO es necesario aquí porque
+    // @intlayer/swc se encarga de reescribir useIntlayer → useDictionary.
+  ],
+};
+```
+
  </Tab>
  <Tab value="vite">
 
 ### Vite
 
-Vite utiliza el complemento `@intlayer/babel`, que se incluye como dependencia de `vite-intlayer`. La optimización está habilitada de forma predeterminada. No hay nada más que hacer.
+Vite utiliza el complemento `@intlayer/babel`, el cual está incluido como una dependencia de `vite-intlayer`. El flujo de optimización completo —reescritura de importaciones, purga y minificación— está activado por defecto y no requiere registrar complementos extra.
+
+Activa la purga y la minificación fijando las variables pertinentes en `intlayer.config.ts`:
+
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // eliminar campos no usados de los JSON empaquetados
+    minify: true, // renombrar las claves de campos a alias cortos
+  },
+};
+
+export default config;
+```
 
  </Tab>
  <Tab value="webpack">
 
-### Webpack
+### Webpack (y Next.js con Babel)
 
-Para habilitar la optimización del bundle con Intlayer en Webpack, debe instalar y configurar el complemento Babel (`@intlayer/babel`) o SWC (`@intlayer/swc`) adecuado.
+Instala `@intlayer/babel`:
 
 ```bash packageManager="npm"
 npm install -D @intlayer/babel
@@ -238,14 +320,37 @@ pnpm add -D @intlayer/babel
 bun add -d @intlayer/babel
 ```
 
-```typescript fileName="babel.config.js"
+Agrega los cuatro plugins a `babel.config.js` en el orden correcto:
+
+```javascript fileName="babel.config.js"
 const {
-  getOptimizePluginOptions,
+  intlayerExtractBabelPlugin,
+  intlayerPurgeBabelPlugin,
+  intlayerMinifyBabelPlugin,
   intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getPurgePluginOptions,
+  getMinifyPluginOptions,
+  getOptimizePluginOptions,
 } = require("@intlayer/babel");
 
 module.exports = {
-  plugins: [[intlayerOptimizeBabelPlugin, getOptimizePluginOptions()]],
+  plugins: [
+    // Extract: compilar archivos .content.ts → .intlayer/**/*.json
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+
+    // Purge: eliminar los campos no usados de .intlayer/**/*.json
+    //    (lee la variable build.purge de intlayer.config.ts)
+    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
+
+    // Minify: renombrar las claves en el JSON y el código fuente
+    //    (lee la variable build.minify de intlayer.config.ts)
+    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
+
+    // Optimize: reescribe useIntlayer('key') → useDictionary(hash)
+    //    Debe ir al último porque elimina la clave del diccionario.
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
 };
 ```
 
@@ -254,57 +359,62 @@ module.exports = {
 
 ## Configuración
 
-Puede controlar cómo Intlayer optimiza su bundle a través de la propiedad `build` en su `intlayer.config.ts`.
+Puedes controlar cómo Intlayer optimiza el tamaño de tu paquete mediante la propiedad `build` en tu `intlayer.config.ts`.
 
 ```typescript fileName="intlayer.config.ts"
 import { Locales, type IntlayerConfig } from "intlayer";
 
 const config: IntlayerConfig = {
   internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH],
+    locales: [Locales.ENGLISH, Locales.SPANISH],
     defaultLocale: Locales.ENGLISH,
   },
   dictionary: {
     importMode: "dynamic",
   },
   build: {
-    /**
-     * Minificar los diccionarios para reducir el tamaño del bundle.
-     */
-     minify: true;
-
-    /**
-     * Purgar las claves no utilizadas en los diccionarios
-     */
-     purge: true;
-
-    /**
-     * Indica si la construcción debe verificar los tipos de TypeScript
-     */
-    checkTypes: false;
+    // Reemplaza llamadas a useIntlayer() con importaciones directas de diccionario
+    // al momento de compilar. undefined = auto (activo en prod), true = siempre, false = nunca.
+    optimize: undefined,
+
+    // Renombra las claves de campos de contenido en los diccionarios a alias cortos
+    // alfabéticos (ej. title → a). Reduce el tamaño de JSON; requiere optimize.
+    minify: true,
+
+    // Elimina los campos de contenido a los que no se acceda en el código fuente.
+    // Requiere optimize.
+    purge: true,
   },
 };
 
 export default config;
 ```
 
-> Se recomienda mantener la opción predeterminada para `optimize` en la gran mayoría de los casos.
+> Se recomienda mantener el valor por defecto (`undefined`) para `optimize` en la gran mayoría de los casos.
 
-> Consulte la documentación de configuración para más detalles: [Configuración](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md)
+> Consulta la referencia de configuración para ver todas las opciones: [Configuración](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md)
 
-### Opciones de construcción
+### Opciones de compilación (Build Options)
 
-Las siguientes opciones están disponibles bajo el objeto de configuración `build`:
+| Propiedad      | Tipo                   | Por defecto | Descripción                                                                                                                                                                                    |
+| :------------- | :--------------------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`optimize`** | `boolean \| undefined` | `undefined` | Habilita el paso de reescritura de importación. `undefined` = activo solo en compilaciones de producción. `false` también deshabilita purga y minificación.                                    |
+| **`minify`**   | `boolean`              | `false`     | Renombra las claves de campos en los JSON a alias alfabéticos cortos. También reescribe los accesos a propiedades que coincidan en el código fuente. No surte efecto si `optimize` es `false`. |
+| **`purge`**    | `boolean`              | `false`     | Elimina los campos a los que nunca se acceda en código estático desde los archivos JSON compilados. No surte efecto si `optimize` es `false`.                                                  |
 
-| Propiedad      | Tipo      | Predeterminado | Descripción                                                                                                                                                                                                             |
-| :------------- | :-------- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`optimize`** | `boolean` | `undefined`    | Controla si la optimización de la construcción está habilitada. Si es `true`, Intlayer reemplaza las llamadas a diccionarios con inyecciones optimizadas. Si es `false`, la optimización se deshabilita. Ideal en prod. |
-| **`minify`**   | `boolean` | `false`        | Si se deben minificar los diccionarios para reducir el tamaño del bundle.                                                                                                                                               |
-| **`purge`**    | `boolean` | `false`        | Si se deben purgar las claves no utilizadas en los diccionarios.                                                                                                                                                        |
+### Minificación (renombramiento de campos)
 
-### Minificación
+`build.minify` **no** minifica tu código JavaScript; eso lo hace el bundler. Lo que hace es reducir el tamaño de los JSON resultantes al reemplazar toda clave definida por el usuario por un alias alfabético:
 
-Minificar diccionarios elimina espacios en blanco innecesarios, comentarios y reduce el tamaño del contenido JSON. Esto es especialmente útil para diccionarios grandes.
+```
+// Antes de minificar
+{ "title": "Hola", "subtitle": "Mundo" }
+
+// Después de minificar
+{ "a": "Hola", "b": "Mundo" }
+```
+
+Este mismo renombramiento se propaga en tus accesos a propiedades en el código, por lo que `content.title` pasa a ser `content.a` durante la compilación. El comportamiento en tiempo de ejecución sigue siendo idéntico.
 
 ```typescript fileName="intlayer.config.ts"
 import type { IntlayerConfig } from "intlayer";
@@ -318,11 +428,13 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-> Nota: La minificación se ignora si `optimize` está deshabilitado o si el Editor Visual está habilitado (ya que el editor necesita el contenido completo para permitir la edición).
+> La minificación se omite cuando `optimize` es `false` o cuando `editor.enabled` es `true` (el Editor Visual requiere de los nombres de los campos originales para editarlos).
+
+> La minificación también se omite con diccionarios de `importMode: 'fetch'`, dado que esos JSON son provistos por una API de terceros bajo sus nombres de campos originales; renombrarlo en el cliente perjudicaría a esa sincronización.
 
-### Purgado
+### Purga (eliminación de campos no utilizados)
 
-El purgado garantiza que solo las claves realmente utilizadas en su código se incluyan en el bundle final de diccionarios. Esto puede reducir significativamente el tamaño de su bundle si tiene diccionarios grandes con muchas claves que no se usan en todas las partes de su aplicación.
+`build.purge` analiza qué campos de contenido son visitados en tu código fuente y elimina al resto en el JSON compilado.
 
 ```typescript fileName="intlayer.config.ts"
 import type { IntlayerConfig } from "intlayer";
@@ -336,34 +448,50 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-> Nota: El purgado se ignora si `optimize` está deshabilitado.
+**Ejemplo:** en un diccionario con 5 campos de los cuales solo se emplean 2:
+
+```
+// Antes de la purga
+{ "title": "…", "subtitle": "…", "cta": "…", "footer": "…", "badge": "…" }
+
+// Después de la purga (solo título y subtítulo son consumidos)
+{ "title": "…", "subtitle": "…" }
+```
+
+> La purga se omite cuando `optimize` es `false` o cuando `editor.enabled` es `true`.
+
+> La purga también se omite por protección cuando un archivo del código fuente sea irreparable y no logre ejecutarse `useIntlayer` al mismo tiempo que una destructuración. Por lo cual todo el diccionario pasaría a formar parte por completo y sin purgar.
+
+### Modo de Importación
 
-### Modo de importación
+Para aplicaciones grandes que incluyen múltiples páginas e idiomas, el contenido JSON puede ocupar un espacio significativo en tu paquete (bundle). Intlayer te permite controlar cómo se cargan los diccionarios usando la opción `importMode`.
 
-Para aplicaciones grandes, que incluyen varias páginas y configuraciones regionales, sus archivos JSON pueden representar una parte significativa del tamaño de su bundle. Intlayer le permite controlar cómo se cargan los diccionarios.
+### Definición global
 
-El modo de importación puede definirse por defecto globalmente en su archivo `intlayer.config.ts`.
+El modo de importación puede ser definido de manera global en tu archivo `intlayer.config.ts`.
 
 ```typescript fileName="intlayer.config.ts"
 import type { IntlayerConfig } from "intlayer";
 
 const config: IntlayerConfig = {
-  build: {
-    minify: true,
+  dictionary: {
+    importMode: "dynamic", // El valor predeterminado es 'static'
   },
 };
 
 export default config;
 ```
 
-Así como para cada diccionario en sus archivos `.content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5}}`.
+### Definición individual
+
+Puedes sobrescribir el modo de importación para diccionarios individuales en sus propios archivos `.content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5|md|mdx|yaml|yml}}`.
 
 ```ts
 import { type Dictionary, t } from "intlayer";
 
 const appContent: Dictionary = {
   key: "app",
-  importMode: "dynamic", // Sobrescribir el modo de importación predeterminado
+  importMode: "dynamic", // Sobrescribe el valor global
   content: {
     // ...
   },
@@ -372,28 +500,28 @@ const appContent: Dictionary = {
 export default appContent;
 ```
 
-| Propiedad        | Tipo                               | Predeterminado | Descripción                                                                                                                     |
-| :--------------- | :--------------------------------- | :------------- | :------------------------------------------------------------------------------------------------------------------------------ |
-| **`importMode`** | `'static'`, `'dynamic'`, `'fetch'` | `'static'`     | **Obsoleto**: Use `dictionary.importMode` en su lugar. Determina cómo se cargan los diccionarios (ver detalles a continuación). |
+| Propiedad        | Tipo                               | Por Defecto | Descripción                                                                                                                         |
+| :--------------- | :--------------------------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------- |
+| **`importMode`** | `'static'`, `'dynamic'`, `'fetch'` | `'static'`  | **Obsoleto**: Utiliza `dictionary.importMode` en su lugar. Determina cómo se cargan los diccionarios (ver detalles a continuación). |
 
-La configuración `importMode` dicta cómo se inyecta el contenido del diccionario en su componente.
-Puede definirlo globalmente en el archivo `intlayer.config.ts` bajo el objeto `dictionary`, o puede sobrescribirlo para un diccionario específico en su archivo `.content.ts`.
+La configuración `importMode` dicta la manera en que los contenidos del diccionario se inyectan en tu componente. Puedes fijarlo de forma global dentro del objeto `dictionary` en `intlayer.config.ts`, o para cada archivo en particular.
 
-### 1. Modo estático (`default`)
+### 1. Modo Estático (`default`)
 
-En modo estático, Intlayer reemplaza `useIntlayer` con `useDictionary` e inyecta el diccionario directamente en el bundle de JavaScript.
+En el modo estático, Intlayer reemplaza `useIntlayer` por `useDictionary` e inserta el diccionario directamente en el paquete de JavaScript.
 
-- **Pros:** Renderizado instantáneo (síncrono), cero solicitudes de red adicionales durante la hidratación.
-- **Contras:** El bundle incluye traducciones para **todos** los idiomas disponibles para ese componente específico.
-- **Ideal para:** Aplicaciones de una sola página (SPA).
+- **Ventajas:** Renderizado instantáneo (sincrónico), cero llamadas de red extra durante la hidratación (hydration).
+- **Desventajas:** El paquete contendrá las traducciones de **todos** los idiomas posibles que ese componente pudiese alcanzar.
+- **Mejor para:** Aplicaciones de una sola página (SPA).
 
 **Ejemplo de código transformado:**
 
 ```tsx
-// Su código
+// Tu código fuente
 const content = useIntlayer("my-key");
 
-// Código optimizado (Estatico)
+// Ilustración del código optimizado después de la transformación (Static)
+// Este código solo es de referencia y puede variar de forma interna
 const content = useDictionary({
   key: "my-key",
   content: {
@@ -401,54 +529,74 @@ const content = useDictionary({
     translation: {
       en: "My title",
       fr: "Mon titre",
+      es: "Mi título",
     },
   },
 });
 ```
 
-### 2. Modo dinámico
+### 2. Modo Dinámico
 
-En modo dinámico, Intlayer reemplaza `useIntlayer` con `useDictionaryAsync`. Esto utiliza `import()` (mecanismo similar a Suspense) para cargar de forma diferida específicamente el JSON para la configuración regional actual.
+En el modo dinámico, Intlayer sustituye `useIntlayer` con `useDictionaryAsync`. Para ello emplea importaciones dinámicas `import()` como mecanismo de Lazy Loading cargando el archivo de su propio lenguaje de modo pertinente.
 
-- **Pros:** **Tree shaking a nivel de locale.** 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.
-- **Contras:** Activa una solicitud de red (obtención de activos) por componente durante la hidratación.
-- **Ideal para:** Bloques de texto grandes, artículos o aplicaciones que admiten muchos idiomas donde el tamaño del bundle es crítico.
+- **Ventajas:** **Tree shaking a nivel de idioma.** El usuario que navega tu portal en español, solo descargará el JSON en español. El JSON en francés jamás será consumido.
+- **Desventajas:** Dispara una llamada HTTP adicional (asset) desde cada uno de los elementos presentes al hidratarse.
+- **Mejor para:** Textos pesados o portales globales donde prime la velocidad y reducir el gasto del paquete o (bundle size).
 
 **Ejemplo de código transformado:**
 
 ```tsx
-// Su código
+// Tu código fuente
 const content = useIntlayer("my-key");
 
-// Código optimizado (Dinámico)
+// Ilustración de código dinámico procesado
 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(
+  es: () =>
+    import(".intlayer/dynamic_dictionary/my-key/es.json").then(
       (mod) => mod.default
     ),
 });
 ```
 
-> Al usar `importMode: 'dynamic'`, si tiene 100 componentes que usan `useIntlayer` en una sola página, el navegador intentará 100 descargas separadas. Para evitar esta "cascada" de solicitudes, agrupe el contenido en menos archivos `.content` (por ejemplo, un diccionario por sección de la página) en lugar de uno por componente átomo.
+> Al usar `importMode: 'dynamic'`, debes tener en cuenta que, si hay 100 componentes distintos llamando a `useIntlayer` en una pantalla, el navegador hará 100 descargas diminutas por separado. Trata de limitar dichas peticiones, creando, por ejemplo, archivos de diccionario que abarquen más de un átomo o grupo y unifica su llamado por vista. Varios archivos de contenido pueden tener a su vez la misma clave dictada fusionándose automáticamente.
 
 ### 3. Modo Fetch
 
-Se comporta de manera similar al modo dinámico, pero intenta obtener diccionarios de la API de Live Sync de Intlayer primero. Si la llamada a la API falla o el contenido no está marcado para actualizaciones en vivo, recurre a la importación dinámica.
+Trabaja de un modo afín al Dinámico, con la disyuntiva de tratar de consultar su modelo hacia la API remota de "Intlayer Live Sync". Confiando de primera mano sobre este y recayendo en la importación dinámica en el fallo de este.
+
+**Ejemplo de código transformado:**
+
+```tsx
+// Tu código fuente
+const content = useIntlayer("my-key");
+
+// Código Fetch procesado de modo ilustrativo
+const content = useDictionaryAsync({
+  en: () =>
+    fetch("https://intlayer.my-domain.com/dictionary/my-key/en").then((res) =>
+      res.json()
+    ),
+  es: () =>
+    fetch("https://intlayer.my-domain.com/dictionary/my-key/es").then((res) =>
+      res.json()
+    ),
+});
+```
 
-> Consulte la documentación del CMS para más detalles: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md)
+> Aprende más desde la guía del CMS: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md)
 
-> En modo fetch, no se pueden usar el purgado y la minificación.
+> Recordamos que con el modo "Fetch", el código original prevalecerá y sus elementos no se purgarán ni formarán parte de una minificación preestablecida.
 
 ## 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 comp.)      | Más pequeño (solo código, sin contenido)  |
-| **Carga inicial**        | Instantánea (El contenido está en el bundle)              | Ligero retraso (Obtiene el JSON)          |
-| **Solicitudes de red**   | 0 solicitudes adicionales                                 | 1 solicitud por diccionario               |
-| **Tree Shaking**         | A nivel de componente                                     | A nivel de componente + A nivel de locale |
-| **Mejor caso de uso**    | Componentes de interfaz de usuario, aplicaciones pequeñas | Páginas con mucho texto, muchos idiomas   |
+| Característica              | Modo Estático                               | Modo Dinámico                                 |
+| :-------------------------- | :------------------------------------------ | :-------------------------------------------- |
+| **Tamaño JS del paquete**   | Alto (Integra todos los locales existentes) | Pequeño (Baja solo su modelo correspondiente) |
+| **Carga Inicial**           | Instantánea                                 | Ligera demora o espera                        |
+| **Llamadas de red (Fetch)** | 0 adicionales                               | 1 por key del diccionario                     |
+| **Tree Shaking**            | Presente desde el componente                | Desde el componente + Local                   |
+| **Mejor uso para:**         | Elementos visuales, Apps ligeras            | Enormes bloques de texto, Múltiples regiones  |

package/docs/es/configuration.md

@@ -681,16 +681,16 @@ routing: {
 
 Cuando se utiliza el almacenamiento mediante galletas (cookies), se pueden configurar atributos adicionales:
 
-| Campo      | Tipo                                                  | Descripción                                                                                                  |
-| ---------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `name`     | `string`                                              | Nombre de la galleta (cookie). Predeterminado: `'INTLAYER_LOCALE'`                                           |
-| `domain`   | `string`                                              | Dominio de la galleta. Predeterminado: `undefined`                                                           |
-| `path`     | `string`                                              | Ruta de la galleta. Predeterminado: `undefined`                                                              |
-| `secure`   | `boolean`                                             | Requiere HTTPS. Predeterminado: `undefined`                                                                  |
-| `httpOnly` | `boolean`                                             | Bandera HTTP-only. Predeterminado: `undefined`                                                               |
-| `sameSite` | `'strict'` &#124; <br/> `'lax'` &#124; <br/> `'none'` | Política de SameSite.                                                                                        |
-| `expires`  | `Date` &#124; <br/> `number`                          | Fecha de expiración o número de días. Predeterminado: `undefined`                                            |
-| `maxAge`   | `number`                                              | Tiempo de vida en segundos desde la creación. Tiene precedencia sobre `expires`. Predeterminado: `undefined` |
+| Campo      | Tipo                                                  | Descripción                                                                                                                                    |
+| ---------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`     | `string`                                              | Nombre de la galleta (cookie). Predeterminado: `'INTLAYER_LOCALE'`                                                                             |
+| `domain`   | `string`                                              | Dominio de la galleta. Predeterminado: `undefined`                                                                                             |
+| `path`     | `string`                                              | Ruta de la galleta. Predeterminado: `undefined`                                                                                                |
+| `secure`   | `boolean`                                             | Requiere HTTPS. Predeterminado: `undefined`                                                                                                    |
+| `httpOnly` | `boolean`                                             | Bandera HTTP-only. Predeterminado: `undefined`                                                                                                 |
+| `sameSite` | `'strict'` &#124; <br/> `'lax'` &#124; <br/> `'none'` | Política de SameSite.                                                                                                                          |
+| `expires`  | `Date` &#124; <br/> `number` &#124; <br/> `string`    | Un `number` indica días desde la creación; una `Date` (o cadena de fecha ISO) es una fecha de expiración absoluta. Predeterminado: `undefined` |
+| `maxAge`   | `number`                                              | Tiempo de vida en segundos desde la creación. Tiene precedencia sobre `expires`. Predeterminado: `undefined`                                   |
 
 #### Atributos de Almacenamiento de Localidad (Locale Storage Attributes)