Migrar de next-i18next a Intlayer

¿Por qué migrar de next-i18next a Intlayer?

Estrategias de migración

Dado que next-i18next envuelve a react-i18next e i18next internamente, existen dos estrategias complementarias para migrar hacia Intlayer:

1. Adaptador de compatibilidad (recomendado para aplicaciones existentes) — Instala @intlayer/next-i18next, @intlayer/react-i18next, y @intlayer/i18next. Estos paquetes exponen exactamente la misma API que sus equivalentes, pero delegan todo el trabajo de traducción a Intlayer. Mantienes tus llamadas existentes a useTranslation, appWithTranslation, serverSideTranslations y el enrutamiento de páginas de Next.js sin cambios — el único cambio es la inicialización.

2. Migración completa — Reemplaza gradualmente las APIs de next-i18next por hooks nativos de Intlayer (useIntlayer) 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

Migración rápida

Los siguientes pasos son el mínimo requerido para que tu aplicación Next.js Pages Router existente funcione sobre Intlayer con cero cambios de código en tus páginas y componentes.

1. 1

   Instalar Dependencias

   Instala los paquetes principales de Intlayer y los adaptadores de compatibilidad:

   npm install intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   npx intlayer init

   pnpm add intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   pnpm intlayer init

   yarn add intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   yarn intlayer init

   bun add intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   bun x intlayer init

   Puedes mantener de manera segura next-i18next, react-i18next, e i18next instalados durante la migración, aunque los eliminarás una vez configurados los alias.

2. 2

   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 de next-i18next (usualmente en public/locales):

   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 i18next: {{name}}
         format: "i18next",
         source: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/locales",
       }),
     ],
   };
   
   export default config;

   source asigna un idioma y un espacio de nombres (key) a la ruta de su archivo JSON. location le indica al observador de Intlayer qué carpeta monitorear. La opción format: 'i18next' asegura que los marcadores de posición se analicen correctamente para next-i18next.

3. 3

   Actualizar la Configuración de Next.js

   Envuelve tu archivo existente next.config.ts (o .js) con createNextI18nPlugin de @intlayer/next-i18next/plugin. Este envoltorio compone withIntlayer e inyecta los alias next-i18next / react-i18next / i18next → @intlayer/*, de modo que tus llamadas a import { useTranslation } from 'next-i18next' se redirijan transparentemente en tiempo de compilación. No se necesitan cambios en los archivos fuente.

   import type { NextConfig } from "next";
   import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
   // Puedes eliminar la configuración i18n importada de next-i18next.config.js
   // import { i18n } from './next-i18next.config';
   
   const withIntlayer = createNextI18nPlugin();
   
   const nextConfig: NextConfig = {
     // Intlayer gestiona el enrutamiento i18n de Next.js de manera interna,
     // por lo que ya no necesitas pasar el objeto i18n aquí.
   };
   
   export default withIntlayer(nextConfig);

   Ya no necesitas el archivo next-i18next.config.js. Intlayer compila todos los diccionarios en tiempo de compilación, gestionando la detección del idioma, el enrutamiento y la carga de diccionarios a la perfección.

   ¿Prefieres el plugin simple withIntlayer de next-intlayer/server? Compila tus diccionarios pero no añade los alias de next-i18next / react-i18next / i18next — tendrías que renombrar las importaciones a @intlayer/* manualmente (ver el Paso 4).

Eso es todo para la migración rápida. Tu aplicación Next.js ahora funciona sobre Intlayer mientras mantiene intactas todas las llamadas a useTranslation, serverSideTranslations y appWithTranslation.

Claves de traducción tipadas — automáticas. Una vez que Intlayer compila tus diccionarios, useTranslation y getFixedT quedan tipados en relación con 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.

// Pages Router — 'about' es una clave registrada
const { t } = useTranslation("about");
t("counter.label"); // ✓ autocompletado
t("does.not.exist"); // ✗ Error de TypeScript

// getStaticProps / getServerSideProps (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.

1. 4

   Renombrar importaciones explícitamente (opcional)

   Opcional

   El plugin de Intlayer ya maneja los alias a nivel del empaquetador. Si prefieres hacer la dependencia explícita en tus archivos fuente, puedes renombrar las importaciones manualmente:

   Mostrar todo el contenido de la tabla

   Mostrar todo el contenido de la tabla

   Abrir la tabla en una ventana flotante para ver todo el contenido claramente

   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'
   import { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-i18next'

   Estos son reemplazos directos — no se requieren cambios en las firmas de llamada, argumentos o tipos de retorno.

2. 5

   Activar la Automatización de Traducción con IA

   Opcional

   Una vez que Intlayer esté configurado, utiliza su CLI para llenar automáticamente las traducciones faltantes:

   # Probar traducciones faltantes (agregar al CI)
   npx intlayer test
   
   # Llenar traducciones faltantes con IA
   npx intlayer fill

   pnpm intlayer test
   pnpm intlayer fill

   yarn intlayer test
   yarn intlayer fill

   bun x intlayer test
   bun x intlayer fill

   Añade la configuración de IA a intlayer.config.ts:

   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: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/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 para ver todas las opciones disponibles.

Qué puedes eliminar tras la migración

Una vez que el adaptador de compatibilidad esté en su lugar, el siguiente código repetitivo de next-i18next se puede eliminar:

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 y 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 sea completamente fluida con las páginas y componentes.

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:

{
  // ... 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:

# Ignorar los archivos generados por Intlayer
.intlayer

Profundizar Más

• Editor Visual — Gestiona las traducciones visualmente en tu navegador: Editor Visual de Intlayer
• CMS — Externaliza y gestiona contenido de forma remota: Intlayer CMS
• 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
• Referencia del CLI — Lista completa de comandos CLI: Intlayer CLI
• Intlayer con Next.js (Pages Router) — Guía de configuración completa para Next.js: intlayerwithnextjspagerouter.md