Intlayer Compiler | Estrazione Automatica dei Contenuti per i18n

Cos'è Intlayer Compiler?

Il Intlayer Compiler è uno strumento potente progettato per automatizzare il processo di internazionalizzazione (i18n) nelle tue applicazioni. Scansiona il tuo codice sorgente (JSX, TSX, Vue, Svelte) alla ricerca di dichiarazioni di contenuto, le estrae e genera automaticamente i file di dizionario necessari. Questo ti permette di mantenere i contenuti co-localizzati con i tuoi componenti mentre Intlayer gestisce la sincronizzazione e la gestione dei dizionari.

Perché Usare Intlayer Compiler?

• Automazione: Elimina il copia-incolla manuale dei contenuti nei dizionari.
• Velocità: Estrazione dei contenuti ottimizzata per garantire che il processo di build rimanga veloce.
• Esperienza Sviluppatore: Mantieni le dichiarazioni di contenuto esattamente dove vengono utilizzate, migliorando la manutenibilità.
• Aggiornamenti in tempo reale: Supporta Hot Module Replacement (HMR) per un feedback immediato durante lo sviluppo.

Consulta il post sul blog Compiler vs. Declarative i18n per un confronto più approfondito.

Perché non usare Intlayer Compiler?

Sebbene il compiler offra un'esperienza eccellente "funziona subito", introduce anche alcuni compromessi di cui dovresti essere consapevole:

• Ambiguità euristica: Il compiler deve indovinare cosa è contenuto orientato all'utente rispetto alla logica dell'applicazione (ad esempio, className="active", codici di stato, ID prodotto). In codebase complesse, questo può portare a falsi positivi o stringhe mancate che richiedono annotazioni manuali ed eccezioni.
• Estrazione solo statica: L'estrazione basata sul compiler si basa sull'analisi statica. Le stringhe che esistono solo in fase di esecuzione (codici di errore API, campi CMS, ecc.) non possono essere scoperte o tradotte dal compiler da solo, quindi hai ancora bisogno di una strategia i18n di runtime complementare.

Per un confronto architetturale più approfondito, consulta il post sul blog Compiler vs. Declarative i18n.

Come alternativa, per automatizzare il tuo processo i18n mantenendo il pieno controllo del tuo contenuto, Intlayer fornisce anche un comando di auto-estrazione intlayer extract (vedi documentazione CLI), o il comando Intlayer: extract content to Dictionary dall'estensione Intlayer VS Code (vedi documentazione estensione VS Code).

Utilizzo

npm install vite-intlayer

import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Aggiunge il plugin del compiler ],});

# Per Vuenpm install @intlayer/vue-compiler# Per Sveltenpm install @intlayer/svelte-compiler

npm install @intlayer/babel

const { intlayerExtractBabelPlugin, intlayerOptimizeBabelPlugin, getExtractPluginOptions, getOptimizePluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [   // Extract content from components into dictionaries   [intlayerExtractBabelPlugin, getExtractPluginOptions()],   // Optimize imports by replacing useIntlayer with direct dictionary imports   [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()], ],};

Configurazione personalizzata

Per personalizzare il comportamento del compiler, puoi aggiornare il file intlayer.config.ts nella radice del tuo progetto.

import { type IntlayerConfig, Locales } from "intlayer";const config: IntlayerConfig = {  compiler: {    /**     * Indica se il compilatore deve essere abilitato.     * Imposta su 'build-only' per saltare il compilatore durante lo sviluppo e accelerare i tempi di avvio.     */    enabled: true,    /**     * Definisce il percorso dei file di output. Sostituisce `outputDir`.     *     * - I percorsi `./` sono risolti rispetto alla directory del componente.     * - I percorsi `/` sono risolti rispetto alla radice del progetto (`baseDir`).     *     * - L'inserimento della variabile `{{locale}}` nel percorso attiverà la generazione di dizionari separati per lingua.     *     * Esempio:     * ```ts     * {     *   // Crea file .content.ts multilingue vicino al componente     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,     *     *   // output: './{{fileName}}{{extension}}', // Equivalente usando una stringa template     * }     * ```     *     * ```ts     * {     *   // Crea file JSON centralizzati per lingua nella radice del progetto     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,     *     *   // output: '/locales/{{locale}}/{{key}}.content.json', // Equivalente usando una stringa template     * }     * ```     *     * Elenco variabili:     *   - `fileName`: Il nome del file.     *   - `key`: La chiave del contenuto.     *   - `locale`: La lingua del contenuto.     *   - `extension`: L'estensione del file.     *   - `componentFileName`: Il nome del file del componente.     *   - `componentExtension`: L'estensione del file del componente.     *   - `format`: Il formato del dizionario.     *   - `componentFormat`: Il formato del dizionario del componente.     *   - `componentDirPath`: Il percorso della directory del componente.     */    output: ({ fileName, extension }) => `./${fileName}${extension}`,    /**     * Se salvare i componenti dopo averli trasformati.     *     * - Se impostato su `true`, il compilatore riscriverà il file del componente sul disco. Pertanto la trasformazione sarà permanente e il compilatore salterà la trasformazione per il processo successivo. In questo modo, il compilatore può trasformare l'app e poi può essere rimosso.     *     * - Se impostato su `false`, il compilatore inietterà la chiamata alla funzione `useIntlayer()` nel codice solo nell'output della build, mantenendo intatta la base di codice originale. La trasformazione verrà eseguita solo in memoria.     */    saveComponents: false,    /**     * Inserisci solo il contenuto nel file generato. Utile per gli output JSON di i18next o ICU MessageFormat per lingua.     *     * - `output: ({ locale, key }) => `./locale/${locale}/${key}.json`,`     */    noMetadata: false,    /**     * Prefisso chiave dizionario     */    dictionaryKeyPrefix: "", // Aggiungi un prefisso opzionale per le chiavi del dizionario estratte  },};export default config;

Riferimento alla configurazione del compilatore

Le seguenti proprietà possono essere configurate nel blocco compiler del file intlayer.config.ts:

• enabled:

  • Tipo: boolean | 'build-only'
  • Predefinito: true
  • Descrizione: Indica se il compilatore deve essere abilitato.

• dictionaryKeyPrefix:

  • Tipo: string
  • Predefinito: ''
  • Descrizione: Prefisso per le chiavi del dizionario estratte.

• transformPattern:

  • Tipo: string | string[]
  • Predefinito: ['**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}', '!**/node_modules/**']
  • Descrizione: (Deprecato: usa invece build.traversePattern) Modelli per attraversare il codice da ottimizzare.

• excludePattern:

  • Tipo: string | string[]
  • Predefinito: ['**/node_modules/**']
  • Descrizione: (Deprecato: usa invece build.traversePattern) Modelli da escludere dall'ottimizzazione.

• output:

  • Type: FilePathPattern
  • Default: ({ key }) => 'compiler/${key}.content.json'
  • Descrizione: Definisce il percorso dei file di output. Sostituisce outputDir. Gestisce variabili dinamiche come {{locale}}, {{key}}, {{fileName}}, {{extension}}, {{format}}, {{dirPath}}, {{componentFileName}}, {{componentExtension}}, {{componentFormat}}. Può essere impostato come stringa utilizzando il formato 'my/{{var}}/path' o come funzione.
  • Nota: ./**/* I percorsi sono risolti relativamente al componente. /**/* i percorsi sono risolti relativamente al baseDir di Intlayer.
  • Nota: Se la lingua è impostata nel percorso, i dizionari verranno generati per lingua.
  • Esempio: output: ({ locale, key }) => 'compiler/${locale}/${key}.json'

• noMetadata:

  • Tipo: boolean
  • Predefinito: false
  • Descrizione: Indica se i metadati devono essere salvati nel file. Se vero, il compilatore non salverà i metadatati dei dizionari (chiave, contenitore del contenuto). Utile per output JSON i18next o ICU MessageFormat per lingua.
  • Nota: Utile se utilizzato con il plugin loadJSON.
  • Esempio: Se true: json { "key": "value" } Se false: json { "key": "value", "content": { "key": "value" } }

• saveComponents:

  • Tipo: boolean
  • Predefinito: false
  • Descrizione: Indica se i componenti debbano essere salvati dopo essere stati trasformati.
    • Se impostato su true, il compilatore riscriverà il file del componente sul disco. La trasformazione sarà permanente e il compilatore potrà essere rimosso.
    • Se impostato su false, il compilatore inietterà la chiamata alla funzione useIntlayer() nel codice solo nell'output della build, mantenendo intatta la base di codice originale. La trasformazione verrà eseguita solo in memoria.

Riempire le traduzioni mancanti

Intlayer fornisce uno strumento CLI per aiutarti a riempire le traduzioni mancanti. Puoi usare il comando intlayer per testare e riempire le traduzioni mancanti dal tuo codice.

npx intlayer test         # Testa se ci sono traduzioni mancanti

npx intlayer fill         # Riempi le traduzioni mancanti

Estrazione

Intlayer fornisce uno strumento CLI per estrarre contenuti dal tuo codice. Puoi usare il comando intlayer extract per estrarre i contenuti dal tuo codice.

npx intlayer extract

Per maggiori dettagli, fare riferimento alla documentazione CLI