Ottimizzazione della dimensione del bundle i18n e prestazioni

Una delle sfide più comuni con le soluzioni i18n tradizionali che si affidano a file JSON è la gestione della dimensione dei contenuti. Se gli sviluppatori non separano manualmente i contenuti in namespace, gli utenti finiscono spesso per scaricare le traduzioni per ogni pagina e potenzialmente per ogni lingua solo per visualizzare una singola pagina.

Ad esempio, un'applicazione con 10 pagine tradotte in 10 lingue potrebbe comportare il download dei contenuti di 100 pagine da parte di un utente, anche se ne serve solo una (quella corrente nella lingua corrente). Ciò comporta uno spreco di larghezza di banda e tempi di caricamento più lenti.

Intlayer risolve questo problema attraverso l'ottimizzazione in fase di build. Analizza il tuo codice per rilevare quali dizionari sono effettivamente utilizzati per ogni componente e reinserisce solo il contenuto necessario nel tuo bundle.

Sommario

Scansiona il tuo bundle

Analizzare il tuo bundle è il primo passo per identificare file JSON "pesanti" e opportunità di code-splitting. Questi strumenti generano una mappa ad albero visiva del codice compilato della tua applicazione, permettendoti di vedere esattamente quali librerie stanno consumando più spazio.

npm install -D rollup-plugin-visualizer

import { defineConfig } from "vite";import { visualizer } from "rollup-plugin-visualizer";export default defineConfig({ plugins: [   visualizer({     open: true, // Apre automaticamente il report nel tuo browser     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({ // La tua configurazione 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,   }), ],};

Come funziona

Intlayer utilizza un approccio per componente. A differenza dei file JSON globali, i tuoi contenuti sono definiti insieme o all'interno dei tuoi componenti. Durante il processo di build, Intlayer:

1. Analizza il tuo codice per trovare le chiamate a useIntlayer.
2. Costruisce il contenuto del dizionario corrispondente.
3. Sostituisce la chiamata a useIntlayer con codice ottimizzato in base alla tua configurazione.

Questo assicura che:

• Se un componente non viene importato, il suo contenuto non viene incluso nel bundle (Dead Code Elimination).
• Se un componente è caricato in modalità lazy, anche il suo contenuto viene caricato in modalità lazy.

Configurazione per piattaforma

npm install -D @intlayer/swc

npm install -D @intlayer/babel

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

Configurazione

Puoi controllare come Intlayer ottimizza il tuo bundle tramite la proprietà build nel tuo 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: {    /**     * Minimizza i dizionari per ridurre la dimensione del bundle.     */     minify: true;    /**     * Elimina le chiavi inutilizzate nei dizionari     */     purge: true;    /**     * Indica se la build deve controllare i tipi TypeScript     */    checkTypes: false;  },};export default config;

Mantenere l'opzione predefinita per optimize è raccomandato nella stragrande maggioranza dei casi.

Vedi la doc di configurazione per maggiori dettagli: Configurazione

Opzioni di Build

Le seguenti opzioni sono disponibili sotto l'oggetto di configurazione build:

Minimizzazione

Minimizzare i dizionari rimuove spazi bianchi non necessari, commenti e riduce la dimensione dei contenuti JSON. Ciò è particolarmente utile per dizionari di grandi dimensioni.

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

Nota: La minimizzazione viene ignorata se optimize è disabilitato o se il Visual Editor è abilitato (poiché l'editor ha bisogno del contenuto completo per consentire le modifiche).

Purging (Eliminazione)

Il purging assicura che solo le chiavi effettivamente utilizzate nel codice siano incluse nel bundle finale dei dizionari. Ciò può ridurre significativamente la dimensione del bundle se si hanno dizionari grandi con molte chiavi che non vengono utilizzate in ogni parte dell'applicazione.

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

Nota: Il purging viene ignorato se optimize è disabilitato.

Modalità di Importazione

Per applicazioni di grandi dimensioni, comprese diverse pagine e lingue, i tuoi file JSON possono rappresentare una parte significativa della dimensione del tuo bundle. Intlayer ti consente di controllare come vengono caricati i dizionari.

La modalità di importazione può essere definita di default a livello globale nel file intlayer.config.ts.

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

Così come per ogni dizionario nei tuoi file .content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5}}.

import { type Dictionary, t } from "intlayer";const appContent: Dictionary = {  key: "app",  importMode: "dynamic", // Sovrascrive la modalità di importazione predefinita  content: {    // ...  },};export default appContent;

L'impostazione importMode dettata come il contenuto del dizionario viene iniettato nel tuo componente. Puoi definirlo globalmente nel file intlayer.config.ts sotto l'oggetto dictionary, oppure puoi sovrascriverlo per un dizionario specifico nel suo file .content.ts.

1. Modalità Statica (default)

In modalità statica, Intlayer sostituisce useIntlayer con useDictionary e inietta il dizionario direttamente nel bundle JavaScript.

• Pro: Rendering istantaneo (sincrono), zero richieste di rete extra durante l'idratazione.
• Contro: Il bundle include le traduzioni per tutte le lingue disponibili per quel componente specifico.
• Ideale per: Single Page Applications (SPA).

Esempio di codice trasformato:

// Il tuo codiceconst content = useIntlayer("my-key");// Codice ottimizzato (Statico)const content = useDictionary({  key: "my-key",  content: {    nodeType: "translation",    translation: {      en: "My title",      fr: "Mon titolo",    },  },});

2. Modalità Dinamica

In modalità dinamica, Intlayer sostituisce useIntlayer con useDictionaryAsync. Questo utilizza import() (meccanismo simile a Suspense) per caricare in modalità lazy specificamente il JSON per la lingua corrente.

• Pro: Tree shaking a livello di lingua. Un utente che visualizza la versione inglese scaricherà solo il dizionario inglese. Il dizionario francese non viene mai caricato.
• Contro: Attiva una richiesta di rete (recupero dell'asset) per componente durante l'idratazione.
• Ideale per: Grandi blocchi di testo, articoli o applicazioni che supportano molte lingue in cui la dimensione del bundle è critica.

Esempio di codice trasformato:

// Il tuo codiceconst content = useIntlayer("my-key");// Codice ottimizzato (Dinamico)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    ),});

Quando usi importMode: 'dynamic', se hai 100 componenti che usano useIntlayer in una singola pagina, il browser tenterà 100 recuperi separati. Per evitare questo "waterfall" di richieste, raggruppa i contenuti in meno file .content (ad esempio, un dizionario per sezione della pagina) invece di uno per ogni singolo componente atomico.

3. Modalità Fetch

Si comporta in modo simile alla modalità dinamica ma tenta prima di recuperare i dizionari dall'API Intlayer Live Sync. Se la chiamata API fallisce o il contenuto non è contrassegnato per gli aggiornamenti live, ricorre all'importazione dinamica.

Vedi la documentazione CMS per maggiori dettagli: CMS

In modalità fetch, purghe e minimizzazioni non possono essere utilizzate.

Riepilogo: Statico vs Dinamico