Optimización del Tamaño y Rendimiento del Bundle i18n

Uno de los desafíos más comunes con las soluciones tradicionales de i18n que dependen de archivos JSON es gestionar el tamaño del contenido. Si los desarrolladores no separan manualmente el contenido en namespaces, los usuarios a menudo terminan descargando las traducciones de todas las páginas y potencialmente de todos los idiomas solo para ver una sola página.

Por ejemplo, una aplicación con 10 páginas traducidas a 10 idiomas podría hacer que un usuario descargue el contenido de 100 páginas, aunque solo necesite una (la página actual en el idioma actual). Esto conduce a un desperdicio de ancho de banda y tiempos de carga más lentos.

Para detectarlo, puedes usar analizadores de bundle como rollup-plugin-visualizer (vite), @next/bundle-analyzer (next.js) o webpack-bundle-analyzer (React CRA / Angular / etc).

Intlayer resuelve este problema mediante la optimización en tiempo de compilación. Analiza tu código para detectar qué diccionarios se usan realmente por componente y reinserta solo el contenido necesario en tu bundle.

Tabla de Contenidos

Cómo Funciona

Intlayer utiliza un enfoque por componente. A diferencia de los archivos JSON globales, tu contenido se define junto a tus componentes o dentro de ellos. Durante el proceso de compilación, Intlayer:

1. Analiza tu código para encontrar llamadas a useIntlayer.
2. Construye el contenido del diccionario correspondiente.
3. Reemplaza la llamada a useIntlayer con código optimizado basado en tu configuración.

Esto garantiza que:

• Si un componente no se importa, su contenido no se incluye en el bundle (Eliminación de Código Muerto).
• Si un componente se carga de forma lazy, su contenido también se carga de forma lazy.

Configuración por Plataforma

Next.js

Next.js requiere el plugin @intlayer/swc para manejar la transformación, ya que Next.js utiliza SWC para las compilaciones.

Este plugin está instalado por defecto porque los plugins SWC aún son experimentales para Next.js. Esto podría cambiar en el futuro.

Vite

Vite utiliza el plugin @intlayer/babel que está incluido como dependencia de vite-intlayer. La optimización está habilitada por defecto.

Webpack

Para habilitar la optimización del bundle con Intlayer en Webpack, necesitas instalar y configurar el plugin adecuado de Babel (@intlayer/babel) o SWC (@intlayer/swc).

Expo / Lynx

La optimización del bundle no está disponible aún para esta plataforma. El soporte será añadido en una versión futura.

Configuración

Puedes controlar cómo Intlayer optimiza tu bundle a través de la propiedad build en tu archivo intlayer.config.ts.

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH],    defaultLocale: Locales.ENGLISH,  },  build: {    optimize: true,    importMode: "static", // o 'dynamic'    traversePattern: ["**/*.{js,ts,mjs,cjs,jsx,tsx}", "!**/node_modules/**"],  },};export default config;

Se recomienda mantener la opción por defecto para optimize en la mayoría de los casos.

Consulta la documentación de configuración para más detalles: Configuración

Opciones de Build

Las siguientes opciones están disponibles bajo el objeto de configuración build:

Modos de Importación

La configuración importMode dicta cómo se inyecta el contenido del diccionario en tu componente.

1. Modo Estático (default)

En modo estático, Intlayer reemplaza useIntlayer por useDictionary e inyecta el diccionario directamente en el bundle de JavaScript.

• Ventajas: Renderizado instantáneo (síncrono), sin solicitudes de red adicionales durante la hidratación.
• Desventajas: El bundle incluye traducciones para todos los idiomas disponibles para ese componente específico.
• Ideal para: Aplicaciones de una sola página (SPA).

Ejemplo de código transformado:

// Tu códigoconst content = useIntlayer("my-key");// Código optimizado (Estático)const content = useDictionary({  key: "my-key",  content: {    nodeType: "translation",    translation: {      en: "My title",      fr: "Mon titre",    },  },});

2. Modo Dinámico

En modo dinámico, Intlayer reemplaza useIntlayer por useDictionaryAsync. Esto utiliza import() (mecanismo similar a Suspense) para cargar perezosamente específicamente el JSON para la localidad actual.

• Ventajas: Eliminación de código a nivel de localidad. Un usuario que vea la versión en inglés solo descargará el diccionario en inglés. El diccionario en francés nunca se carga.
• Desventajas: Genera una solicitud de red (descarga de recurso) por componente durante la hidratación.
• Ideal para: Bloques grandes de texto, artículos o aplicaciones que soportan muchos idiomas donde el tamaño del bundle es crítico.

Ejemplo de código transformado:

// Tu códigoconst content = useIntlayer("my-key");// Código optimizado (Dinámico)const content = useDictionaryAsync({  en: () =>    import(".intlayer/dynamic_dictionary/my-key/en.json").then(      (mod) => mod.default    ),  fr: () =>    import(".intlayer/dynamic_dictionary/my-key/fr.json").then(      (mod) => mod.default    ),});

Al usar importMode: 'dynamic', si tienes 100 componentes usando useIntlayer en una sola página, el navegador intentará realizar 100 solicitudes separadas. Para evitar esta "cascada" de peticiones, agrupa el contenido en menos archivos .content (por ejemplo, un diccionario por sección de página) en lugar de uno por componente átomo.

Actualmente, importMode: 'dynamic' no está completamente soportado para Vue y Svelte. Se recomienda usar importMode: 'static' para estos frameworks hasta futuras actualizaciones.

3. Modo Live

Se comporta de manera similar al modo Dinámico, pero intenta obtener primero los diccionarios desde la API de Intlayer Live Sync. Si la llamada a la API falla o el contenido no está marcado para actualizaciones en vivo, vuelve a la importación dinámica.

Consulta la documentación del CMS para más detalles: CMS

Resumen: Estático vs Dinámico

Se comporta de manera similar al modo Dinámico pero intenta obtener los diccionarios primero desde la API de Intlayer Live Sync. Si la llamada a la API falla o el contenido no está marcado para actualizaciones en vivo, vuelve a la importación dinámica.

Consulte la documentación del CMS para más detalles: CMS

Resumen: Estático vs Dinámico