Nuovo Intlayer v7 - Novità

Benvenuto in Intlayer v7! Questa versione principale introduce miglioramenti significativi nelle prestazioni, nella sicurezza dei tipi e nell'esperienza dello sviluppatore. Di seguito i punti salienti, con note di migrazione ed esempi pratici.

Punti salienti

• Strategia di caching per build più veloci
• Generazione migliorata dei tipi TypeScript con tipi specifici per locale
• Ottimizzazione del bundle: Locali come stringhe invece che enum
• Nuove modalità di routing: prefix-no-default, prefix-all, no-prefix, search-params
• Archiviazione locale conforme al GDPR con localStorage come predefinito
• Configurazione flessibile dello storage: cookie, localStorage, sessionStorage o multipli
• Dimensione del pacchetto Visual Editor ridotta del 30%
• Opzioni di configurazione middleware migliorate
• Comportamento aggiornato del comando fill per una migliore gestione dei contenuti
• Stabilità migliorata con aggiornamenti completi dei file di dichiarazione dei contenuti
• Gestione intelligente dei retry per una maggiore accuratezza delle traduzioni
• Parallelizzazione per un'elaborazione delle traduzioni più veloce
• Suddivisione intelligente per gestire file di grandi dimensioni entro i limiti del contesto AI

Prestazioni: Caching per build più veloci

Invece di ricostruire le dichiarazioni di contenuto con esbuild a ogni build, la versione 7 implementa una strategia di caching che accelera il processo di build.

npx intlayer build

Il nuovo sistema di caching:

• Memorizza le dichiarazioni di contenuto compilate per evitare elaborazioni ridondanti
• Rileva le modifiche e ricostruisce solo i file modificati
• Riduce significativamente i tempi di build per progetti di grandi dimensioni

TypeScript: Generazione di tipi specifici per locale

I tipi TypeScript ora vengono generati per ogni locale, offrendo un typing più forte ed eliminando i tipi unione tra tutti i locali.

Comportamento v6:

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }

Comportamento v7:

tsx;const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" }

Vantaggi:

• Completamento automatico più preciso nel tuo IDE
• Maggiore sicurezza dei tipi senza inquinamento tra tipi di diverse localizzazioni
• Prestazioni migliorate riducendo la complessità dei tipi

Ottimizzazione del bundle: Locali come stringhe

Il tipo Locales non è più un enum, il che significa che ora è completamente tree-shakeable e non appesantirà il tuo bundle con migliaia di record di localizzazione inutilizzati.

v6:

import { Locales } from "intlayer";// Enum che include tutte le localizzazioni -> non tree-shakeableconst locale: Locales = Locales.ENGLISH;

v7:

import { Locales, Locale } from "intlayer";// Tipo stringa -> completamente tree-shakeableconst locale: Locale = Locales.ENGLISH;

Poiché Locales non è più un enum, dovrai cambiare il tipo da Locales a Locale per ottenere la localizzazione come tipo.

Consulta i dettagli di implementazione per maggiori informazioni.

Nuove modalità di routing per una maggiore flessibilità

La versione 7 introduce una configurazione unificata routing.mode che sostituisce le precedenti opzioni prefixDefault e noPrefix, offrendo un controllo più granulare sulla struttura degli URL.

Modalità di routing disponibili

• prefix-no-default (predefinita): la localizzazione predefinita non ha prefisso, le altre localizzazioni sì
  • /dashboard (en) o /fr/dashboard (fr)
• prefix-all: tutte le localizzazioni hanno un prefisso
  • /en/dashboard (en) o /fr/dashboard (fr)
• no-prefix: Nessun prefisso di localizzazione negli URL (la localizzazione è gestita tramite storage/header)
  • /dashboard per tutte le localizzazioni
• search-params: La localizzazione viene passata come parametro di query
  • /dashboard?locale=en o /dashboard?locale=fr

Configurazione di base

// intlayer.config.tsexport default {  internationalization: {    locales: ["en", "fr", "es"],    defaultLocale: "en",  },  routing: {    mode: "prefix-no-default", // predefinito  },};

Conformità GDPR: storage in localStorage / cookie

La versione 7 dà priorità alla privacy dell'utente utilizzando localStorage come meccanismo di storage predefinito invece dei cookie. Questo cambiamento aiuta a rispettare il GDPR evitando la necessità del consenso per i cookie relativi alle preferenze di localizzazione.

Opzioni di configurazione dello storage

Il nuovo campo routing.storage è disponibile in aggiunta alle precedenti opzioni middleware.cookieName e middleware.serverSetCookie, offrendo configurazioni di storage flessibili:

// Disabilita lo storagestorage: false// Tipi di storage semplicistorage: 'cookie'storage: 'localStorage'storage: 'sessionStorage'// Cookie con attributi personalizzatistorage: {  type: 'cookie',  name: 'custom-locale',  domain: '.example.com',  secure: true,  sameSite: 'strict'}// localStorage con chiave personalizzatastorage: {  type: 'localStorage',  name: 'custom-locale'}// Più tipi di storage per ridondanzastorage: ['cookie', 'localStorage']

Esempio di configurazione conforme al GDPR

Per applicazioni in produzione che devono bilanciare funzionalità e conformità al GDPR:

typescript;// intlayer.config.tsexport default {  internationalization: {    locales: ["en", "fr", "es"],    defaultLocale: "en",  },  routing: {    mode: "prefix-no-default",    storage: [      {        type: "localStorage", // Archiviazione primaria (non necessita di consenso)        name: "user-locale",      },      {        type: "cookie", // Archiviazione cookie opzionale (richiede consenso)        name: "user-locale",        secure: true,        sameSite: "strict",        httpOnly: false,      },    ],  },};

Abilitare / disabilitare l'archiviazione tramite cookie

Esempio con React / Next.js:

Può essere definito globalmente:

<IntlayerProvider isCookieEnabled={false}>  <App /></IntlayerProvider>

Può essere sovrascritto localmente per ogni hook:

const { setLocale } = useLocale({ isCookieEnabled: false });setLocale("en");

Nota: I cookie sono abilitati di default. Nota: Controlla i requisiti GDPR per i cookie per il tuo caso specifico.

Visual Editor: pacchetto ridotto del 30%

Il pacchetto Visual Editor è stato ottimizzato per essere il 30% più piccolo rispetto alla versione precedente, grazie a:

• Miglioramenti delle prestazioni dell'editor di codice
• Rimozione di dipendenze non necessarie dai pacchetti core di Intlayer
• Migliore tree-shaking e bundling dei moduli

Questo si traduce in tempi di download più rapidi e prestazioni di runtime migliorate per la tua applicazione.

Comando Fill: comportamento aggiornato per una migliore gestione dei contenuti

La versione 7 introduce un comportamento migliorato per il comando fill, offrendo una gestione dei contenuti più prevedibile e flessibile:

Nuovo comportamento di fill

• fill: true - Riscrive il file corrente con il contenuto compilato per tutte le localizzazioni
• fill: "path/to/file" - Compila il file specificato senza modificare il file corrente
• fill: false - Disabilita completamente l'auto-fill

Supporto migliorato per strutture di contenuto complesse

Il comando fill ora supporta strutture complesse di dichiarazione del contenuto, inclusi:

• Oggetti composti: Dichiarazioni di contenuto che fanno riferimento ad altri oggetti
• Contenuto destrutturato: Contenuto che utilizza pattern di destrutturazione
• Riferimenti annidati: Oggetti che si richiamano a vicenda in gerarchie complesse
• Strutture di contenuto dinamiche: Contenuto con proprietà condizionali o calcolate

Vantaggi

• Intento più chiaro: Il comportamento è ora più esplicito su cosa viene modificato
• Migliore separazione: I file di contenuto possono essere mantenuti separati dalle traduzioni compilate
• Flusso di lavoro migliorato: Gli sviluppatori hanno un maggiore controllo su dove vengono memorizzate le traduzioni
• Supporto per strutture complesse: Gestione di architetture di contenuto sofisticate con molteplici oggetti interconnessi

Esempio di utilizzo

// Riscrive il file corrente con tutte le localizzazioniconst content = {  key: "example",  fill: true, // Riscrive questo file  content: {    title: "Hello World",  },};// Compila un file separato senza modificare il file correnteconst content = {  key: "example",  fill: "./translations.json", // Crea/aggiorna translations.json  content: {    title: "Hello World",  },};// Disabilita il riempimento automaticoconst content = {  key: "example",  fill: false, // Nessun riempimento automatico  content: {    title: "Hello World",  },};// Struttura di contenuto complessa con oggetti composticonst sharedContent = {  buttons: {    save: "Salva",    cancel: "Annulla",  },};const content = {  key: "complex-example",  fill: true,  content: {    // Riferimenti ad altri oggetti    sharedContent,    // Contenuto destrutturato    ...sharedContent,    // Riferimenti annidati    sections: [      {        ...sharedContent.buttons,        header: "Sezione 1",      },    ],  },};

Maggiore stabilità e gestione delle traduzioni

La versione 7 introduce diversi miglioramenti per rendere la traduzione dei contenuti più affidabile ed efficiente:

Aggiornamenti completi dei file di dichiarazione dei contenuti

Il sistema ora aggiorna i file .content.{ts,js,cjs,mjs} invece di aggiornamenti parziali, garantendo:

• Integrità dei dati: La riscrittura completa dei file previene aggiornamenti parziali che potrebbero corrompere il contenuto
• Coerenza: Tutte le localizzazioni vengono aggiornate in modo atomico, mantenendo la sincronizzazione
• Affidabilità: Riduce il rischio di file di contenuto incompleti o malformati

Gestione intelligente dei tentativi di ripetizione

I nuovi meccanismi di retry impediscono di inviare contenuti in formati errati e evitano che l'intero processo di fill si interrompa se una richiesta fallisce.

Parallelizzazione per un'elaborazione più veloce

Le operazioni di traduzione ora vengono eseguite in coda per poter essere processate in parallelo. Questo accelera significativamente il processo.

Suddivisione intelligente per file di grandi dimensioni

Strategie avanzate di chunking gestiscono file di contenuto di grandi dimensioni senza superare i limiti del contesto AI:

Esempio di flusso di lavoro

// Il file di contenuto di grandi dimensioni viene automaticamente suddiviso in chunkconst content = {  key: "large-documentation",  fill: true,  content: {    // Contenuto grande automaticamente suddiviso in chunk per l'elaborazione AI    introduction: "..." // oltre 5000 caratteri    sections: [      // Più sezioni grandi    ]  }};

Il sistema automaticamente:

1. Analizza la dimensione e la struttura del contenuto
2. Suddivide il contenuto in chunk appropriati
3. Elabora i chunk in parallelo
4. Valida e ritenta se necessario
5. Ricostruisce il file completo

Note di migrazione dalla versione v6

Configurazioni rimosse

• middleware.cookieName: Sostituito da routing.storage
• middleware.serverSetCookie: Sostituito da routing.storage
• middleware.prefixDefault: Sostituito da routing.mode
• middleware.noPrefix: Sostituito da routing.mode

Mappatura della migrazione

Mappatura della configurazione

Esempio di migrazione

Prima (v6):

export default {#### Mappatura della configurazione| Configurazione v6         | Configurazione v7                                    || ------------------------ | --------------------------------------------------- || `autoFill: xxx`          | `fill: xxx`                                         || `prefixDefault: false`   | `mode: 'prefix-no-default'`                         || `prefixDefault: true`    | `mode: 'prefix-all'`                                || `noPrefix: true`         | `mode: 'no-prefix'`                                 || `cookieName: 'my-locale'`| `storage: { type: 'cookie', name: 'my-locale' }`   || `serverSetCookie: 'never'`| `storage: false` o rimuovere il cookie dall'array di storage |#### Esempio di migrazione**Prima (v6):**```typescriptexport default {  middleware: {    headerName: "x-intlayer-locale",    cookieName: "intlayer-locale",    prefixDefault: false,    basePath: "",    serverSetCookie: "always",    noPrefix: false,  },};

Dopo (v7):

export default {  routing: {    mode: "prefix-no-default",    storage: "localStorage", // oppure 'cookie' se è necessario lo storage tramite cookie    headerName: "x-intlayer-locale",    basePath: "",  },};

Mappatura del contenuto del dizionario

Esempio di migrazione

Prima (v6):

const content = {  key: "example",  autoFill: true, // Riscrive questo file  content: {    title: "Hello World",  },};

Dopo (v7):

const content = {  key: "example",  fill: true, // Riscrive questo file  content: {    title: "Hello World",  },};

Note di migrazione da v5 a v6

Consulta le note di migrazione da v5 a v6 per maggiori informazioni.

Link utili

• Riferimento alla configurazione
• Documentazione Middleware
• Tipi TypeScript
• Linee guida GDPR sui cookie