@intlayer/docs 8.12.1 → 8.12.3

package/docs/es/migration_from_react-i18next_to_intlayer.md

@@ -0,0 +1,367 @@
+---
+createdAt: 2026-06-05
+updatedAt: 2026-06-05
+title: "Migrar de react-i18next / i18next a Intlayer | Internacionalización (i18n)"
+description: "Aprende cómo migrar tu aplicación React o Next.js de react-i18next o i18next a Intlayer — paso a paso, sin romper tu código existente. Utiliza los adaptadores de compatibilidad @intlayer/react-i18next y @intlayer/i18next para una transición sin interrupciones."
+keywords:
+  - react-i18next
+  - i18next
+  - intlayer
+  - migración
+  - internacionalización
+  - i18n
+  - Next.js
+  - React
+  - JavaScript
+slugs:
+  - doc
+  - migration
+  - react-i18next
+history:
+  - version: 8.13.0
+    date: 2026-06-05
+    changes: "Init history"
+---
+
+# Migrar de react-i18next / i18next a Intlayer
+
+## ¿Por qué migrar de react-i18next / i18next a Intlayer?
+
+<AccordionGroup>
+
+<Accordion header="Tamaño del bundle">
+
+En lugar de cargar archivos JSON masivos en tus páginas, carga solo el contenido necesario. Intlayer ayuda a **reducir el tamaño de tu bundle y tus páginas hasta en un 50 %**.
+
+</Accordion>
+
+<Accordion header="Mantenibilidad">
+
+Establecer un alcance al contenido de tu aplicación **facilita el mantenimiento** para aplicaciones a gran escala. Puedes duplicar o eliminar una carpeta de función completa sin la carga mental de revisar todo el código de tu contenido. Además, Intlayer está **completamente tipado** para asegurar la precisión de tu contenido.
+
+Intlayer es también la solución con el **desarrollo más activo** en el ecosistema i18n — los problemas se solucionan rápidamente, nuevos adaptadores de framework se añaden regularmente y la API principal se refina continuamente basándose en retroalimentación real de producción.
+
+</Accordion>
+
+<Accordion header="Agente de IA">
+
+Colocalizar el contenido **reduce el contexto necesario** para los Grandes Modelos de Lenguaje (LLM). Intlayer también incluye una suite de herramientas, como un **CLI** para probar traducciones faltantes, **[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/mcp_server.md)** y **[habilidades de agente](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/agent_skills.md)**, para que la experiencia del desarrollador (DX) sea aún más fluida para los agentes de IA.
+
+</Accordion>
+
+<Accordion header="Automatización">
+
+Usa la automatización para traducir en tu flujo de CI/CD utilizando el LLM de tu elección al costo de tu proveedor de IA. Intlayer también ofrece un **compilador** para automatizar la extracción de contenido, así como una [plataforma web](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md) para ayudar a **traducir en segundo plano**.
+
+</Accordion>
+
+<Accordion header="Rendimiento">
+
+Conectar archivos JSON masivos a los componentes puede llevar a problemas de rendimiento y reactividad. Intlayer optimiza la carga de tu contenido en tiempo de compilación.
+
+</Accordion>
+
+<Accordion header="Escalabilidad con no-desarrolladores">
+
+Más que una simple solución de i18n, Intlayer proporciona un **[editor visual](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_visual_editor.md)** autohospedado y un **[CMS completo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md)** para ayudarte a gestionar tu contenido multilingüe en **tiempo real**, haciendo la colaboración con traductores, redactores y otros miembros del equipo fluida. El contenido se puede almacenar local y/o remotamente.
+
+</Accordion>
+
+</AccordionGroup>
+
+---
+
+## Estrategias de migración
+
+Existen dos estrategias complementarias para migrar de `react-i18next` / `i18next` a Intlayer:
+
+1. **Adaptador de compatibilidad (recomendado para aplicaciones existentes)** — Instala `@intlayer/react-i18next` (para componentes React) y/o `@intlayer/i18next` (para la instancia core de `i18n`). Estos paquetes exponen **exactamente la misma API** que `react-i18next` / `i18next` pero delegan todo el trabajo de traducción a Intlayer. Mantienes tus llamadas existentes a `useTranslation`, `Trans`, `withTranslation`, `i18next.t()` — el único cambio es la ruta de importación.
+
+2. **Migración completa** — Reemplaza gradualmente las APIs de `react-i18next` por hooks nativos de Intlayer (`useIntlayer`, `IntlayerProvider`) y colocaliza el contenido en archivos `.content.ts` junto a tus componentes.
+
+Esta guía cubre primero la **Estrategia 1** (adaptador de compatibilidad de fácil uso), y luego revisa la migración completa opcional.
+
+---
+
+## Tabla de Contenidos
+
+<TOC/>
+
+---
+
+## Migración rápida
+
+Los siguientes pasos son el mínimo requerido para que tu aplicación `react-i18next` existente funcione sobre Intlayer con cero cambios en el código.
+
+<Steps>
+
+<Step number={1} title="Instalar Dependencias">
+
+Instala los paquetes principales de Intlayer y los adaptadores de compatibilidad:
+
+```bash packageManager="npm"
+npm install intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
+npx intlayer init
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
+pnpm intlayer init
+```
+
+```bash packageManager="yarn"
+yarn add intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
+yarn intlayer init
+```
+
+```bash packageManager="bun"
+bun add intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
+bun x intlayer init
+```
+
+> Puedes mantener `react-i18next` e `i18next` instalados — los adaptadores de compatibilidad los usan como `devDependencies` / `peerDependencies` opcionales para los tipos de TypeScript. No necesitas cambiar ningún peer de tu `package.json`.
+
+</Step>
+
+<Step number={2} title="Configurar Intlayer">
+
+El comando `intlayer init` crea un archivo inicial `intlayer.config.ts`. Actualízalo para que coincida con tus idiomas existentes y apunta el plugin `syncJSON` a tus archivos de mensajes:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Agrega todos tus idiomas existentes aquí
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      // coincide con la sintaxis de marcador de posición react-i18next: {{name}}
+      format: "i18next",
+      source: ({ locale }) => `./src/locales/${locale}.json`,
+      location: "src/locales",
+    }),
+  ],
+};
+
+export default config;
+```
+
+> **`source`** asigna un idioma a su ruta de archivo JSON. **`location`** le indica al observador de Intlayer qué carpeta monitorear en busca de cambios. La opción `format: 'i18next'` asegura que los marcadores de posición como `{{name}}` se analicen correctamente.
+
+</Step>
+
+<Step number={3} title="Añadir el Plugin de Intlayer a tu Bundler">
+
+Envuelve tu configuración de empaquetador existente con el plugin de compatibilidad. Este compone el plugin principal de Intlayer, vincula el monitoreo de contenido, y — críticamente — **inyecta alias de módulos** para que tus llamadas existentes a `import … from 'react-i18next'` (y `'i18next'`) sean redirigidas transparentemente a `@intlayer/react-i18next` / `@intlayer/i18next` en tiempo de compilación. No se requieren cambios en los archivos fuente.
+
+**Para Vite:**
+
+```typescript fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { reactI18nextVitePlugin } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [react(), reactI18nextVitePlugin()],
+});
+```
+
+> `reactI18nextVitePlugin()` envuelve el plugin `intlayer()` de `vite-intlayer` y añade los alias de `react-i18next` / `i18next`. Usar el plugin regular `intlayer()` de `vite-intlayer` compila los diccionarios pero **no** añade los alias — tendrías que renombrar las importaciones a `@intlayer/*` manualmente (ver el Paso 4).
+
+**Para Next.js:**
+
+Si utilizas `next-i18next` (integración con Pages Router), instala `@intlayer/next-i18next` y `next-intlayer`:
+
+```bash packageManager="npm"
+npm install @intlayer/next-i18next next-intlayer
+```
+
+Luego, agrega el plugin de compatibilidad a tu `next.config.ts` (inyecta los alias `next-i18next` / `react-i18next` / `i18next`):
+
+```typescript fileName="next.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { NextConfig } from "next";
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+
+const withIntlayer = createNextI18nPlugin();
+
+const nextConfig: NextConfig = {
+  /* tus opciones */
+};
+
+export default withIntlayer(nextConfig);
+```
+
+> **Ya no necesitas `i18next.init()` ni configuración manual del provider.** Intlayer compila todos los diccionarios **en tiempo de compilación**, por lo que no hay paso de carga en tiempo de ejecución. El proveedor aliasado maneja la inicialización por ti.
+
+</Step>
+
+</Steps>
+
+Eso es todo para la migración rápida. Tu aplicación ahora funciona sobre Intlayer mientras mantiene intactas todas las importaciones y APIs de `react-i18next`.
+
+> **Claves de traducción tipadas — automáticas.** Una vez que Intlayer compila tus diccionarios, `useTranslation` y `getFixedT` quedan tipados en relación a tu contenido real. Las claves se autocompletan en tu IDE y las rutas inválidas provocan errores de TypeScript en tiempo de compilación — sin configuraciones adicionales requeridas.
+>
+> ```tsx
+> // 'about' es una clave de diccionario registrada → t() solo acepta rutas válidas
+> const { t } = useTranslation("about");
+> t("counter.label"); // ✓ autocompletado
+> t("does.not.exist"); // ✗ Error de TypeScript
+>
+> // Lado del servidor (instancia i18next)
+> const tAbout = i18n.getFixedT(null, "about");
+> tAbout("counter.label"); // ✓ tipado
+> ```
+
+---
+
+## Migración completa
+
+Los pasos a continuación son opcionales y pueden hacerse incrementalmente. Desbloquean todas las funcionalidades de Intlayer: editor visual, CMS, archivos de contenido tipados, automatización de traducción con IA y más.
+
+<Steps>
+
+<Step number={4} title="Renombrar importaciones explícitamente (opcional)" isOptional={true}>
+
+Los plugins de Intlayer ya manejan los alias a nivel del empaquetador. Si prefieres hacer la dependencia explícita en tus archivos de origen, puedes renombrar las importaciones manualmente:
+
+| Antes                                              | Después                                                      |
+| -------------------------------------------------- | ------------------------------------------------------------ |
+| `import { useTranslation } from 'react-i18next'`   | `import { useTranslation } from '@intlayer/react-i18next'`   |
+| `import { Trans } from 'react-i18next'`            | `import { Trans } from '@intlayer/react-i18next'`            |
+| `import { withTranslation } from 'react-i18next'`  | `import { withTranslation } from '@intlayer/react-i18next'`  |
+| `import { I18nextProvider } from 'react-i18next'`  | `import { I18nextProvider } from '@intlayer/react-i18next'`  |
+| `import { initReactI18next } from 'react-i18next'` | `import { initReactI18next } from '@intlayer/react-i18next'` |
+| `import i18next from 'i18next'`                    | `import i18next from '@intlayer/i18next'`                    |
+| `import { createInstance } from 'i18next'`         | `import { createInstance } from '@intlayer/i18next'`         |
+| `import { t } from 'i18next'`                      | `import { t } from '@intlayer/i18next'`                      |
+
+Para Next.js (`next-i18next`):
+
+| Antes                                                                          | Después                                                           |
+| ------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
+| `import { serverSideTranslations } from 'next-i18next/serverSideTranslations'` | `import { serverSideTranslations } from '@intlayer/next-i18next'` |
+| `import { appWithTranslation } from 'next-i18next'`                            | `import { appWithTranslation } from '@intlayer/next-i18next'`     |
+| `import { useTranslation } from 'next-i18next'`                                | `import { useTranslation } from '@intlayer/next-i18next'`         |
+
+</Step>
+
+<Step number={5} title="Activar la Automatización de Traducción con IA" isOptional={true}>
+
+Una vez que Intlayer esté configurado, utiliza su CLI para llenar automáticamente las traducciones faltantes:
+
+```bash packageManager="npm"
+# Probar traducciones faltantes (agregar al CI)
+npx intlayer test
+
+# Llenar traducciones faltantes con IA
+npx intlayer fill
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer test
+pnpm intlayer fill
+```
+
+```bash packageManager="yarn"
+yarn intlayer test
+yarn intlayer fill
+```
+
+```bash packageManager="bun"
+bun x intlayer test
+bun x intlayer fill
+```
+
+Añade la configuración de IA a `intlayer.config.ts`:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      format: "i18next",
+      source: ({ locale }) => `./src/locales/${locale}.json`,
+      location: "src/locales",
+    }),
+  ],
+  ai: {
+    apiKey: process.env.OPENAI_API_KEY,
+    // provider: "openai",     // default
+    // model: "gpt-4o-mini",   // default
+  },
+};
+
+export default config;
+```
+
+> Consulta la [documentación de CLI de Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/index.md) para ver todas las opciones disponibles.
+
+</Step>
+
+</Steps>
+
+---
+
+## Qué puedes eliminar tras la migración
+
+Una vez que los adaptadores de compatibilidad estén en su lugar, el siguiente código repetitivo de `react-i18next` / `i18next` se puede eliminar:
+
+| Archivo / patrón                           | Por qué ya no es necesario                                                                                                                             |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Llamadas a `i18next.init()`                | El proveedor de Intlayer inicializa todo automáticamente; no hay paso de carga en tiempo de ejecución.                                                 |
+| `I18nextProvider` / `initReactI18next`     | El plugin de Intlayer maneja la inyección de manera interna.                                                                                           |
+| Bundles de idiomas JSON (`locales/*.json`) | Los bundles JSON solo son necesarios si aún utilizas el plugin `syncJSON`. Una vez que migres a archivos `.content.ts`, puedes borrar la carpeta JSON. |
+
+Cuando estés listo para ir más allá, Intlayer **descubre automáticamente todos los archivos `.content.ts` y `.content.json` en cualquier lugar de tu código base** (por defecto, en cualquier lugar dentro de `./src`). Puedes colocar un archivo `my-component.content.ts` directamente junto a tu `MyComponent.tsx` e Intlayer lo tomará al momento de compilación sin configuración adicional — sin importaciones, sin registro, sin necesidad de un archivo índice centralizado. Esto hace que la co-localización de traducciones con páginas y componentes sea completamente fluida.
+
+---
+
+## Configurar TypeScript
+
+Intlayer usa el aumento de módulos para ofrecer autocompletado completo de TypeScript para tus claves de traducción. Asegúrate de que tu `tsconfig.json` incluya los tipos generados automáticamente:
+
+```json5 fileName="tsconfig.json"
+{
+  // ... Tus configuraciones de TypeScript existentes
+  "include": [
+    // ... Tus configuraciones de TypeScript existentes
+    ".intlayer/**/*.ts", // Incluir los tipos generados automáticamente
+  ],
+}
+```
+
+---
+
+## Configuración de Git
+
+Añade el directorio generado por Intlayer a tu `.gitignore`:
+
+```plaintext fileName=".gitignore"
+# Ignorar los archivos generados por Intlayer
+.intlayer
+```
+
+---
+
+## Profundizar Más
+
+- **Editor Visual** — Gestiona las traducciones visualmente en tu navegador: [Editor Visual de Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_visual_editor.md)
+- **CMS** — Externaliza y gestiona contenido de forma remota: [Intlayer CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md)
+- **Extensión de VS Code** — Obtén autocompletado y detección de errores de traducción en tiempo real: [Extensión de VS Code de Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/vs_code_extension.md)
+- **Referencia del CLI** — Lista completa de comandos CLI: [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/index.md)
+- **Intlayer con React** — Guía de configuración completa para React: [intlayer_with_vite+react.md](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_with_vite+react.md)
+- **Intlayer con Next.js** — Guía de configuración completa para Next.js: [intlayer_with_nextjs_16.md](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_with_nextjs_16.md)