@intlayer/docs 9.0.0-canary.6 → 9.0.0-canary.7

package/docs/es/intlayer_with_vite+solid.md

@@ -596,6 +596,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilador Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Actualiza tu archivo `vite.config.ts` para incluir el plugin `intlayerCompiler` :
 
 ```ts fileName="vite.config.ts"
@@ -605,7 +607,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Agrega el plugin del compilador
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/es/intlayer_with_vite+svelte.md

@@ -458,7 +458,7 @@ Paralelamente, también puedes usar `intlayerProxy` para añadir enrutamiento de
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
 import { svelte } from "@sveltejs/vite-plugin-svelte";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
   plugins: [intlayerProxy(), // should be placed first
  svelte(), intlayer()],
@@ -592,6 +592,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilador Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Actualiza tu archivo `vite.config.ts` para incluir el plugin `intlayerCompiler` :
 
 ```ts fileName="vite.config.ts"
@@ -601,7 +603,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Agrega el plugin del compilador
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/es/intlayer_with_vite+vanilla.md

@@ -205,7 +205,13 @@ import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
-  plugins: [intlayer()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 
@@ -466,12 +472,15 @@ Primero, añade `intlayerProxy` a tu configuración de Vite:
 
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // debe colocarse primero
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```
@@ -603,6 +612,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilador Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Actualiza tu `vite.config.ts` para incluir el plugin `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -612,7 +623,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Añade el plugin del compilador
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/es/intlayer_with_vite+vue.md

@@ -665,14 +665,17 @@ Paralelamente, también puede usar el `intlayerProxy` para agregar enrutamiento
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
 import vue from "@vitejs/plugin-vue";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
     vue(),
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```
@@ -1001,6 +1004,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilador Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Actualiza tu archivo `vite.config.ts` para incluir el plugin `intlayerCompiler` :
 
 ```ts fileName="vite.config.ts"
@@ -1010,7 +1015,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Agrega el plugin del compilador
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/es/packages/@intlayer_babel/export.md

@@ -0,0 +1,131 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: "Documentación del paquete @intlayer/babel"
+description: Complementos de Babel para Intlayer para manejar la extracción de contenido, la optimización de importaciones, la depuración de campos no utilizados y la ofuscación de nombres de campos durante la compilación.
+keywords:
+  - "@intlayer/babel"
+  - babel
+  - plugin
+  - internacionalización
+  - i18n
+  - compilador
+  - optimizar
+  - depurar
+  - minificar
+slugs:
+  - doc
+  - packages
+  - "@intlayer/babel"
+  - export
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Documentación unificada de todas las exportaciones"
+author: aymericzip
+---
+
+# Paquete @intlayer/babel
+
+El paquete `@intlayer/babel` proporciona un conjunto de plugins de Babel especializados para Intlayer. Estos plugins cubren todo el ciclo de compilación: extracción de declaraciones de contenido, reescritura de llamadas a `useIntlayer` / `getIntlayer` a importaciones de diccionarios optimizadas, depuración de campos no utilizados y minificación de nombres de campos.
+
+## Instalación
+
+```bash
+npm install @intlayer/babel
+```
+
+## Exportaciones
+
+Importar:
+
+```ts
+import { ... } from "@intlayer/babel";
+```
+
+---
+
+### Plugins
+
+| Función / Clase                | Descripción                                                                                                                                                                                                              |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `intlayerExtractBabelPlugin`   | Plugin de Babel que extrae contenido traducible de archivos fuente e inyecta los hooks `useIntlayer` / `getIntlayer` automáticamente. Diseñado para su uso con Next.js y herramientas de compilación basadas en Babel.   |
+| `intlayerOptimizeBabelPlugin`  | Plugin de Babel que transforma las llamadas `useIntlayer` y `getIntlayer` y reescribe sus importaciones a importaciones de diccionarios JSON optimizadas (estáticas, dinámicas o a través de fetch).                     |
+| `intlayerPurgeBabelPlugin`     | Plugin de Babel que analiza archivos fuente y reescribe archivos JSON de diccionarios compilados para eliminar campos no utilizados (`build.purge`) o renombrarlos a alias cortos (`build.minify`).                      |
+| `intlayerMinifyBabelPlugin`    | Plugin de Babel que reescribe archivos fuente para usar los alias de campos cortos asignados durante la fase de minificación (por ejemplo, `content.title` ← `content.a`). Depende de `intlayerPurgeBabelPlugin`.        |
+| `makeFieldRenameBabelPlugin`   | Función de fábrica que produce un plugin de Babel para renombrar los accesos a campos de contenido de diccionarios en archivos fuente de acuerdo con la `dictionaryKeyToFieldRenameMap` completada en el `PruneContext`. |
+| `makeUsageAnalyzerBabelPlugin` | Función de fábrica que produce un plugin de Babel para analizar el uso de `useIntlayer` / `getIntlayer` en el código fuente y acumular datos de uso de campos en el `PruneContext` compartido.                           |
+| `getSharedPruneContext`        | Función de ayuda que devuelve el objeto `PruneContext` compartido para el directorio base especificado, o `null` si aún no se ha inicializado.                                                                           |
+
+---
+
+### Utilidades de configuración del plugin
+
+| Función                    | Descripción                                                                                                                                                |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getExtractPluginOptions`  | Carga la configuración de Intlayer y devuelve `ExtractPluginOptions` listas para su uso con `intlayerExtractBabelPlugin`.                                  |
+| `getOptimizePluginOptions` | Carga la configuración de Intlayer y los diccionarios compilados, y devuelve `OptimizePluginOptions` listas para su uso con `intlayerOptimizeBabelPlugin`. |
+| `getPurgePluginOptions`    | Carga la configuración de Intlayer y devuelve `PurgePluginOptions` listas para su uso con `intlayerPurgeBabelPlugin`.                                      |
+| `getMinifyPluginOptions`   | Carga la configuración de Intlayer y devuelve `MinifyPluginOptions` listas para su uso con `intlayerMinifyBabelPlugin`.                                    |
+
+---
+
+### Tipos
+
+| Tipo                    | Descripción                                                                                                                                       |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CompilerMode`          | Modo de compilador: `'dev'` para desarrollo con soporte HMR, o `'build'` para compilaciones de producción.                                        |
+| `ExtractPluginOptions`  | Opciones para `intlayerExtractBabelPlugin`: lista de archivos, configuración, callback `onExtract`, etc.                                          |
+| `ExtractResult`         | Resultado de la extracción: clave de diccionario, ruta del archivo, contenido y idioma.                                                           |
+| `OptimizePluginOptions` | Opciones para `intlayerOptimizeBabelPlugin`: rutas de diccionarios, modo de importación, mapa de modos por diccionario, etc.                      |
+| `PurgePluginOptions`    | Opciones para `intlayerPurgeBabelPlugin`: directorio base, indicadores de depuración/minificación/optimización, lista de archivos de componentes. |
+| `MinifyPluginOptions`   | Opciones para `intlayerMinifyBabelPlugin`: directorio base, indicadores de minificación/optimización/editorEnabled.                               |
+| `PruneContext`          | Estado compartido entre los plugins de análisis y depuración: mapas de uso de campos, mapas de renombrado, etc.                                   |
+| `DictionaryFieldUsage`  | Resultado del uso de campos para un solo diccionario: `Set<string>` o `'all'` cuando el análisis estático no es concluyente.                      |
+| `NestedRenameEntry`     | Nodo en el árbol de renombrado: el `shortName` y el mapa de hijos.                                                                                |
+| `NestedRenameMap`       | Un nivel en el árbol de renombrado: `Map<string, NestedRenameEntry>`.                                                                             |
+| `CompatCallerConfig`    | Configuración para un analizador de uso compatible para paquetes compat-adapter (nombre de la llamada y opciones de procesamiento).               |
+| `ScriptBlock`           | Bloque de script extraído de un tệp SFC (Vue o Svelte): contenido, desplazamiento de inicio y desplazamiento de final.                            |
+
+---
+
+### Funciones utilitarias
+
+| Función                           | Description                                                                                                                                                                                   |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `generateShortFieldName`          | Convierte un entero (empezando desde cero) en un identificador alfabético corto: `0` → `'a'`, `25` → `'z'`, `26` → `'aa'`, etc.                                                               |
+| `buildNestedRenameMapFromContent` | Construye recursivamente una `NestedRenameMap` a partir del valor de contenido de un diccionario compilado, respetando las estructuras de nodos de Intlayer (translation, enumeration, etc.). |
+| `createPruneContext`              | Crea un nuevo objeto `PruneContext` vacío inicializado con los valores predeterminados.                                                                                                       |
+| `extractScriptBlocks`             | Extrae bloques `<script>` de archivos SFC (Vue / Svelte) para un análisis Babel posterior.                                                                                                    |
+| `BABEL_PARSER_OPTIONS`            | Constante que representa las opciones del parser de Babel que cubren los frameworks admitidos (React/Vue/Svelte/Angular/...).                                                                 |
+| `INTLAYER_CALLER_NAMES`           | Lista constante de nombres de llamada originales de Intlayer: `['useIntlayer', 'getIntlayer']`.                                                                                               |
+
+---
+
+## Ejemplo de uso
+
+```js
+// babel.config.js
+const {
+  intlayerExtractBabelPlugin,
+  intlayerPurgeBabelPlugin,
+  intlayerMinifyBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getPurgePluginOptions,
+  getMinifyPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
+    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+> **Nota:** El plugin `intlayerPurgeBabelPlugin` debe declararse **antes** de `intlayerMinifyBabelPlugin`, porque este último lee el mapa de renombrado creado por el primero. Además, ambos deben estar precedidos por `intlayerOptimizeBabelPlugin` para que este pueda ver las claves del diccionario antes de que se reescriban las llamadas a `useIntlayer`.

package/docs/es/packages/vite-intlayer/intlayerCompiler.md

@@ -0,0 +1,120 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: Documentación del plugin Vite intlayerCompiler | vite-intlayer
+description: Plugin de Vite que extrae declaraciones de contenido de Intlayer en línea de los archivos de componentes y las escribe en archivos JSON de diccionario en el momento de la compilación/transformación.
+keywords:
+  - intlayerCompiler
+  - vite
+  - plugin
+  - compilador
+  - contenido
+  - diccionario
+  - internacionalización
+  - i18n
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerCompiler
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Integrado en intlayer(); inicialización de doc"
+author: aymericzip
+---
+
+# intlayerCompiler
+
+`intlayerCompiler` es un plugin de Vite que escanea los archivos de código fuente de los componentes en busca de **declaraciones de contenido inline de Intlayer** — contenido definido directamente dentro de un componente en lugar de en un archivo `.content.ts` separado — y las escribe en archivos JSON de diccionario durante la fase de transformación.
+
+> **Desde Intlayer v9**, `intlayerCompiler` se incluye automáticamente dentro del plugin principal [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/vite-intlayer/intlayer.md) cuando tanto `compiler.enabled` es `true` como `compiler.output` están configurados en su configuración de Intlayer. Solo necesita registrarlo por separado cuando desee tener un control total sobre la configuración específica del compilador.
+
+## Uso
+
+### Como parte de `intlayer()` (recomendado, v9+)
+
+Habilite el compilador a través de su configuración de Intlayer:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  compiler: {
+    enabled: true,
+    output: "./src/dictionaries", // donde se escriben los diccionarios extraídos
+  },
+});
+```
+
+Luego use el plugin estándar sin registro adicional:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+### Autónomo (cuando sea necesario)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayerCompiler()],
+});
+```
+
+## Opciones
+
+```ts
+import type { IntlayerCompilerOptions } from "vite-intlayer";
+```
+
+| Opción           | Tipo                      | Descripción                                                                                                             |
+| ---------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `configOptions`  | `GetConfigurationOptions` | Anulaciones de configuración de Intlayer reenviadas a `getConfiguration()`.                                             |
+| `compilerConfig` | `Partial<CompilerConfig>` | Anulaciones para la sección de configuración específica del compilador (por ejemplo, `enabled`, `output`, `filesList`). |
+
+### Ejemplo
+
+```ts
+intlayerCompiler({
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+  compilerConfig: { enabled: true, output: "./src/dictionaries" },
+});
+```
+
+## Cómo funciona
+
+### Fase de transformación
+
+Para cada archivo fuente que coincida con `compiler.filesList`, el plugin del compilador:
+
+1. Pasa el contenido del archivo a través de `extractContent` de `@intlayer/babel`.
+2. Llama a `onExtract` para cada declaración encontrada, lo que escribe el JSON del diccionario resultante en `compiler.output`.
+3. Devuelve el código fuente transformado con las declaraciones en línea reemplazadas por llamadas estándar `useIntlayer('key')` / `getIntlayer('key')`.
+
+Tipos de archivos admitidos: `.ts`, `.tsx`, `.js`, `.jsx`, `.vue`, `.svelte`, `.astro`.
+
+### HMR (Hot Module Replacement)
+
+Cuando se guarda un archivo de componente en modo de desarrollo, el compilador:
+
+1. Detecta el cambio de archivo a través del hook `handleHotUpdate` de Vite.
+2. Vuelve a extraer el contenido del archivo actualizado.
+3. Escribe el JSON del diccionario actualizado.
+4. Activa una recarga completa de la página (`server.ws.send({ type: 'full-reload' })`).
+
+Un retraso (debounce) de 500 ms evita que la propia escritura del diccionario (que también activa un evento de cambio de archivo) cause un bucle de re-extracción infinito.
+
+### Deduplicación
+
+`intlayerCompiler` utiliza el mismo mecanismo de deduplicación `createPrimaryInstanceGuard` que los otros plugins incluidos. Cuando están presentes tanto `intlayer()` (que incluye el compilador) como una llamada manual a `intlayerCompiler()`, solo se ejecuta la primera instancia registrada; no se escribe ningún diccionario dos veces.

package/docs/es/packages/vite-intlayer/intlayerMinify.md

@@ -0,0 +1,92 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: Documentación del plugin Vite intlayerMinify | vite-intlayer
+description: Plugin de Vite que minifica los archivos JSON de diccionarios Intlayer compilados y, opcionalmente, ofusca los nombres de los campos de contenido para reducir el tamaño del bundle.
+keywords:
+  - intlayerMinify
+  - vite
+  - plugin
+  - minificar
+  - tamaño del bundle
+  - diccionario
+  - internacionalización
+  - i18n
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerMinify
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Inicialización de doc"
+author: aymericzip
+---
+
+# intlayerMinify
+
+`intlayerMinify` es un plugin de Vite que minifica archivos JSON de diccionarios compilados durante una compilación de producción. Elimina todos los espacios en blanco innecesarios y, cuando se combina con `intlayerPrune`, opcionalmente renombra los nombres de los campos de contenido a alias alfabéticos cortos (`a`, `b`, `c`, ...) para reducir aún más el tamaño del bundle.
+
+> El plugin ya está incluido y configurado automáticamente cuando utiliza [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/vite-intlayer/intlayer.md). Solo necesita registrarlo manualmente si está componiendo la pila de plugins usted mismo.
+
+## Uso
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerMinify, intlayerPrune } from "vite-intlayer";
+import { createPruneContext } from "@intlayer/babel";
+
+const pruneContext = createPruneContext();
+
+export default defineConfig({
+  plugins: [
+    intlayerPrune(intlayerConfig, pruneContext),
+    intlayerMinify(intlayerConfig, pruneContext),
+  ],
+});
+```
+
+## Condiciones de activación
+
+`intlayerMinify` está activo **solo** cuando se cumplen las tres condiciones siguientes:
+
+1. El comando de Vite es `build` (no `serve` / dev).
+2. `build.optimize` es `true` (o `undefined`, que por defecto es `true` para compilaciones).
+3. `build.minify` es `true` en su configuración de Intlayer.
+
+Se **desactiva** automáticamente cuando `editor.enabled` es `true` porque el editor necesita el contenido del diccionario completo y legible por humanos.
+
+## Qué se minifica
+
+El plugin apunta a dos ubicaciones de diccionarios (según lo resuelto a partir de `intlayer.system`):
+
+- `dictionariesDir` — diccionarios estáticos para todos los idiomas (por ejemplo, `.intlayer/dictionaries/*.json`)
+- `dynamicDictionariesDir` — diccionarios dinámicos por idioma
+
+> Los diccionarios en modo fetch (`fetchDictionariesDir`) **nunca** se minifican porque se sirven desde una API remota en tiempo de ejecución utilizando sus nombres de campo originales. Cambiar el nombre de los campos crearía una discrepancia entre la respuesta del servidor y los accesos a propiedades en el lado del cliente.
+
+## Ofuscación de nombres de campo (minificación de propiedades)
+
+Cuando `intlayerPrune` ha analizado el código fuente y ha llenado `pruneContext.dictionaryKeyToFieldRenameMap`, `intlayerMinify` también cambia el nombre de los campos de contenido a alias cortos. Por ejemplo:
+
+```json
+// antes
+{ "key": "myDict", "content": { "title": "Hello", "description": "World" } }
+
+// después (con ofuscación)
+{ "key": "myDict", "content": { "a": "Hello", "b": "World" } }
+```
+
+Los accesos a propiedades de archivos fuente correspondientes se renombran mediante el paso de Babel dentro de `intlayerOptimize`, por lo que el comportamiento en tiempo de ejecución no cambia.
+
+Los campos internos de Intlayer (`nodeType`, `translation`, etc.) nunca se renombran.
+
+## Dicionarios de casos extremos (Edge cases)
+
+Los diccionarios marcados en `pruneContext.dictionariesWithEdgeCases` (anomalías estructurales detectadas durante la fase de prune) se omiten por completo — ni se minifican ni se ofuscan — para evitar el envío de datos dañados.
+
+## Grupos calificados (colecciones / variantes / registros meta)
+
+Para diccionarios con una matriz `qualifierTypes` (colecciones, variantes y registros meta), el plugin conserva la matriz `qualifierTypes` y el mapa lateral `meta` literalmente. Solo las entradas de `content` tienen sus nombres de campo ofuscados. Las claves compuestas (utilizadas para la coincidencia de selectores en tiempo de ejecución) nunca se tocan.

package/docs/es/packages/vite-intlayer/intlayerProxy.md

@@ -0,0 +1,172 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: Documentación del plugin Vite intlayerProxy | vite-intlayer
+description: Middleware de enrutamiento de idiomas para los servidores dev/preview de Vite y SSR de producción. Maneja la detección de idioma, redireccionamientos de URL y reescrituras internas.
+keywords:
+  - intlayerProxy
+  - vite
+  - plugin
+  - middleware
+  - idioma
+  - enrutamiento
+  - internacionalización
+  - i18n
+  - SSR
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerProxy
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Se fusionó configOptions en un solo objeto de opciones; proxy integrado en intlayer()"
+author: aymericzip
+---
+
+# intlayerProxy
+
+`intlayerProxy` es un plugin de Vite que registra un middleware de enrutamiento de idiomas para **todos los entornos**: servidor de desarrollo, servidor de vista previa y SSR de producción (Nitro / TanStack Start).
+
+> **Desde Intlayer v9**, `intlayerProxy` se incluye automáticamente dentro del plugin principal [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/vite-intlayer/intlayer.md) y está habilitado por defecto mediante `routing.enableProxy: true`. Solo necesita registrarlo por separado si requiere un control de nivel inferior o si lo está utilizando fuera de la configuración estándar de `intlayer()`.
+
+## Uso
+
+### Como parte de `intlayer()` (recomendado, v9+)
+
+Pase las opciones de `proxy` al plugin principal en lugar de registrar `intlayerProxy` por separado:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
+});
+```
+
+### Autónomo (cuando sea necesario)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+## Opciones
+
+```ts
+import type { IntlayerProxyPluginOptions } from "vite-intlayer";
+```
+
+Todas las opciones son opcionales y se pasan como un único objeto:
+
+| Opción          | Tipo                                | Descripción                                                                                                                                                                |
+| --------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ignore`        | `(req: IncomingMessage) => boolean` | Predicado que excluye solicitudes del enrutamiento de idiomas. Devuelva `true` para omitir una solicitud (por ejemplo, rutas de API, controles de salud).                  |
+| `configOptions` | `GetConfigurationOptions`           | Anulaciones de configuración de Intlayer reenviadas a `getConfiguration()`. Úselo cuando necesite que el proxy lea un archivo de configuración específico o anule valores. |
+
+### Ejemplo
+
+```ts
+intlayerProxy({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+```
+
+## createIntlayerProxyHandler
+
+`createIntlayerProxyHandler` crea un middleware Node.js `(req, res, next)` independiente del framework que contiene toda la lógica de enrutamiento de idiomas. Es útil en entornos donde la API del plugin de Vite no está disponible (por ejemplo, un servidor Node.js simple o un módulo Nitro personalizado).
+
+```ts
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+const handler = createIntlayerProxyHandler({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+
+// Express / Connect
+app.use(handler);
+```
+
+### SSR de producción (TanStack Start / Nitro a través de h3)
+
+```ts
+// server/middleware/intlayerProxy.ts
+import { fromNodeMiddleware } from "h3";
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+export default fromNodeMiddleware(
+  createIntlayerProxyHandler({
+    ignore: (req) => req.url?.startsWith("/api"),
+  })
+);
+```
+
+## Comportamiento de enrutamiento
+
+El middleware refleja la lógica de enrutamiento del middleware de `next-intlayer` y es compatible con todos los modos de enrutamiento de Intlayer.
+
+### Modos de enrutamiento
+
+| Modo            | URL visible en el navegador | Comportamiento                                                                                                                          |
+| --------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `prefix`        | `/es/about`                 | Por defecto. Prefijo de idioma en la URL. El idioma por defecto redirige a la URL sin prefijo a menos que `prefix-all` esté habilitado. |
+| `prefix-all`    | `/en/about`, `/es/about`    | Todos los idiomas — incluido el por defecto — siempre tienen prefijo.                                                                   |
+| `no-prefix`     | `/about`                    | Sin idioma en la URL. El idioma se almacena únicamente en las cookies; las reescrituras de URL ocurren internamente.                    |
+| `search-params` | `/about?locale=es`          | Idioma pasado como parámetro de consulta. Redirige para agregar/actualizar el parámetro `locale` cuando falta o está obsoleto.          |
+
+### Prioridad de detección
+
+1. Prefijo de ruta URL (por ejemplo, `/es/about` → `es`).
+2. Valor de cookie / localStorage (`intlayer-locale`).
+3. Cabecera `Accept-Language`.
+4. `defaultLocale` de la configuración.
+
+### Omisión automática
+
+El middleware siempre deja pasar estas solicitudes directamente sin manejo de idioma:
+
+- Solicitudes que coinciden con el predicado `ignore`.
+- `/node_modules/**`
+- `/@**` – Componentes internos de Vite (`@vite/`, `@fs/`, `@id/`, etc.).
+- `/_**` – Componentes internos del servidor (`__vite_ping`, `__manifest`, etc.).
+- Solicitudes cuya ruta termina con una extensión de archivo (activos estáticos). Si hay un prefijo de idioma presente en la ruta de un activo estático (por ejemplo, `/es/logo.png`), se elimina para que el archivo se pueda servir correctamente.
+
+### Enrutamiento de dominio
+
+Cuando `routing.domains` está configurado en su configuración de Intlayer, el middleware maneja el enrutamiento de idiomas entre dominios:
+
+- Una solicitud para `/zh/about` en `intlayer.org` se redirige a `https://intlayer.zh/about` cuando `domains.zh = "intlayer.zh"`.
+- Una solicitud a `intlayer.zh/about` se reescribe internamente a `/zh/about` para que se complete el parámetro de ruta `[locale]`.
+
+### Protección contra bucles de redirección
+
+El middleware realiza un seguimiento de los recuentos de redireccionamientos por par `originalUrl → newUrl` dentro de una ventana deslizante de 2 segundos. Más de 10 redireccionamientos dentro de esa ventana devuelven una respuesta `500` con un error descriptivo en lugar de entrar en un bucle infinito.
+
+## Nitro / SSR de producción (inyección automática, v9+)
+
+Cuando se usa `intlayerProxy` como plugin de Vite, lleva una propiedad `.nitro`. El plugin de compilación `nitro/vite` lee esta propiedad y la agrega a `nitroConfig.modules`, por lo que `intlayerNitroHandler` se registra como middleware del servidor Nitro automáticamente; no se necesita configuración manual para el SSR de producción.
+
+El controlador Nitro utiliza el modelo de eventos de la API Web Fetch de h3 v2 (no `fromNodeMiddleware`), por lo que es compatible con todos los preajustes de Nitro: Node, Bun, Deno, entornos de ejecución edge.
+
+## Alias obsoletos
+
+| Exportación obsoleta       | Reemplazo       |
+| -------------------------- | --------------- |
+| `intlayerMiddleware`       | `intlayerProxy` |
+| `intLayerMiddlewarePlugin` | `intlayerProxy` |