Optimización del tamaño y rendimiento del bundle i18n

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

Por ejemplo, una aplicación con 10 páginas traducidas a 10 idiomas podría resultar en 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.

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

Tabla de contenidos

Escanee su bundle

Analizar su bundle es el primer paso para identificar archivos JSON "pesados" y oportunidades de división de código (code-splitting). Estas herramientas generan un mapa de árbol visual del código compilado de su aplicación, lo que le permite ver exactamente qué librerías están consumiendo más espacio.

npm install -D rollup-plugin-visualizer

import { defineConfig } from "vite";import { visualizer } from "rollup-plugin-visualizer";export default defineConfig({ plugins: [   visualizer({     open: true, // Abrir automáticamente el informe en su navegador     filename: "stats.html",     gzipSize: true,     brotliSize: true,   }), ],});

npx next experimental-analyze

npm install -D @next/bundle-analyzer

const withBundleAnalyzer = require("@next/bundle-analyzer")({ enabled: process.env.ANALYZE === "true",});module.exports = withBundleAnalyzer({ // Su configuración de Next.js});

ANALYZE=true npm run build

npm install -D webpack-bundle-analyzer

import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";export default { plugins: [   new BundleAnalyzerPlugin({     analyzerMode: "static",     reportFilename: "bundle-analyzer.html",     openAnalyzer: false,   }), ],};

Cómo funciona

Intlayer utiliza un enfoque por componente. A diferencia de los archivos JSON globales, su contenido se define junto o dentro de sus componentes. Durante el proceso de construcción, Intlayer:

1. Analiza su 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 su 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 diferida (lazy-loading), su contenido también se carga de forma diferida.

Configuración por plataforma

npm install -D @intlayer/swc

npm install -D @intlayer/babel

const { getOptimizePluginOptions, intlayerOptimizeBabelPlugin,} = require("@intlayer/babel");module.exports = { plugins: [[intlayerOptimizeBabelPlugin, getOptimizePluginOptions()]],};

Configuración

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

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH],    defaultLocale: Locales.ENGLISH,  },  dictionary: {    importMode: "dynamic",  },  build: {    /**     * Minificar los diccionarios para reducir el tamaño del bundle.     */     minify: true;    /**     * Purgar las claves no utilizadas en los diccionarios     */     purge: true;    /**     * Indica si la construcción debe verificar los tipos de TypeScript     */    checkTypes: false;  },};export default config;

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

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

Opciones de construcción

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

Minificación

Minificar diccionarios elimina espacios en blanco innecesarios, comentarios y reduce el tamaño del contenido JSON. Esto es especialmente útil para diccionarios grandes.

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  build: {    minify: true,  },};export default config;

Nota: La minificación se ignora si optimize está deshabilitado o si el Editor Visual está habilitado (ya que el editor necesita el contenido completo para permitir la edición).

Purgado

El purgado garantiza que solo las claves realmente utilizadas en su código se incluyan en el bundle final de diccionarios. Esto puede reducir significativamente el tamaño de su bundle si tiene diccionarios grandes con muchas claves que no se usan en todas las partes de su aplicación.

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  build: {    purge: true,  },};export default config;

Nota: El purgado se ignora si optimize está deshabilitado.

Modo de importación

Para aplicaciones grandes, que incluyen varias páginas y configuraciones regionales, sus archivos JSON pueden representar una parte significativa del tamaño de su bundle. Intlayer le permite controlar cómo se cargan los diccionarios.

El modo de importación puede definirse por defecto globalmente en su archivo intlayer.config.ts.

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  build: {    minify: true,  },};export default config;

Así como para cada diccionario en sus archivos .content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5}}.

import { type Dictionary, t } from "intlayer";const appContent: Dictionary = {  key: "app",  importMode: "dynamic", // Sobrescribir el modo de importación predeterminado  content: {    // ...  },};export default appContent;

La configuración importMode dicta cómo se inyecta el contenido del diccionario en su componente. Puede definirlo globalmente en el archivo intlayer.config.ts bajo el objeto dictionary, o puede sobrescribirlo para un diccionario específico en su archivo .content.ts.

1. Modo estático (default)

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

• Pros: Renderizado instantáneo (síncrono), cero solicitudes de red adicionales durante la hidratación.
• Contras: 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:

// Su códigoconst content = useIntlayer("my-key");// Código optimizado (Estatico)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 con useDictionaryAsync. Esto utiliza import() (mecanismo similar a Suspense) para cargar de forma diferida específicamente el JSON para la configuración regional actual.

• Pros: Tree shaking a nivel de locale. 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.
• Contras: Activa una solicitud de red (obtención de activos) por componente durante la hidratación.
• Ideal para: Bloques de texto grandes, artículos o aplicaciones que admiten muchos idiomas donde el tamaño del bundle es crítico.

Ejemplo de código transformado:

// Su 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 tiene 100 componentes que usan useIntlayer en una sola página, el navegador intentará 100 descargas separadas. Para evitar esta "cascada" de solicitudes, agrupe el contenido en menos archivos .content (por ejemplo, un diccionario por sección de la página) en lugar de uno por componente átomo.

3. Modo Fetch

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

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

En modo fetch, no se pueden usar el purgado y la minificación.

Resumen: Estático vs Dinámico