Nuevo Intlayer v9 - ¿Qué hay de nuevo?

¡Bienvenido a Intlayer v9! Esta importante versión marca un gran hito al simplificar la ruta de migración a Intlayer con Paquetes Adaptadores de Compatibilidad para las principales librerías i18n (react-i18next, next-intl, vue-i18n, etc.) y añade soporte para estructuras de contenido enriquecido: Colecciones y Variantes.

Tabla de contenidos

Paquetes Adaptadores de Compatibilidad

Migrar a Intlayer desde librerías i18n populares es ahora más fácil que nunca. Hemos creado cinco paquetes de compatibilidad que exponen las mismas APIs públicas exactas que las librerías i18n estándar, pero delegan todo el trabajo de traducción a Intlayer en tiempo de ejecución.

Exponer la Misma API Pública con Tipado Estricto

Al reemplazar los imports, obtienes todos los beneficios de Intlayer (incluida la seguridad de tipos en tiempo de compilación contra tus diccionarios reales) con cambios mínimos en el código:

• @intlayer/i18next
• @intlayer/react-i18next
• @intlayer/next-intl
• @intlayer/react-intl
• @intlayer/next-i18next
• @intlayer/vue-i18n
• @intlayer/lingui

Por ejemplo, simplemente cambia:

import { useTranslation } from "react-i18next";

a:

import { useTranslation } from "@intlayer/react-i18next";

¡Tus claves ahora estarán estrictamente tipadas contra tus diccionarios de Intlayer, ofreciendo auto-completado completo de rutas con puntos en tu IDE!

Plugins de Alias de Bundler (Vite, Next.js, Turbopack)

Para permitir la migración sin reescribir manualmente todas tus declaraciones de importación, cada paquete adaptador de compatibilidad incluye un plugin de bundler personalizado (Vite o Next.js) bajo la subruta /plugin.

Estos plugins reescriben automáticamente los imports existentes (por ejemplo, react-i18next o next-intl) a sus equivalentes @intlayer/* en tiempo de compilación.

Ejemplo de Next.js (Webpack / Turbopack)

En lugar de withIntlayer, envuelve tu configuración de Next.js con el plugin de compatibilidad:

import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";import type { NextConfig } from "next";const withIntlayer = createNextI18nPlugin();const nextConfig: NextConfig = {};export default withIntlayer(nextConfig);

Ejemplo de Vite (React, Vue, Solid, Svelte)

import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";export default defineConfig({  plugins: [vueI18nVitePlugin()],});

Resolvedor de Tiempo de Ejecución Mutualizado

Todos los adaptadores de compatibilidad ahora enrutan la resolución de traducciones a través de un único parser de tiempo de ejecución altamente optimizado: @intlayer/core/messageFormat.

• Interpolación de Mensajes: Resuelve {{var}} estándar (espacios en blanco y rutas con puntos), argumentos formateados ICU ({v, number, percent} etc.) y plantillas {var} simples.
• Resolvedor de Nodos de Mensaje: Resuelve nodos anidados: insert(), plural() (reglas de plural CLDR), enu() (enumeración), gender(), etiquetas HTML, arrays y nodos de función invocables.
• Parser de Etiquetas Tokenizadas: Soporta etiquetas XML/HTML en línea y etiquetas numeradas (por ejemplo, <1>children</1>) para potenciar la renderización de texto enriquecido de forma predeterminada.

Especificación de Características: Colecciones y Variantes

Intlayer v9 se expande más allá de los objetos estáticos clave-valor, permitiendo que los diccionarios declaren estructuras de diseño dinámicas que están completamente tipadas de principio a fin.

1. Colecciones

Define una lista de elementos ordenados gestionada por CMS (por ejemplo, FAQs, productos o listas de blogs):

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 1,  content: {    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),  },} satisfies Dictionary;

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 2,  content: {    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),  },} satisfies Dictionary;

Uso:

// Fetch all items as an arrayconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Fetch a single item by indexconst faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }

2. Variantes

Ofrece pruebas A/B, encabezados de temporada, feature flags o landing pages personalizadas:

Variantes de cadena (por ejemplo, pruebas A/B)

import { t, type Dictionary } => "intlayer";export default {  key: "hero-banner",  variant: "default",  content: {    control: t({ es: "Bienvenido", en: "Welcome", fr: "Bienvenue" }),    black_friday: t({ es: "Comprar ahora", en: "Shop now", fr: "Acheter maintenant" }),  },} satisfies Dictionary;

Uso:

const banner = useIntlayer("hero-banner", { variant: "black_friday" });

Variantes de objeto (por ejemplo, Dynamic Records)

import { t, type Dictionary } from "intlayer";export default {  key: "product-copy",  variant: {    id: "prod_123",    category: "books",  },  content: {    title: t({ es: "Código Limpio", en: "Clean Code", fr: "Code Propre" }),  },} satisfies Dictionary;

Uso:

// Fetches only the requested item dynamically (requires Suspense)const product = useIntlayer("product-copy", {  variant: { id: "prod_123", category: "books" },});

@intlayer/analytics: seguimiento de exposición de contenido y pruebas A/B

Un nuevo paquete opcional, @intlayer/analytics, te indica qué contenido ven realmente tus visitantes — y cierra el círculo con Collections & Variants, permitiéndote hacer pruebas A/B de contenido y medir conversiones por variante.

• Seguimiento a nivel de provider: IntlayerProvider (React / Next.js / React Native) registra automáticamente eventos page_view al cargar, al cambiar de ruta y al cambiar de idioma.
• Seguimiento a nivel de nodo: cada resolución de useIntlayer reporta un evento content_exposure — qué clave de diccionario, ruta de clave, idioma y, cuando aplica, qué variante A/B se mostró. Las exposiciones repetidas del mismo nodo dentro de una ventana de envío se combinan en un solo evento.
• Asignación determinista de A/B: getVariant(experimentKey, variants) asigna una variante a cada sesión sin ida y vuelta al servidor, por lo que no hay parpadeo antes del primer renderizado.
• useConversion(): atribuye un objetivo (registro, clic, compra…) a la variante a la que estuvo expuesta la sesión.
• Coste cero si no está instalado: mismo patrón tree-shakeable que @intlayer/editor — import() dinámico envuelto en try/catch, más una variable de entorno en tiempo de compilación (INTLAYER_ANALYTICS_ENABLED) que elimina por completo la integración del bundle para las apps que no la activan.
• Sin nuevo esquema de configuración: reutiliza editor.backendURL (endpoint de envío / auto-alojamiento) y editor.clientId (clave del proyecto, que también actúa como interruptor de activación).
• Respetuoso con la privacidad: hash anónimo de sesión (SHA-256, sin almacenar ids en bruto), sin almacenamiento de IP, geolocalización aproximada solo por país, solicitudes enviadas por lotes aproximadamente cada 20 segundos.
• Panel: una nueva página Analytics (visible en la barra lateral una vez seleccionado un proyecto) muestra usuarios activos, usuarios de hoy, usuarios de los últimos 7/30/90 días, un gráfico de evolución de visitantes y desgloses por idioma y ubicación.

npm install @intlayer/analytics

Disponible hoy para React, Next.js y React Native (a través de react-intlayer); otras integraciones de frameworks (Vue, Svelte, Angular, …) están planificadas, siguiendo el mismo patrón de despliegue que @intlayer/editor. Consulta la documentación de Analytics para la guía completa.

Plugin de Vite: Compilador Integrado y Proxy

El plugin de Vite intlayer() ahora integra el compilador y el proxy de enrutamiento de locales directamente, por lo que la mayoría de proyectos solo necesitan un único plugin en vite.config.ts:

import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [intlayer()],});

• Compilador: Se activa automáticamente cuando compiler.enabled está configurado en true y se define una ruta compiler.output. Ya no necesitas registrar intlayerCompiler() por separado.
• Proxy: Se activa automáticamente basado en la nueva opción routing.enableProxy (true por defecto). Conecta el middleware de detección de locales / redirección / reescritura en desarrollo, vista previa y SSR de producción. Ya no necesitas registrar intlayerProxy() por separado.

Opción routing.enableProxy

Una nueva opción routing.enableProxy controla si el proxy de enrutamiento de locales está activado. Por defecto es true. Desactívalo cuando quieras manejar el enrutamiento de locales por tu cuenta:

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  routing: {    enableProxy: false, // Por defecto: true  },};export default config;

Los plugins independientes intlayerCompiler() e intlayerProxy() siguen siendo exportados para configuraciones avanzadas. Registrarlos junto con intlayer() es seguro — cada plugin se deduplica a sí mismo y se ejecuta solo una vez.

Compilador deshabilitado por defecto

A partir de Intlayer v9, el compilador está deshabilitado por defecto (compiler.enabled ahora tiene el valor predeterminado false). Para habilitar la extracción de tus archivos .content.ts en tiempo de compilación, establece compiler.enabled: true en tu configuración:

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  compiler: {    enabled: true, // Por defecto: false — requerido para habilitar el compilador desde la v9    output: ({ fileName }) => `./${fileName}.content.ts`,  },};export default config;

Cuando el compilador está deshabilitado, Intlayer omite el paso de extracción en tiempo de compilación y se basa en tus diccionarios ya declarados. Habilítalo solo cuando quieras que el plugin del bundler (@intlayer/swc, @intlayer/babel o el plugin de Vite intlayer()) extraiga el contenido automáticamente.

React Native: importaciones desde un solo paquete

En una aplicación de React Native o Expo, ya no necesitas alternar entre react-intlayer y react-native-intlayer. El paquete react-native-intlayer ahora reexporta la API completa de react-intlayer (hooks, utilidades y las subrutas /format, /html, y /markdown), y su IntlayerProvider aplica automáticamente los polyfills de React Native.

Importa todo desde el paquete único react-native-intlayer:

import {  IntlayerProvider,  useIntlayer,  useLocale,} from "react-native-intlayer";

npm install intlayer react-native-intlayer

Importar desde react-intlayer sigue funcionando, pero react-native-intlayer es ahora el punto de entrada único recomendado para React Native — su provider incluye los polyfills que el provider de react-intlayer (orientado a la web) no contiene.

SDK de CMS: usa Intlayer como una base de datos de contenido headless

Intlayer v9 incluye un SDK limpio y con autenticación automática en @intlayer/api para interactuar con el CMS de forma programática: obtener proyectos, obtener diccionarios y enviarlos o actualizarlos desde tu propio servidor, scripts o CI. La autenticación (OAuth2 client_credentials) se gestiona y renueva por ti.

El SDK se divide en dos importaciones separadas para que tu bundle incluya solo los dominios que realmente usas:

1. createIntlayerCMS — un autenticador ligero que contiene las credenciales y el token gestionado (sin ningún cliente de dominio incluido).
2. dictionaryEndpoint, projectEndpoint, … — enlazadores de endpoint por dominio, cada uno importado desde su propia subruta.

import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";// La configuración es opcional: las credenciales recurren a INTLAYER_CLIENT_ID /// INTLAYER_CLIENT_SECRET resueltos por `@intlayer/config/built`.const cms = createIntlayerCMS();// Lecturaconst { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();// Escritura — usa el CMS como una base de datosawait dictionaryEndpoint(cms).pushDictionaries([myDictionary]);

Seguridad: las credenciales del CMS otorgan acceso de escritura a tu contenido. Crea el autenticador siempre en el lado del servidor — nunca envíes clientId / clientSecret al navegador.

Auto-alojamiento

Intlayer v9 incluye soporte de primera clase para ejecutar tu propia instancia de Intlayer con un solo comando — sin necesidad de cuenta en Intlayer Cloud.

curl -fsSL https://intlayer.org/install.sh | sh

El instalador descarga un docker-compose.yml y un .env, genera automáticamente los secretos necesarios y ejecuta docker compose up -d. Todo — el panel de control, la API, la base de datos, el almacenamiento de objetos y el correo electrónico transaccional — se ejecuta localmente en contenedores.

Servicios incluidos

Chromium (usado para la generación de capturas de pantalla con Puppeteer) está incluido dentro de la imagen del backend — no se necesita ningún contenedor adicional.

Notas de migración desde v8

Si estás actualizando desde v8, ten en cuenta que la v9 no incluye cambios disruptivos. Pero aquí están los cambios clave:

• Compilador deshabilitado por defecto: compiler.enabled ahora tiene el valor predeterminado false. Si dependes de la extracción de tus archivos .content.ts en tiempo de compilación, establece compiler.enabled: true en tu intlayer.config.ts.
• Plugin de Vite: El compilador y el proxy de enrutamiento de locales ahora están integrados en intlayer(). Si previamente registraste intlayerCompiler() o intlayerProxy() manualmente, puedes eliminarlos — se deduplicanautomáticamente, por lo que mantenerlos es inofensivo. Usa routing.enableProxy: false para desactivar el proxy.
• Locales y Dialectos: Si utilizas dependencias i18n externas, añade sus respectivos plugins adaptadores de compatibilidad en tu configuración o setup del bundler para reescribir automáticamente los imports.
• Selectores Personalizados: Al llamar a useIntlayer, el segundo parámetro ahora está reservado para un objeto de opciones que contiene { locale, item, variant }. Si anteriormente pasabas una cadena de locale directamente, aún puedes hacerlo, pero se recomienda usar el objeto de opciones para selecciones avanzadas.
• React Native: react-native-intlayer ahora reexporta toda la API de react-intlayer. En una aplicación React Native, importa todo desde react-native-intlayer y elimina la dependencia directa a react-intlayer. Los imports existentes de react-intlayer siguen funcionando.

Enlaces útiles

• Guía de Paquetes Adaptadores de Compatibilidad
• Diccionarios Dinámicos - Colecciones y Variantes
• Analytics - Seguimiento de exposición de contenido y pruebas A/B
• Referencia de Configuración
• SDK de CMS - Acceso programático con @intlayer/api
• Guía de Auto-alojamiento