Migrar de next-intl a Intlayer

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

Estrategia de migración

El enfoque recomendado para las aplicaciones existentes es el adaptador de compatibilidad: instala @intlayer/next-intl, que expone exactamente la misma API que next-intl pero delega todo el trabajo de traducción a Intlayer.

Mantienes tus useTranslations, getTranslations, NextIntlClientProvider existentes y demás elementos — el único cambio es la ruta de importación. No se requiere refactorizar firmas de llamada, formas de props o la estructura de los componentes.

Con el tiempo puedes, opcionalmente, migrar archivos individuales al formato .content.ts más rico de Intlayer para desbloquear el editor visual, el CMS y el alcance de contenido por componente — pero este paso es enteramente opcional y puede realizarse de forma gradual.

Tabla de Contenidos

Migración rápida

Los siguientes pasos son el mínimo requerido para que tu aplicación next-intl existente funcione sobre Intlayer con cero cambios en el código.

1. 1

   Instalar Dependencias

   Instala los paquetes principales de Intlayer y el adaptador de compatibilidad @intlayer/next-intl:

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   npm install intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-pluginnpx intlayer init

   Conserva instalado next-intl — sigue siendo necesario para el enrutamiento URL (createNavigation, createMiddleware, Link, redirect, usePathname, useRouter). El adaptador de compatibilidad no reemplaza la capa de enrutamiento.

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:

   intlayer.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   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({
         // 'icu' coincide con la sintaxis de marcador de posición ICU de next-intl: {name}, {count, plural, ...}
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
   };
   
   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: 'icu' asegura que los marcadores de posición ICU como {name} y {count, plural, one {# item} other {# items}} se analicen correctamente.

   Para obtener una lista completa de opciones de configuración, consulta la documentación de configuración.

3. 3

   Añadir el Plugin de Intlayer a Next.js

   Envuelve tu configuración existente de Next.js con createNextIntlPlugin desde @intlayer/next-intl/plugin. Este envoltorio compone withIntlayer e inyecta los alias next-intl → @intlayer/next-intl por ti:

   next.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import type { NextConfig } from "next";
   import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
   
   const withIntlayer = createNextIntlPlugin();
   
   const nextConfig: NextConfig = {
     /* tus opciones de configuración existentes */
   };
   
   export default withIntlayer(nextConfig);

   createNextIntlPlugin() envuelve a withIntlayer, detecta automáticamente Webpack o Turbopack, vincula el monitoreo de contenido, compila los diccionarios y, lo más importante, inyecta alias de módulos para que tus llamadas existentes a import … from 'next-intl' sean redirigidas de forma transparente a @intlayer/next-intl en tiempo de compilación. La entrada de enrutamiento next-intl/routing sigue apuntando al paquete real. No se requieren cambios en los archivos de origen.

   ¿Prefieres usar el withIntlayer sencillo de next-intlayer/server? Compilará tus diccionarios, pero no añadirá los alias de next-intl — tendrías que renombrar las importaciones a @intlayer/next-intl manualmente (ver el Paso 4).

   Ya no necesitas getRequestConfig o loadMessages. Con next-intl, tenías que escribir un archivo src/i18n.ts que cargaba paquetes de mensajes JSON en cada solicitud a través de getRequestConfig. Intlayer compila todos los diccionarios en tiempo de compilación, por lo que no hay paso de carga en tiempo de ejecución. Puedes borrar ese archivo por completo (o mantener solo las partes de enrutamiento si aún utilizas createNavigation).

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 next-intl.

Claves de traducción tipadas — automáticas. Una vez que Intlayer compila tus diccionarios, useTranslations y getTranslations 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

Copiar contenido

Copiar código

Copiar el código al portapapeles

// Componente de cliente — 'about' es una clave de diccionario registradaconst t = useTranslations("about");t("counter.label"); // ✓ autocompletadot("does.not.exist"); // ✗ Error de TypeScript// Componente de servidorconst t = await getTranslations("about");t("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 contenedor createNextIntlPlugin() ya maneja el alias de next-intl → @intlayer/next-intl a nivel del empaquetador. Si prefieres hacer la dependencia explícita en tus archivos de origen (y usar el plugin withIntlayer regular en su lugar), 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 { useTranslations } from 'next-intl'	import { useTranslations } from '@intlayer/next-intl'
   import { useLocale } from 'next-intl'	import { useLocale } from '@intlayer/next-intl'
   import { NextIntlClientProvider } from 'next-intl'	import { NextIntlClientProvider } from '@intlayer/next-intl'
   import { getTranslations } from 'next-intl/server'	import { getTranslations } from '@intlayer/next-intl/server'
   import { getLocale } from 'next-intl/server'	import { getLocale } from '@intlayer/next-intl/server'
   import { setLocale } from 'next-intl/server'	import { setLocale } from '@intlayer/next-intl/server'
   import { getMessages } from 'next-intl/server'	import { getMessages } from '@intlayer/next-intl/server'

   Mantén siempre las importaciones de enrutamiento del next-intl real — el adaptador de compatibilidad no reemplaza la capa de enrutamiento URL:

   ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   // ✅ Mantén siempre estos desde el 'next-intl' realimport { createNavigation } from "next-intl/routing";import { createMiddleware } from "next-intl/server";import { defineRouting } from "next-intl/routing";

   De manera alternativa, puedes usar defineRouting de @intlayer/next-intl/routing que combina la configuración de idiomas de tu intlayer.config.ts automáticamente.

2. 5

   Activar la Automatización de Traducción con IA

   Opcional

   Una vez que Intlayer esté configurado, puedes usar su CLI para llenar automáticamente las traducciones faltantes utilizando el LLM de tu elección:

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

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

   Añade una OPENAI_API_KEY (o la clave de tu proveedor preferido) a tu archivo .env, luego amplía tu intlayer.config.ts:

   intlayer.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   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: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
     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 @intlayer/next-intl esté en su lugar, el siguiente código repetitivo de next-intl 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 about.content.ts directamente junto a tu about/page.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 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 — Guía de configuración completa para Next.js: intlayerwithnextjs_16.md