@intlayer/docs 9.0.0-canary.2 → 9.0.0-canary.20

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/cli/scan.md

@@ -150,10 +150,10 @@ await scan("https://example.com", {
 });
 ```
 
-Para un acceso de nivel inferior, `scanWebsite` de `@intlayer/chokidar/scan` devuelve un objeto `ScanResult` estructurado:
+Para un acceso de nivel inferior, `scanWebsite` de `@intlayer/engine/scan` devuelve un objeto `ScanResult` estructurado:
 
 ```ts
-import { scanWebsite } from "@intlayer/chokidar/scan";
+import { scanWebsite } from "@intlayer/engine/scan";
 
 const result = await scanWebsite("https://example.com", { deep: false });
 console.log(result.score, result.totalPageSize, result.events);

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.

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

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar de NGX-Translate a Intlayer"
+description: "Aprende cómo migrar tu aplicación Angular desde ngx-translate a Intlayer usando el adaptador de compatibilidad."
+keywords:
+  - ngx-translate
+  - angular
+  - intlayer
+  - migración
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - ngx-translate
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Inicializar historial"
+author: aymericzip
+---
+
+# Migrar de NGX-Translate a Intlayer
+
+Migrar tu aplicación Angular desde `ngx-translate` a Intlayer es fácil con el adaptador de compatibilidad, permitiéndote evitar la necesidad de reescribir todas tus plantillas.
+
+## Qué hacer
+
+Comienza ejecutando:
+
+```bash
+npx intlayer init
+```
+
+Esto configura `intlayer.config.ts`. Reemplaza tus configuraciones `TranslateModule.forRoot()` e importa alias apropiadamente para apuntar a `@intlayer/ngx-translate`.
+
+## Qué hace bajo el capó
+
+`ngx-translate` utiliza `TranslateService` (`instant`, `get`, `stream`) junto con el pipe `{{ 'KEY' | translate:params }}` y la directiva `[translate]`.
+
+Bajo el capó:
+
+- **Servicios:** `TranslateService` envuelve `getIntlayer` y un observable de locale, proporcionando exactamente los mismos métodos.
+- **Pipes y directivas:** Reimplementados para resolver directamente contra diccionarios de Intlayer.
+- **Cargadores:** Las configuraciones de `TranslateHttpLoader` se convierten en stubs de advertencia porque Intlayer inherentemente resuelve y agrupa tus diccionarios en tiempo de compilación (o a través de importaciones dinámicas estándar), eliminando completamente la necesidad de cargadores HTTP.

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

@@ -0,0 +1,46 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar de NuxtJS I18n a Intlayer"
+description: "Aprende cómo migrar tu aplicación Nuxt desde @nuxtjs/i18n a Intlayer usando el módulo adaptador de compatibilidad."
+keywords:
+  - nuxtjs-i18n
+  - nuxt
+  - vue
+  - intlayer
+  - migración
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - nuxtjs-i18n
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Inicializar historial"
+author: aymericzip
+---
+
+# Migrar de NuxtJS I18n a Intlayer
+
+Migrar tu aplicación Nuxt desde `@nuxtjs/i18n` a Intlayer es un proceso sin problemas usando el módulo adaptador de Nuxt.
+
+## Qué hacer
+
+Para inicializar el proyecto, ejecuta:
+
+```bash
+npx intlayer init
+```
+
+Esto configurará `intlayer.config.ts`. Luego, agrega el módulo Nuxt de Intlayer (p. ej. `@intlayer/nuxt-i18n`) en el array de módulos de tu `nuxt.config.ts`. Esto aplica automáticamente la configuración de compatibilidad para tu aplicación.
+
+## Qué hace bajo el capó
+
+`@nuxtjs/i18n` envuelve `vue-i18n` mientras proporciona composables de enrutamiento específicos de Nuxt (`useLocalePath`, `useSwitchLocalePath`, `<NuxtLinkLocale>`).
+
+Bajo el capó:
+
+- **Traducciones:** Se basa nativamente en la capa de compatibilidad `@intlayer/vue-i18n` para todas las tareas de traducción de cadenas (soportando completamente formatos de `vue-i18n`, plurales de tubería y reactividad).
+- **Enrutamiento:** Refleja los composables de enrutamiento utilizando los helpers de URL localizadas de Intlayer.
+- **Configuración:** Lee los `availableLocales` y la configuración predeterminada directamente desde tu `intlayer.config.ts` para coordinar páginas de Nuxt automáticamente.

package/docs/es/compat/polyglot.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar de Polyglot.js a Intlayer"
+description: "Aprende cómo migrar desde Polyglot.js a Intlayer usando el adaptador de compatibilidad."
+keywords:
+  - polyglot
+  - airbnb
+  - intlayer
+  - migración
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - polyglot
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Inicializar historial"
+author: aymericzip
+---
+
+# Migrar de Polyglot.js a Intlayer
+
+Si estás usando Polyglot.js de Airbnb, migrar a Intlayer es extremadamente fácil usando la capa de compatibilidad.
+
+## Qué hacer
+
+Simplemente ejecuta el comando de inicialización en tu proyecto:
+
+```bash
+npx intlayer init
+```
+
+Esto genera `intlayer.config.ts`. Luego puedes utilizar el alias del plugin del empaquetador para redireccionara transparentemente importaciones de Polyglot a `@intlayer/polyglot`.
+
+## Qué hace bajo el capó
+
+La sintaxis de Polyglot.js típicamente se basa en `polyglot.t('key', {name})` con interpolaciones `%{name}` y plurales `smart_count` separados por `"singular |||| plural"`.
+
+Bajo el capó:
+
+- **Interpolación:** La capa de compatibilidad maneja placeholders `%{var}` nativamente.
+- **Plurales:** La cadena se divide en `||||` y se evalúa contra `Intl.PluralRules` nativo según el locale activo, reflejando el propio orden de bucket de Polyglot por locale.
+- **Diccionarios:** Evitas la necesidad de proporcionar enormes configuraciones de JSON a `new Polyglot()` – Intlayer maneja los diccionarios dinámicamente y los poda automáticamente.

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

@@ -0,0 +1,58 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar de react-i18next a Intlayer"
+description: "Aprende cómo migrar tu aplicación React desde react-i18next a Intlayer usando el adaptador de compatibilidad."
+keywords:
+  - react-i18next
+  - i18next
+  - intlayer
+  - migración
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - react-i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Inicializar historial"
+author: aymericzip
+---
+
+# Migrar de react-i18next a Intlayer
+
+Para un tutorial completo y detallado paso a paso, por favor consulta nuestra [Guía Completa de Migración de react-i18next](../migration_from_react-i18next_to_intlayer.md).
+
+Usar el adaptador de compatibilidad de Intlayer te permite migrar desde `react-i18next` sin ningún cambio en las importaciones de tu código fuente.
+
+## Qué hacer
+
+Para inicializar el proyecto, ejecuta:
+
+```bash
+npx intlayer init
+```
+
+Durante la inicialización, Intlayer instalará `@intlayer/react-i18next` y creará `intlayer.config.ts`. En tu empaquetador (como Vite), aplica el plugin de Intlayer:
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { reactI18nextVitePlugin } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [react(), reactI18nextVitePlugin()],
+});
+```
+
+## Qué hace bajo el capó
+
+El `reactI18nextVitePlugin` envuelve el plugin principal `vite-intlayer` e inyecta alias de resolución para `react-i18next` e `i18next`, redireccionándolos a `@intlayer/react-i18next` y `@intlayer/i18next`.
+
+Bajo el capó:
+
+- **`useTranslation` y `withTranslation`:** Reescritos para usar hooks nativos de Intlayer, dándote finalización automática de TypeScript para tus claves de diccionario. Soporta sin problemas namespaces (p. ej. `t('namespace:key')`).
+- **Plurales y contexto:** Maneja la pluralización basada en sufijos de i18next (`key_one`, `key_other`) usando `Intl.PluralRules` nativo y sufijos de contexto (`key_male`).
+- **Componente `<Trans>`:** Reimplementado para soportar la prop `components`, formularios de objeto y array, y etiquetas numeradas `<1>...</1>` directamente mapeadas a tus nodos React.
+- **Instancia de `i18n`:** Resuelve claves directamente desde Intlayer sin buscar archivos JSON grandes, resultando en tamaños de bundle significativamente menores.

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

@@ -0,0 +1,55 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar de React Intl a Intlayer"
+description: "Aprende cómo migrar tu aplicación React desde react-intl a Intlayer usando el adaptador de compatibilidad."
+keywords:
+  - react-intl
+  - formatjs
+  - intlayer
+  - migración
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - react-intl
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Inicializar historial"
+author: aymericzip
+---
+
+# Migrar de React Intl a Intlayer
+
+Si tu aplicación React usa `react-intl` (FormatJS), hacer la transición a Intlayer es muy fácil. Nuestra capa de compatibilidad maneja sin problemas ICU MessageFormat y todos los componentes `Formatted*` existentes.
+
+## Qué hacer
+
+Comienza ejecutando el comando de inicialización en tu proyecto:
+
+```bash
+npx intlayer init
+```
+
+Luego, configura el plugin de Vite o Next.js de Intlayer en tu configuración. Este plugin inyecta aliases en tiempo de compilación para redireccionara importaciones de `react-intl` a `@intlayer/react-intl`.
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import reactIntlVitePlugin from "@intlayer/react-intl/plugin";
+
+export default defineConfig({
+  plugins: [react(), reactIntlVitePlugin()],
+});
+```
+
+## Qué hace bajo el capó
+
+El plugin del empaquetador asigna `react-intl` a `@intlayer/react-intl`. En lugar de analizar manualmente grandes archivos JSON y envolver tu aplicación en un `IntlProvider`, el plugin de Intlayer extrae estáticamente claves y usa diccionarios de Intlayer en tiempo de ejecución.
+
+Bajo el capó:
+
+- **ICU MessageFormat:** Intlayer utiliza el resolvedor `resolveMessage(..., 'icu')` que soporta completamente pluralización ICU, selección, formateo de fechas/números y etiquetas de texto rico nativamente.
+- **Llamadores de método y JSX:** `intl.formatMessage({ id: 'a.b' })` y `<FormattedMessage id="a.b">` son identificados por los plugins del compilador de Intlayer (`@intlayer/babel` / `@intlayer/swc`), convirtiendo claves con puntos planos para que el primer segmento se resuelva correctamente a la clave del diccionario de Intlayer.
+- **Formateadores:** `<FormattedNumber>`, `<FormattedDate>`, etc., se puenten a los `core/formatters` nativos usando `Intl`.