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.

Indice

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 bundle 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-shakeable

const locale: Locales = Locales.ENGLISH;

v7:

import { Locales, Locale } from "intlayer";
// Tipo stringa -> completamente tree-shakeable

const 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.ts
export 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 storage
storage: false

// Tipi di storage semplici
storage: 'cookie'
storage: 'localStorage'
storage: 'sessionStorage'

// Cookie con attributi personalizzati
storage: {
  type: 'cookie',
  name: 'custom-locale',
  domain: '.example.com',
  secure: true,
  sameSite: 'strict'
}

// localStorage con chiave personalizzata
storage: {
  type: 'localStorage',
  name: 'custom-locale'
}

// Più tipi di storage per ridondanza
storage: ['cookie', 'localStorage']

Esempio di configurazione conforme al GDPR

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

typescript;
// intlayer.config.ts
export 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.

Formattazione automatica del codice: configurazione formatCommand

v7 introduce l'opzione formatCommand nella configurazione dell'editor, permettendoti di formattare automaticamente i file di contenuto quando vengono scritti da Intlayer. Questo assicura uno stile di codice e una formattazione coerenti nei tuoi file di dichiarazione di contenuto.

Se non impostato, Intlayer tenterà di rilevare il comando di formattazione automaticamente. Provando a risolvere i seguenti comandi: prettier, biome, eslint.

Configurazione

L'opzione formatCommand accetta un template di stringa dove {{file}} verrà sostituito con il percorso file effettivo:

export default {
  content: {
    formatCommand: 'bun x biome format "{{file}}" --write --log-level none',
  },
};

Formatter supportati

Puoi utilizzare qualsiasi code formatter che accetta percorsi di file come argomenti:

Usando Biome:

formatCommand: 'bun x biome format "{{file}}" --write --log-level none';

Usando Prettier:

formatCommand: 'npx prettier --write "{{file}}" --log-level silent';

Usando ESLint:

formatCommand: 'npx eslint --fix "{{file}}" --quiet';

Usando il formatter built-in di Bun:

formatCommand: 'bun format "{{file}}"';

Vantaggi

• Formattazione coerente: Tutti i file di contenuto vengono formattati automaticamente secondo le linee guida di stile del tuo progetto
• Esperienza dello sviluppatore: Non è necessario formattare manualmente i file dopo che Intlayer li scrive
• Coerenza del team: Garantisce che tutti i membri del team abbiano la stessa formattazione applicata ai file di contenuto
• Integrazione CI/CD: I file di contenuto mantengono una formattazione coerente nei flussi di lavoro automatizzati

Come funziona

Quando Intlayer scrive o aggiorna un file di dichiarazione del contenuto (.content.ts, .content.js, ecc.), esegue automaticamente il comando di formattazione specificato sul file. Il placeholder {{file}} viene sostituito con il percorso file effettivo e il comando viene eseguito nella directory base del progetto.

Configurazione del dizionario: Migliore organizzazione e struttura

v7 introduce una nuova sezione di configurazione dedicata dictionary che fornisce una migliore organizzazione per le impostazioni relative al dizionario e una gestione dei contenuti migliorata.

Nuova struttura di configurazione del dizionario

La proprietà fill è stata spostata dalla sezione content a una nuova sezione dictionary, fornendo una separazione più chiara delle responsabilità:

Configurazione v6:

export default {
  content: {
    autoFill: "./{{fileName}}.content.json",
    contentDir: ["src"],
  },
};

Configurazione v7:

export default {
  content: {
    contentDir: ["src"],
  },
  dictionary: {
    fill: "./{{fileName}}.content.json",
  },
};

Vantaggi della nuova struttura

• Organizzazione più chiara: Le impostazioni specifiche del dizionario sono ora raggruppate insieme
• Migliore separazione delle responsabilità: La scoperta dei contenuti rispetto alle operazioni del dizionario sono chiaramente separate
• Manutenibilità migliorata: Più facile da comprendere e modificare le configurazioni relative al dizionario
• Estensibilità futura: La sezione del dizionario può contenere impostazioni specifiche del dizionario aggiuntive
• Gestione dizionario completa: Include proprietà come title, live, priority, tags, version e description per creare e gestire nuovi dizionari

Utilizzo della configurazione

La configurazione del dizionario serve a due scopi principali:

1. Valori predefiniti: Definire i valori predefiniti durante la creazione di file di dichiarazione del contenuto
2. Comportamento di fallback: Fornire valori di fallback quando campi specifici non sono definiti, consentendoti di definire il comportamento dell'operazione del dizionario globalmente

La sezione del dizionario include proprietà complete per la gestione del dizionario:

• fill: Comportamento di riempimento automatico per la generazione del contenuto
• title: Titolo predefinito per i nuovi dizionari
• live: Configurazione di sincronizzazione live per gli aggiornamenti in tempo reale
• priority: Impostazioni di priorità per la risoluzione del dizionario
• tags: Tag predefiniti per l'organizzazione del contenuto
• version: Gestione della versione per gli aggiornamenti del dizionario
• description: Descrizione predefinita per i nuovi contenuti

Per ulteriori informazioni sui file di dichiarazione del contenuto e su come vengono applicate le impostazioni di configurazione, consulta la Documentazione del file di contenuto.

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 localizzazioni
const content = {
  key: "example",
  fill: true, // Riscrive questo file
  content: {
    title: "Hello World",
  },
};

// Compila un file separato senza modificare il file corrente
const content = {
  key: "example",
  fill: "./translations.json", // Crea/aggiorna translations.json
  content: {
    title: "Hello World",
  },
};

// Disabilita il riempimento automatico
const content = {
  key: "example",
  fill: false, // Nessun riempimento automatico
  content: {
    title: "Hello World",
  },
};

// Struttura di contenuto complessa con oggetti composti
const 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 chunk
const 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

Nuove configurazioni

• editor.formatCommand: Nuova opzione per la formattazione automatica del codice dei file di contenuto

Mappatura della migrazione

Mappatura della configurazione

Esempio di migrazione

Prima (v6):

export 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