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, Variantes y Registros Dinámicos.

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/next-i18next
• @intlayer/vue-i18n

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, Variantes y Registros Dinámicos

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",  content: [    {      question: t({        es: "¿Qué es Intlayer?",        en: "What is Intlayer?",        fr: "Qu'est-ce qu'Intlayer ?",      }),      answer: t({        es: "Un toolkit i18n.",        en: "An i18n toolkit.",        fr: "Une boîte à outils i18n.",      }),    },  ],} satisfies Dictionary;

Uso:

// Fetch all itemsconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Fetch single item by indexconst faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }

2. Variantes

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

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" });

3. Registros Dinámicos

Define diccionarios cuyas entradas se cargan dinámicamente en tiempo de ejecución a través de IDs de consulta:

import { t, type Dictionary } from "intlayer";export default {  key: "product-copy",  meta: {    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", {  id: "prod_123",  category: "books",});

Carga Dinámica y Optimizaciones del Tamaño del Bundle

Para mantener los bundles extremadamente pequeños, Intlayer v9 soporta la carga perezosa dinámica.

En tu configuración, establece importMode a 'dynamic' o 'fetch'::

export default {  dictionary: {    importMode: "dynamic", // "static" | "dynamic" | "fetch"  },};

En tiempo de compilación, @intlayer/swc y @intlayer/babel escanean tus archivos y reemplazan las llamadas a useIntlayer / getIntlayer con wrappers tree-shakeable (useDictionary / useDictionaryDynamic). Solo se carga el contenido requerido para el elemento de colección, variante o locale seleccionado, evitando que tu bundle de producción contenga traducciones no utilizadas.

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:

• 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, id }. Si anteriormente pasabas una cadena de locale directamente, aún puedes hacerlo, pero se recomienda usar el objeto de opciones para selecciones avanzadas.

Enlaces útiles

• Guía de Paquetes Adaptadores de Compatibilidad
• Diccionarios Dinámicos - Colecciones, Variantes y Registros Dinámicos
• Referencia de Configuración