@intlayer/docs 9.0.0-canary.4 → 9.0.0-canary.5

package/docs/es/autoFill.md

@@ -28,6 +28,53 @@ history:
 author: aymericzip
 ---
 
+# Rellenar Traducciones de Archivos de Declaración de Contenido
+
+**Rellenar automáticamente archivos de declaración de contenido** en tu CI es una forma de acelerar tu flujo de trabajo de desarrollo.
+
+## Entendiendo el comportamiento
+
+El comando `fill` incluye dos modos:
+
+- **Complete**: Completa automáticamente todo el contenido faltante para cada locale y edita el archivo actual, u otro archivo si se especifica. Es decir, el modo complete omitirá la traducción del contenido existente, si ya está traducido.
+- **Review**: Completa automáticamente **todo** el contenido para cada locale y genera para un archivo específico, u otro archivo si se especifica.
+
+El comando will procesará todos tus archivos de declaración de contenido por locale. Es decir, no procesará tu contenido remoto del CMS. El CMS incluye su propia gestión de traducciones.
+Si utilizas plugins como `@intlayer/sync-json-plugin`, Intlayer transformará los archivos JSON en archivos de declaración de contenido por locale. Es decir, serán procesados por el comando `fill`.
+
+Los archivos generados recientemente incluyen una instrucción `filled` como metadatos del diccionario. Esta instrucción será utilizada por Intlayer para saber si el archivo ha sido rellenado automáticamente o no, y omitirá este archivo de ser traducido nuevamente si está presente.
+
+Intlayer también considerará la siguiente instrucción para rellenado automático:
+
+- De tu `.content.{ts|js|json}` → instrucción `fill`
+- De tu archivo de configuración `.intlayer.config.ts` → instrucción `dictionary.fill`
+- Se establecerá en `true` por defecto de lo contrario
+
+Para archivos de declaración de contenido por locale, la instrucción `true` será reemplazada por `./{{fileName}}.fill.content.json`. Esto es porque un archivo de declaración de contenido por locale no puede recibir contenido localizado adicional. Por lo tanto, generará un nuevo archivo para no sobrescribir el archivo existente.
+
+## Comportamiento Predeterminado
+
+Por defecto, `fill` está establecido en `true` globalmente, lo que significa que Intlayer rellenará automáticamente todos los archivos de contenido y editará el archivo en sí. Este comportamiento se puede personalizar de varias formas:
+
+### Opciones de Configuración Global
+
+1. **`fill: true` (default)** - Rellenar automáticamente todos los locales y editar el archivo actual
+2. **`fill: false`** - Desactivar el relleno automático para este archivo de contenido
+3. **`fill: "./relative/path/to/file"`** - Crear/actualizar el archivo especificado sin editar el actual señalando una ruta relativa resuelta basada en la ubicación del archivo actual
+4. **`fill: "/absolute/path/to/file"`** - Crear/actualizar el archivo especificado sin editar el actual señalando una ruta relativa resuelta basada en la ubicación del directorio base (campo `baseDir` en el archivo de configuración `.intlayer.config.ts`)
+5. **`fill: "C:\\absolute\path\to\file"`** - Crear/actualizar el archivo especificado sin editar el actual señalando una ruta absoluta resuelta basada en tu sistema operativo
+6. **`fill: { [key in Locales]?: string }`** - Crear/actualizar el archivo especificado para cada locale
+
+### Cambios de comportamiento en v7
+
+En v7, el comportamiento del comando `fill` ha sido actualizado:
+
+- **`fill: true`** - Reescribe el archivo actual con contenido completado para todos los locales
+- **`fill: "path/to/file"`** - Completa el archivo especificado sin modificar el archivo actual
+- **`fill: false`** - Desactiva la completación automática completamente
+
+Cuando se utiliza una opción de ruta para escribir en otro archivo, el mecanismo de completación funciona a través de una relación _maestro-esclavo_ entre archivos de declaración de contenido. El archivo principal (maestro) sirve como la fuente de verdad, y cuando se actualiza, Intlayer aplicará automáticamente esos cambios a los archivos de declaración completados (derivados) especificados por la ruta.
+
 # Traducciones de Archivos de Declaración de Contenido con Relleno Automático
 
 **Los archivos de declaración de contenido con relleno automático** son una forma de acelerar tu flujo de trabajo de desarrollo.
@@ -88,6 +135,40 @@ Intlayer generará automáticamente el archivo de declaración derivado en `src/
 
 Después, ambos archivos de declaración se fusionarán en un único diccionario, accesible mediante el hook estándar `useIntlayer("example")` (react) / composable (vue).
 
+## Configuración Global
+
+Puedes configurar la configuración global de auto fill en el archivo `intlayer.config.ts`.
+
+```ts fileName="intlayer.config.ts"
+import { type IntlayerConfig, Locales } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+  },
+  dictionary: {
+    // Auto-generar traducciones faltantes para todos los diccionarios
+    fill: "./{{fileName}}Filled.content.ts",
+    //
+    // fill: "/messages/{{locale}}/{{key}}/{{fileName}}.content.json",
+    //
+    // fill: true, // auto-generar traducciones faltantes para todos los diccionarios como usar "./{{fileName}}.content.json"
+    //
+    // fill: {
+    //   en: "./{{fileName}}.en.content.json",
+    //   fr: "./{{fileName}}.fr.content.json",
+    //   es: "./{{fileName}}.es.content.json",
+    // },
+  },
+};
+
+export default config;
+```
+
+Aún puedes ajustar finamente por diccionario usando el campo `fill` en archivos de contenido. Intlayer primero considerará la configuración por diccionario y luego recurrirá a la configuración global.
+
 ## Formato del Archivo Rellenado Automáticamente
 
 El formato recomendado para los archivos de declaración autocompletados es **JSON**, lo que ayuda a evitar restricciones de formato. Sin embargo, Intlayer también soporta `.ts`, `.js`, `.mjs`, `.cjs` y otros formatos.

package/docs/es/benchmark/solid.md

@@ -118,6 +118,28 @@ Comparamos **quatro estrategias de carga**:
 - **Scoped static**: Mantiene el código organizado (separación lógica) sin solicitudes de red adicionales complejas.
 - **Scoped dynamic**: El mejor enfoque para el _code splitting_ y el rendimiento. Minimiza la memoria cargando solo lo que la vista actual y el idioma activo necesitan.
 
+### Lo que medí:
+
+Ejecuté la misma aplicación multilingüe en un navegador real para cada stack, luego anoté lo que realmente aparecía en la red y cuánto tiempo tomaba. Los tamaños se reportan **después de la compresión web normal**, porque eso es más cercano a lo que la gente descarga que los recuentos de código fuente sin procesar.
+
+- **Tamaño de la biblioteca de internacionalización**: Después de agrupar, tree-shaking y minificación, el tamaño de la biblioteca i18n es el tamaño del código de providers + hooks/primitives en un componente vacío. No incluye la carga de archivos de traducción. Responde qué tan costosa es la biblioteca antes de que tu contenido entre en juego.
+
+- **JavaScript por página**: Para cada ruta de benchmark, cuánto script descarga el navegador en esa visita, promediado en las páginas de la suite (y en idiomas donde el informe los agrupa). Las páginas pesadas son páginas lentas.
+
+- **Fuga de otros idiomas**: Es el contenido de la misma página pero en otro idioma que se cargaría por error en la página auditada. Este contenido es innecesario y debe evitarse. (por ejemplo, contenido de la página `/fr/about` en el bundle de la página `/en/about`)
+
+- **Fuga de otras rutas**: La misma idea para **otras pantallas** en la aplicación: si su contenido viene junto cuando solo abriste una página. (por ejemplo, contenido de la página `/en/about` en el bundle de la página `/en/contact`). Una puntuación alta sugiere un splitting débil o bundles demasiado amplios.
+
+- **Tamaño promedio del bundle de componentes**: Las piezas comunes de la interfaz de usuario se miden **una a la vez** en lugar de esconderse dentro de un número de aplicación gigante. Muestra si la internacionalización infla silenciosamente los componentes cotidianos. Por ejemplo, si tu componente se vuelve a renderizar, cargará todos esos datos de la memoria. Adjuntar un JSON gigante a cualquier componente es como conectar un gran almacén de datos no utilizados que ralentizará el rendimiento de tus componentes.
+
+- **Responsividad del cambio de idioma**: Cambio el idioma usando el control de la aplicación y mido cuánto tiempo tarda hasta que la página se haya cambiado claramente, lo que un visitante notaría, no un micro-paso de laboratorio.
+
+- **Trabajo de renderización después de un cambio de idioma**: Un seguimiento más estrecho: cuánto esfuerzo requirió la interfaz para repintarse con el nuevo idioma una vez que el cambio está en vuelo. Útil cuando el tiempo "sentido" y el costo del framework divergen.
+
+- **Tiempo de carga inicial de la página**: Desde la navegación hasta que el navegador considera la página completamente cargada para los escenarios que probé. Bueno para comparar inicios en frío.
+
+- **Tiempo de hidratación**: Cuando la aplicación lo expone, cuánto tiempo pasa el cliente transformando HTML del servidor en algo que realmente puedas hacer clic. Un guion en las tablas significa que esa implementación no proporcionó una figura de hidratación confiable en este benchmark.
+
 ## Estrellas de GitHub
 
 Las estrellas de GitHub son un fuerte indicador de la popularidad de un proyecto, la confianza de la comunidad y la relevancia a largo plazo. Si bien no son una medida directa de la calidad técnica, reflejan cuántos desarrolladores encuentran útil el proyecto, siguen su progreso y es probable que lo adopten. Para estimar el valor de un proyecto, las estrellas ayudan a comparar la tracción entre alternativas y brindan información sobre el crecimiento del ecosistema.

package/docs/es/benchmark/svelte.md

@@ -116,6 +116,28 @@ Comparamos **quatro estrategias de carga**:
 - **Scoped static**: Mantiene el código organizado (separación lógica) sin solicitudes de red adicionales complejas.
 - **Scoped dynamic**: El mejor enfoque para el _code splitting_ y el rendimiento. Minimiza la memoria cargando solo lo que la vista actual y el idioma activo necesitan.
 
+### Lo que medí:
+
+Ejecuté la misma aplicación multilingüe en un navegador real para cada stack, luego anoté lo que realmente apareció en la red y cuánto tiempo tomó. Los tamaños se reportan **después de la compresión web normal**, porque eso es más cercano a lo que las personas descargan que los recuentos de código fuente sin procesar.
+
+- **Tamaño de la biblioteca de internacionalización**: Después del bundling, tree-shaking y minificación, el tamaño de la biblioteca i18n es el tamaño del código de providers + stores en un componente vacío. No incluye la carga de archivos de traducción. Responde qué tan costosa es la biblioteca antes de que tu contenido entre en juego.
+
+- **JavaScript por página**: Para cada ruta de benchmark, cuánto script descarga el navegador en esa visita, promediado en todas las páginas de la suite (y en locales donde el reporte las agrupa). Las páginas pesadas son páginas lentas.
+
+- **Fuga de otros idiomas**: Es el contenido de la misma página pero en otro idioma que se cargaría por error en la página auditada. Este contenido es innecesario y debe evitarse. (p. ej., contenido de la página `/fr/about` en el bundle de la página `/en/about`)
+
+- **Fuga de otras rutas**: La misma idea para **otras pantallas** en la aplicación: si su contenido se lleva cuando solo abriste una página. (p. ej., contenido de la página `/en/about` en el bundle de la página `/en/contact`). Una puntuación alta sugiere splitting débil o bundles demasiado amplios.
+
+- **Tamaño promedio del bundle de componentes**: Las piezas comunes de la interfaz de usuario se miden **una a la vez** en lugar de ocultarse dentro de un número de aplicación gigante. Muestra si la internacionalización infla silenciosamente los componentes cotidianos. Por ejemplo, si tu componente se reenderiza, cargará todos esos datos de la memoria. Adjuntar un JSON gigante a cualquier componente es como conectar un almacén grande de datos no utilizados que ralentizará el rendimiento de tus componentes.
+
+- **Capacidad de respuesta del cambio de idioma**: Cambio el idioma usando el control de la aplicación y mido cuánto tarda hasta que la página se haya cambiado claramente, lo que un visitante notaría, no un micro-paso de laboratorio.
+
+- **Trabajo de renderizado después de un cambio de idioma**: Un seguimiento más estrecho: cuánto esfuerzo tomó la interfaz para repintarse en el nuevo idioma una vez que el cambio está en vuelo. Útil cuando el tiempo "sentido" y el costo del framework divergen.
+
+- **Tiempo de carga inicial de la página**: Desde la navegación hasta que el navegador considere la página completamente cargada para los escenarios que probé. Bueno para comparar arranques en frío.
+
+- **Tiempo de hidratación**: Cuando la aplicación la expone, cuánto tiempo gasta el cliente convirtiendo HTML del servidor en algo que puedas hacer clic. Un guión en las tablas significa que esa implementación no proporcionó una cifra de hidratación confiable en este benchmark.
+
 ## Estrellas de GitHub
 
 Las estrellas de GitHub son un fuerte indicador de la popularidad de un proyecto, la confianza de la comunidad y la relevancia a largo plazo. Si bien no son una medida directa de la calidad técnica, reflejan cuántos desarrolladores encuentran útil el proyecto, siguen su progreso y es probable que lo adopten. Para estimar el valor de un proyecto, las estrellas ayudan a comparar la tracción entre alternativas y brindan información sobre el crecimiento del ecosistema.

package/docs/es/benchmark/tanstack.md

@@ -124,6 +124,28 @@ Comparamos **cuatro estrategias de carga**:
 - **Scoped static**: Mantiene el código organizado (separación lógica) sin peticiones de red adicionales complejas.
 - **Scoped dynamic**: El mejor enfoque para el _code splitting_ y el rendimiento. Minimiza el uso de memoria cargando solo lo que la vista actual y el idioma activo necesitan.
 
+### Qué medí:
+
+Ejecuté la misma aplicación multilingüe en un navegador real para cada stack, luego anoté lo que realmente aparecía en la red y cuánto tiempo tardaba. Los tamaños se informan **después de la compresión web normal**, porque es más cercano a lo que las personas descargan que los recuentos de fuentes sin procesar.
+
+- **Tamaño de la biblioteca de internacionalización**: Después de agrupar, agitar árboles y minificar, el tamaño de la biblioteca i18n es el tamaño de los proveedores (p. ej. `NextIntlClientProvider`) + código de hooks (p. ej. `useTranslations`) en un componente vacío. No incluye la carga de archivos de traducción. Responde cuán costosa es la biblioteca antes de que tu contenido entre en juego.
+
+- **JavaScript por página**: Para cada ruta de punto de referencia, cuánto script descarga el navegador en esa visita, promediado en las páginas del conjunto (y en locales donde el informe los agrupa). Las páginas pesadas son páginas lentas.
+
+- **Fuga de otros idiomas**: Es el contenido de la misma página pero en otro idioma que se cargaría por error en la página auditada. Este contenido es innecesario y debe evitarse. (p. ej. contenido de página `/fr/about` en paquete de página `/en/about`)
+
+- **Fuga de otras rutas**: La misma idea para **otras pantallas** en la aplicación: si su contenido viene junto cuando solo abriste una página. (p. ej. contenido de página `/en/about` en paquete de página `/en/contact`). Una puntuación alta sugiere un divisor débil o paquetes demasiado amplios.
+
+- **Tamaño promedio del paquete de componentes**: Las piezas comunes de la interfaz se miden **una a la vez** en lugar de ocultarse dentro de un número de aplicación gigante. Muestra si la internacionalización infla silenciosamente los componentes cotidianos. Por ejemplo, si tu componente se redibuja, cargará todos esos datos de la memoria. Adjuntar un JSON gigante a cualquier componente es como conectar un gran almacén de datos no utilizados que ralentizará el rendimiento de tus componentes.
+
+- **Capacidad de respuesta del cambio de idioma**: Cambio el idioma usando el control de la aplicación y mido cuánto tiempo tarda hasta que la página se haya cambiado claramente, lo que un visitante notaría, no un micro-paso de laboratorio.
+
+- **Trabajo de renderizado después de un cambio de idioma**: Un seguimiento más estrecho: cuánto esfuerzo tomó la interfaz para repintarse para el nuevo idioma una vez que el cambio está en vuelo. Útil cuando el tiempo "percibido" y el costo del framework divergen.
+
+- **Tiempo de carga inicial de la página**: Desde la navegación hasta que el navegador considera la página completamente cargada para los escenarios que probé. Bueno para comparar inicios en frío.
+
+- **Tiempo de hidratación**: Cuando la aplicación lo expone, cuánto tiempo pasa el cliente convirtiendo HTML del servidor en algo en lo que realmente puedas hacer clic. Un guión en las tablas significa que esa implementación no proporcionó una cifra de hidratación confiable en este punto de referencia.
+
 ## Estrellas de GitHub
 
 Las estrellas de GitHub son un fuerte indicador de la popularidad de un proyecto, la confianza de la comunidad y la relevancia a largo plazo. Si bien no son una medida directa de la calidad técnica, reflejan cuántos desarrolladores encuentran útil el proyecto, siguen su progreso y es probable que lo adopten. Para estimar el valor de un proyecto, las estrellas ayudan a comparar la tracción entre alternativas y brindan información sobre el crecimiento del ecosistema.

package/docs/es/cli/ci.md

@@ -140,6 +140,28 @@ steps:
     run: npx intlayer ci fill
 ```
 
+## Acciones de GitHub generadas automáticamente
+
+Cuando ejecutas `intlayer init`, Intlayer detecta tu gestor de paquetes (npm, yarn, pnpm, o bun) y genera automáticamente dos flujos de trabajo de GitHub Actions en `.github/workflows/`, con comandos que coinciden con ese gestor de paquetes:
+
+- **`intlayer-fill.yml`** — En cada pull request, construye los diccionarios y ejecuta `intlayer fill --git-diff --mode complete` para generar traducciones faltantes en los diccionarios modificados, luego confirma el resultado en la rama del PR.
+- **`intlayer-test.yml`** — En cada pull request, construye los diccionarios y ejecuta `intlayer test`, fallando la verificación cuando faltan traducciones en las locales requeridas.
+
+Los archivos de flujo de trabajo existentes nunca se sobrescriben. Para omitir la generación automática por completo, ejecuta:
+
+```bash
+npx intlayer init --no-github-actions
+```
+
+### Proporcionar acceso a IA al flujo de trabajo de relleno
+
+El `intlayer-fill.yml` generado requiere acceso a IA. Hay dos opciones disponibles (configuradas en el bloque `env` del flujo de trabajo):
+
+1. **Tu propia clave de proveedor de IA** — Agrega un secreto `AI_API_KEY` en la configuración de tu repositorio (Settings → Secrets and variables → Actions). El flujo de trabajo la reenvía a través de `--provider`, `--model` y `--api-key`.
+2. **Claves de acceso a Intlayer CMS** — Agrega los secretos `INTLAYER_CLIENT_ID` e `INTLAYER_CLIENT_SECRET` e intégralos en la sección `editor` de tu `intlayer.config`. Las claves de acceso a CMS otorgan acceso a IA a través del backend de Intlayer.
+
+El flujo de trabajo `intlayer-test.yml` no requiere acceso a IA.
+
 ## Manejo de errores
 
 - Si `INTLAYER_PROJECT_CREDENTIALS` no está establecida, el comando saldrá con un error.

package/docs/es/cli/fill.md

@@ -47,6 +47,14 @@ Puntos clave:
 - Preserva las traducciones existentes al no sobrescribirlas.
 - Procesa archivos, fragmentos y locales en paralelo usando un sistema de cola para aumentar la velocidad.
 
+## Puntos clave:
+
+- Divide archivos JSON grandes en chunks para mantenerse dentro de los límites de la ventana de contexto del modelo de IA.
+- Reintenta la traducción si el formato de salida es incorrecto.
+- Incorpora contexto específico de la aplicación y del archivo para una precisión de traducción mejorada.
+- Preserva las traducciones existentes sin sobrescribirlas.
+- Procesa archivos, chunks y locales en paralelo usando un sistema de cola para aumentar la velocidad.
+
 ## Alias:
 
 - `npx intlayer dictionaries fill`

package/docs/es/cli/login.md

@@ -78,42 +78,6 @@ bun x intlayer login --cms-url https://intlayer.org
 
 ### Opciones de configuración
 
-También puedes usar opciones de configuración comunes:
-
-- `--env-file <path>`: Ruta al archivo de entorno
-- `-e, --env <env>`: Entorno de ejecución
-- `--base-dir <dir>`: Directorio base del proyecto
-- `--verbose`: Habilitar salida detallada (por defecto: true)
-- `--prefix <prefix>`: Prefijo para los logs
-
-## Cómo funciona
-
-1. **Inicio de servidor local**: El comando inicia un servidor HTTP local en un puerto aleatorio para recibir las credenciales desde el CMS
-
-Especifica la URL del CMS de Intlayer al que conectarse para la autenticación.
-
-- **Tipo**: `string`
-- **Por defecto**: El valor configurado en `intlayer.config.*` o `https://intlayer.org`
-- **Ejemplo**:
-
-```bash packageManager="npm"
-npx intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="yarn"
-yarn intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="bun"
-bun x intlayer login --cms-url https://intlayer.org
-```
-
-### Opciones de configuración
-
 También puedes usar las opciones de configuración comunes:
 
 - `--env-file <path>`: Ruta al archivo de entorno

package/docs/es/compat/i18n-js.md

@@ -0,0 +1,44 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar de i18n-js a Intlayer"
+description: "Aprende cómo migrar tu aplicación desde i18n-js a Intlayer usando el adaptador de compatibilidad."
+keywords:
+  - i18n-js
+  - intlayer
+  - migración
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - i18n-js
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Inicializar historial"
+author: aymericzip
+---
+
+# Migrar de i18n-js a Intlayer
+
+Hacer la transición desde la biblioteca `i18n-js` a Intlayer es una migración altamente optimizada diseñada para descargar grandes configuraciones de traducciones en el sistema de resolución de archivos estructurados de Intlayer.
+
+## Qué hacer
+
+Ejecuta el siguiente comando de configuración en tu repositorio:
+
+```bash
+npx intlayer init
+```
+
+Con `intlayer.config.ts` preparado, puedes agregar el alias de Intlayer a tu configuración del empaquetador para que cualquier importación de `i18n-js` apunte al paquete de compatibilidad `@intlayer/i18n-js`.
+
+## Qué hace bajo el capó
+
+`i18n-js` accede a namespaces a través de expresiones como `i18n.t('scope.key', {name})` junto con fallbacks de locale y mapeos de plurales específicos.
+
+Bajo el capó:
+
+- **Interpolación:** El adaptador de compatibilidad analiza fácilmente mapeos `%{name}` en tu valor de diccionario de runtime objetivo.
+- **Pluralización:** Reemplaza subclaves `one/other` y las asigna contra los poderosos mecanismos de plurales subyacentes de Intlayer (`Intl.PluralRules`), abstrayendo mapeos manuales.
+- **Locales:** En lugar de cargar cargas de idioma monolíticas en el bootstrap, los diccionarios se sirven de manera óptima según la configuración de contexto actual a través de la configuración nativa de Intlayer.

package/docs/es/compat/i18next.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar de i18next a Intlayer"
+description: "Aprende cómo migrar tu aplicación JavaScript/TypeScript vanilla desde i18next a Intlayer usando el adaptador de compatibilidad."
+keywords:
+  - i18next
+  - vanilla
+  - javascript
+  - typescript
+  - intlayer
+  - migración
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Inicializar historial"
+author: aymericzip
+---
+
+# Migrar de i18next a Intlayer
+
+Para un tutorial detallado paso a paso, por favor consulta nuestro [Guía Completa de Migración de i18next](../migration_from_i18next_to_intlayer.md).
+
+Intlayer replica perfectamente las características de runtime principales de `i18next`. Al utilizar el paquete de compatibilidad, tus aplicaciones Vanilla o módulos internos pueden continuar aprovechando la sintaxis familiar.
+
+## Qué hacer
+
+Para comenzar, inicializa Intlayer en tu proyecto:
+
+```bash
+npx intlayer init
+```
+
+Si estás usando Vite, incluye el plugin de Intlayer para enrutar importaciones a `@intlayer/i18next`:
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { i18nextVitePlugin } from "@intlayer/i18next/plugin";
+
+export default defineConfig({
+  plugins: [i18nextVitePlugin()],
+});
+```
+
+## Qué hace bajo el capó
+
+El `i18nextVitePlugin` asigna importaciones de `i18next` a `@intlayer/i18next`, evitando la inflación del bundle de las inclusiones de archivos JSON.
+
+Bajo el capó:
+
+- **Configuración de instancia:** `createInstance` analiza correctamente y aplica fallbacks de namespace mientras aprovecha el pipeline de compilación de Intlayer para la recuperación de diccionarios.
+- **Interpolación:** Soporte nativo para reemplazos de `{{name}}` y anidamiento `$t(key)` recursivamente.
+- **Contexto y plurales:** Identifica y resuelve formatos de sufijo como `key_male` y `key_one`/`key_other` evaluando contra `Intl.PluralRules` estándar.
+- **Objetos de retorno:** El modo `returnObjects: true` extrae de forma segura árboles de diccionarios de Intlayer.

package/docs/es/compat/index.md

@@ -0,0 +1,51 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Adaptadores de Compatibilidad de Intlayer"
+description: "Migra tu solución i18n existente a Intlayer sin fricciones usando adaptadores de compatibilidad."
+keywords:
+  - compat
+  - migración
+  - internacionalización
+  - i18n
+  - Intlayer
+slugs:
+  - doc
+  - compatibility
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Inicializar historial"
+author: aymericzip
+---
+
+# Adaptadores de Compatibilidad de Intlayer
+
+Migrar una aplicación grande a una nueva biblioteca de internacionalización puede ser desalentador. Para facilitar esta transición, Intlayer proporciona **adaptadores de compatibilidad** para las bibliotecas i18n más populares del ecosistema.
+
+Estos paquetes adaptadores exponen la **misma API pública exacta** que tus bibliotecas i18n existentes, pero delegan todo el trabajo de traducción a Intlayer en tiempo de ejecución.
+
+## Cómo funciona
+
+Cuando usas un adaptador de compatibilidad, no necesitas reescribir las importaciones de tu aplicación ni cambiar cómo usas tus hooks de traducción y componentes. En su lugar, los plugins del empaquetador de Intlayer identifican automáticamente tus importaciones existentes con los paquetes de compatibilidad de Intlayer.
+
+Por ejemplo, un desarrollador reemplaza `import { useTranslation } from 'react-i18next'` con `import { useTranslation } from '@intlayer/react-i18next'` (hecho automáticamente mediante el plugin del empaquetador), y la aplicación continúa funcionando con traducciones servidas ahora desde diccionarios de Intlayer. ¡Las claves también se escriben contra tus diccionarios de Intlayer!
+
+## Adaptadores de Compatibilidad Disponibles
+
+Elige tu biblioteca existente a continuación para ver cómo migrar sin problemas:
+
+- [Vue I18n](./vue-i18n.md)
+- [Transloco](./transloco.md)
+- [React Intl](./react-intl.md)
+- [Svelte I18n](./svelte-i18n.md)
+- [React i18next](./react-i18next.md)
+- [Polyglot.js](./polyglot.md)
+- [NuxtJS I18n](./nuxtjs-i18n.md)
+- [NGX Translate](./ngx-translate.md)
+- [Next Translate](./next-translate.md)
+- [Next Intl](./next-intl.md)
+- [Next i18next](./next-i18next.md)
+- [i18next](./i18next.md)
+- [Lingui](./lingui.md)
+- [I18n-js](./i18n-js.md)

package/docs/es/compat/lingui.md

@@ -0,0 +1,44 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar de Lingui a Intlayer"
+description: "Aprende cómo migrar tu aplicación desde Lingui a Intlayer usando el adaptador de compatibilidad."
+keywords:
+  - lingui
+  - intlayer
+  - migración
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - lingui
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Inicializar historial"
+author: aymericzip
+---
+
+# Migrar de Lingui a Intlayer
+
+Si tu proyecto actualmente se basa en la compilación basada en macros de Lingui, hacer la transición a Intlayer te permite mantener tus potentes flujos de trabajo de macros mientras los respalda nativamente con la estrategia de compilación JSON de Intlayer.
+
+## Qué hacer
+
+Para comenzar, inicializa Intlayer en tu proyecto:
+
+```bash
+npx intlayer init
+```
+
+Esto crea tu `intlayer.config.ts`. Asegúrate de retener `@lingui/babel-plugin-lingui-macro` / `@lingui/swc-plugin` en tu paso de compilación para ejecutarse _antes_ del compilador de Intlayer. Luego, utiliza el alias del plugin del empaquetador para enrutar `@lingui/core` y `@lingui/react` a `@intlayer/lingui`.
+
+## Qué hace bajo el capó
+
+Lingui utiliza macros (como `` t`Hello ${name}` `` y `<Trans>`) que se compilan en llamadas de runtime como `i18n._(id, values)`.
+
+Bajo el capó:
+
+- **Macros:** Se compilan exactamente como lo hacían antes, asegurando sin perturbación en tu sintaxis fuente.
+- **Traducción de runtime:** El `i18n._()` asignado utiliza diccionarios de Intlayer. Tanto los IDs nombrados explícitamente como los IDs con hash se asignan completamente utilizando los plugins de sincronización `.po` de Intlayer para agregar y podar claves de forma segura.
+- **Capacidades ICU:** El soporte para pluralización, selección y variantes ICU sigue siendo robusto debido al analizador ICU unificado de Intlayer, asegurando salidas de renderizado idénticas.

package/docs/es/compat/next-i18next.md

@@ -0,0 +1,57 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar de next-i18next a Intlayer"
+description: "Aprende cómo migrar tu aplicación Next.js desde next-i18next a Intlayer usando el adaptador de compatibilidad."
+keywords:
+  - next-i18next
+  - nextjs
+  - intlayer
+  - migración
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Inicializar historial"
+author: aymericzip
+---
+
+# Migrar de next-i18next a Intlayer
+
+Para un tutorial completo y detallado paso a paso, por favor consulta nuestra [Guía Completa de Migración de next-i18next](../migration_from_next-i18next_to_intlayer.md).
+
+Intlayer maneja todas las implementaciones de Pages Router y App Router de Next.js de forma transparente. Usar el adaptador te permite migrar tu implementación de `next-i18next` sin reescritura de código.
+
+## Qué hacer
+
+Para comenzar, ejecuta:
+
+```bash
+npx intlayer init
+```
+
+Esto crea el archivo de configuración requerido de Intlayer. Para cambiar a Intlayer tras bastidores, actualiza tu `next.config.ts`:
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+
+const withIntlayer = createNextI18nPlugin();
+
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+## Qué hace bajo el capó
+
+El `createNextI18nPlugin` compone el comportamiento nativo de Next.js junto con el plugin principal `next-intlayer`, inyectando todos los alias requeridos de Webpack/Turbopack para `next-i18next`, `react-i18next` e `i18next`.
+
+Bajo el capó:
+
+- **`serverSideTranslations` y `appWithTranslation`:** Ahora funcionan como envoltorios para los cargadores internos de Intlayer, evitando la inyección estática de JSON grande.
+- **Hooks del cliente:** Delegan inmediatamente a `@intlayer/react-i18next` reteniendo todas las características de formateo, plurales y namespace anidados.

package/docs/es/compat/next-intl.md

@@ -0,0 +1,61 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar de next-intl a Intlayer"
+description: "Aprende cómo migrar tu aplicación Next.js desde next-intl a Intlayer usando el adaptador de compatibilidad."
+keywords:
+  - next-intl
+  - nextjs
+  - intlayer
+  - migración
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-intl
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Inicializar historial"
+author: aymericzip
+---
+
+# Migrar de next-intl a Intlayer
+
+Para un tutorial completo y detallado paso a paso, por favor consulta nuestra [Guía Completa de Migración de next-intl](../migration_from_next-intl_to_intlayer.md).
+
+Migrar de `next-intl` a Intlayer te permite mantener tu enrutamiento y sintaxis de aplicación completamente sin perturbaciones.
+
+## Qué hacer
+
+Ejecuta el siguiente comando en tu repositorio:
+
+```bash
+npx intlayer init
+```
+
+Esto creará un `intlayer.config.ts`. En tu `next.config.ts`, usa el wrapper del plugin para inyectar sin problemas los aliases de `next-intl` hacia `@intlayer/next-intl`.
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
+
+const withIntlayer = createNextIntlPlugin();
+
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+## Qué hace bajo el capó
+
+El wrapper del plugin `@intlayer/next-intl` proporciona alias automáticos que redireccionan todas las importaciones de `next-intl` a `@intlayer/next-intl` durante la compilación.
+
+Bajo el capó:
+
+- **Routing:** El enrutamiento dinámico basado en locale basado en segmentos de `[locale]` continúa funcionando exactamente como lo hacía con `next-intl`, pero ahora las traducciones se sirven desde diccionarios de Intlayer.
+- **`useTranslations`:** Se reimplementa para devolver una función tipada que se vincula automáticamente a tus diccionarios de Intlayer.
+- **`getTranslations`:** En funciones del servidor, obtiene acceso tipado a contenido de Intlayer sin hacer solicitudes de red.
+- **Middleware:** Intlayer proporciona un middleware de routing automático que reconoce locales y gestiona redirecciones.
+
+Tu aplicación mantiene la misma estructura y sintaxis, pero ahora con el poder de Intlayer dirigiendo las traducciones.

package/docs/es/compat/next-translate.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar de Next Translate a Intlayer"
+description: "Aprende cómo migrar tu aplicación Next.js desde next-translate a Intlayer usando el adaptador de compatibilidad."
+keywords:
+  - next-translate
+  - nextjs
+  - intlayer
+  - migración
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-translate
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Inicializar historial"
+author: aymericzip
+---
+
+# Migrar de Next Translate a Intlayer
+
+Migrar de `next-translate` a Intlayer es un reemplazo casi directo que retiene tu sintaxis y etiquetas existentes.
+
+## Qué hacer
+
+Inicializa Intlayer en tu proyecto:
+
+```bash
+npx intlayer init
+```
+
+El CLI generará tu configuración. Luego, puedes aplicar el plugin de Intlayer en tu `next.config.ts`, el cual inyecta aliases de subpaths en tiempo de compilación mapeando `next-translate/useTranslation` a `@intlayer/next-translate`.
+
+## Qué hace bajo el capó
+
+`next-translate` proporciona hooks como `useTranslation('ns')`, `t('ns:key.path')`, y el componente `<Trans>`.
+
+Bajo el capó:
+
+- **Interpolación y plurales:** Se basa estrechamente en el comportamiento del adaptador `react-i18next`. Se manejan dinámicamente son los placeholders `{{var}}` y la pluralización mapeada desde sufijos como `key_0`, `key_one` y `key_other`.
+- **Componente `<Trans>`:** Directamente soportado para análisis de etiquetas tipo HTML junto con una prop `components` basada en arrays.
+- **Namespaces:** Los aliases de subpaths aseguran que tus referencias de `useTranslation` apunten a los namespaces de diccionarios internos correctos sin modificación manual.