Documentazione della configurazione di Intlayer

import { Locales, type IntlayerConfig } from "intlayer";
import { nextjsRewrite } from "intlayer/routing";
import { syncJSON } from "@intlayer/sync-json-plugin";
import { z } from "zod";

/**
 * Esempio di file di configurazione Intlayer con tutte le opzioni disponibili.
 */
const config: IntlayerConfig = {
  /**
   * Configurazione delle impostazioni di internazionalizzazione.
   */
  internationalization: {
    /**
     * Elenco dei locale supportati nell'applicazione.
     * Predefinito: [Locales.ENGLISH]
     */
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],

    /**
     * Elenco dei locale richiesti da definire in ogni dizionario.
     * Se vuoto, tutti i locale sono richiesti in modalità `strict`.
     * Predefinito: []
     */
    requiredLocales: [Locales.ENGLISH],

    /**
     * Livello di rigore per i contenuti internazionalizzati.
     * - "strict": Errore in caso di locale dichiarati mancanti o non dichiarati.
     * - "inclusive": Avviso in caso di locale dichiarati mancanti.
     * - "loose": Accetta qualsiasi locale esistente.
     * Predefinito: "inclusive"
     */
    strictMode: "inclusive",

    /**
     * Locale predefinito utilizzato come fallback se il locale richiesto non è disponibile.
     * Predefinito: Locales.ENGLISH
     */
    defaultLocale: Locales.ENGLISH,
  },

  /**
   * Impostazioni che controllano le operazioni del dizionario e il comportamento del contenuto mancante.
   */
  dictionary: {
    /**
     * Controlla come vengono importati i dizionari.
     * - "static": Importazione statica al momento del build.
     * - "dynamic": Importazione dinamica utilizzando Suspense.
     * - "fetch": Recupero dinamico tramite l'API Live Sycn.
     * Predefinito: "static"
     */
    importMode: "static",

    /**
     * Strategia per compilare automaticamente le traduzioni mancanti utilizzando l'IA.
     * Può essere un booleano o un pattern di percorso per salvare il contenuto compilato.
     * Predefinito: true
     */
    fill: true,

    /**
     * Posizione fisica dei file del dizionario.
     * - "local": Memorizzato nel file system locale.
     * - "remote": Memorizzato nel CMS Intlayer.
     * - "hybrid": Memorizzato sia localmente che nel CMS Intlayer.
     * - "plugin" (o qualsiasi stringa personalizzata): Fornito da un plugin o da una sorgente personalizzata.
     * Predefinito: "local"
     */
    location: "local",

    /**
     * Se trasformare automaticamente il contenuto (es. Markdown in HTML).
     * Predefinito: false
     */
    contentAutoTransformation: false,
  },

  /**
   * Configurazione del routing e del middleware.
   */
  routing: {
    /**
     * Strategia di routing per locale.
     * - "prefix-no-default": Prefisso per tutti i locale tranne quello predefinito (es. /dashboard, /fr/dashboard).
     * - "prefix-all": Prefisso per tutti i locale (es. /en/dashboard, /fr/dashboard).
     * - "no-prefix": Nessun locale nell'URL.
     * - "search-params": Usa ?locale=...
     * Predefinito: "prefix-no-default"
     */
    mode: "prefix-no-default",

    /**
     * Abilita il proxy di routing delle locale di Intlayer (middleware).
     * Gestisce rilevamento della locale, redirect e rewrite in dev, preview e SSR.
     * - non impostato (auto): i server di dev e preview mantengono il routing
     *   guidato dall'URL ignorando la locale salvata in cookie e header. I prefissi
     *   vengono ancora risolti, la locale viene ancora persistita e il rilevamento
     *   Accept-Language si applica ancora. In produzione si comporta come `true`.
     * - true: comportamento completo in ogni ambiente.
     * - false: nessun routing delle locale.
     * Predefinito: undefined (auto)
     */
    enableProxy: undefined,

    /**
     * Dove memorizzare il locale selezionato dall'utente.
     * Opzioni: 'cookie', 'localStorage', 'sessionStorage', 'header' o un array di questi.
     * Predefinito: ['cookie', 'header']
     */
    storage: ["cookie", "header"],

    /**
     * Percorso base dell'URL dell'applicazione.
     * Predefinito: ""
     */
    basePath: "",

    /**
     * Regole di riscrittura URL personalizzate per percorsi specifici locali.
     */
    rewrite: nextjsRewrite({
      "/[locale]/about": {
        en: "/[locale]/about",
        fr: "/[locale]/a-propos",
      },
    }),

    /**
     * Mappa i locale ai nomi host del dominio per il routing basato sul dominio.
     * Gli URL per questi locale saranno assoluti (es. https://intlayer.cn/).
     * Il dominio implica il locale, quindi non viene aggiunto alcun prefisso di locale al percorso.
     * Predefinito: undefined
     */
    domains: {
      en: "intlayer.org",
      zh: "intlayer.cn",
    },
  },

  /**
   * Impostazioni per la scoperta e l'elaborazione dei file di contenuto.
   */
  content: {
    /**
     * Estensioni di file per scansionare i dizionari.
     * Predefinito: ['.content.ts', '.content.js', '.content.json', ecc.]
     */
    fileExtensions: [".content.ts", ".content.js", ".content.json"],

    /**
     * Directory in cui si trovano i file .content.
     * Predefinito: ["."]
     */
    contentDir: ["src"],

    /**
     * Directory del codice sorgente.
     * Utilizzato per l'ottimizzazione del build e la trasformazione del codice.
     * Predefinito: ["."]
     */
    codeDir: ["src"],

    /**
     * Pattern da escludere dalla scansione.
     * Predefinito: ['node_modules', '.intlayer', ecc.]
     */
    excludedPath: ["node_modules"],

    /**
     * Se monitorare le modifiche e rigenerare i dizionari durante lo sviluppo.
     * Predefinito: true in modalità sviluppo
     */
    watch: true,

    /**
     * Comando per formattare i file .content appena creati / aggiornati.
     */
    formatCommand: 'npx prettier --write "{{file}}"',
  },

  /**
   * Configurazione dell'Editor Visuale.
   */
  editor: {
    /**
     * Se l'editor visuale è abilitato.
     * Predefinito: false
     */
    enabled: true,

    /**
     * L'URL della tua applicazione per la convalida dell'origine.
     * Predefinito: ""
     */
    applicationURL: "http://localhost:3000",

    /**
     * La porta del server dell'editor locale.
     * Predefinito: 8000
     */
    port: 8000,

    /**
     * L'URL pubblico per l'editor.
     * Predefinito: "http://localhost:8000"
     */
    editorURL: "http://localhost:8000",

    /**
     * L'URL del CMS Intlayer.
     * Predefinito: "https://app.intlayer.org"
     */
    cmsURL: "https://app.intlayer.org",

    /**
     * L'URL del server API di backend.
     * Predefinito: "https://back.intlayer.org"
     */
    backendURL: "https://back.intlayer.org",

    /**
     * Se abilitare la sincronizzazione dei contenuti in tempo reale.
     * Predefinito: false
     */
    liveSync: true,
  },

  /**
   * Configurazione degli analytics.
   */
  analytics: {
    /**
     * Se la raccolta degli analytics è abilitata (visualizzazioni di pagina, esposizioni di contenuto, eventi A/B).
     * Richiede che `@intlayer/analytics` sia installato e che `editor.clientId` sia impostato per l'attribuzione.
     * Predefinito: true
     */
    enabled: true,

    /**
     * Millisecondi tra gli invii automatici in batch al backend.
     * Predefinito: 20000
     */
    flushInterval: 20000,

    /**
     * Frazione di sessioni da registrare, da 0 (nessuna) a 1 (tutte).
     * Predefinito: 1
     */
    sampleRate: 1,
  },

  /**
   * Impostazioni per le traduzioni e la generazione tramite IA.
   */
  ai: {
    /**
     * Fornitore IA da utilizzare.
     * Opzioni: 'openai', 'anthropic', 'mistral', 'deepseek', 'gemini', 'ollama', 'openrouter', 'alibaba', 'fireworks', 'groq', 'huggingface', 'bedrock', 'googlevertex', 'togetherai', 'lmstudio', 'moonshotai'
     * Predefinito: 'openai'
     */
    provider: "openai",

    /**
     * Modello da utilizzare per il fornitore selezionato.
     */
    model: "gpt-4o",

    /**
     * La chiave API per il fornitore.
     */
    apiKey: process.env.OPENAI_API_KEY,

    /**
     * Contesto globale per guidare l'IA durante la generazione delle traduzioni.
     */
    applicationContext: "Questa è un'applicazione di prenotazione viaggi.",

    /**
     * URL base per l'API IA.
     */
    baseURL: "http://localhost:3000",

    /**
     * Serializzazione dei dati
     *
     * Opzioni:
     * - "json": predefinito, affidabile; utilizza più token.
     * - "toon": più veloce, meno token, meno stabile di JSON.
     *
     * Predefinito: "json"
     */
    dataSerialization: "json",
  },

  /**
   * Impostazioni di build e ottimizzazione.
   */
  build: {
    /**
     * Modalità di esecuzione del build.
     * - "auto": Build automatica durante il build dell'applicazione.
     * - "manual": Richiede il comando di build esplicito.
     * Predefinito: "auto"
     */
    mode: "auto",

    /**
     * Se ottimizzare il bundle dell'applicazione rimuovendo i dizionari inutilizzati.
     * Predefinito: true in produzione
     */
    optimize: true,

    /**
     * Minifica i dizionari per ridurre le dimensioni del bundle.
     * Predefinito: false
     *
     * Note:
     * - Questa opzione verrà ignorata se `optimize` è disabilitato.
     * - Questa opzione verrà ignorata se `editor.enabled` è vero.
     */
    minify: true,

    /**
     * Rimuovi le chiavi non utilizzate nei dizionari.
     * Predefinito: false
     *
     * Note:
     * - Questa opzione verrà ignorata se `optimize` è disabilitato.
     */
    purge: true,

    /**
     * Raggruppare i chunk di dizionario per lingua in base al confine di
     * code-splitting che li utilizza, così una pagina caricata in modo lazy
     * recupera il suo contenuto con una sola richiesta.
     * Predefinito: true
     *
     * Nota:
     * - Si applica solo ai dizionari che usano `importMode: 'dynamic'`.
     */
    chunkGrouping: true,

    /**
     * Caricare un dizionario insieme al chunk che lo utilizza, invece di
     * recuperarlo una volta che quel chunk viene renderizzato. I lettori vengono
     * renderizzati in modo sincrono invece di sospendersi, quindi la navigazione
     * non mostra più un lampeggio di caricamento.
     * Predefinito: true
     *
     * Nota:
     * - Viene attesa solo la lingua risolta, quindi la pagina scarica solo la
     *   lingua che mostra.
     */
    dictionariesPreload: true,

    /**
     * Formato di output per i file del dizionario generati.
     * Predefinito: ['cjs', 'esm']
     */
    outputFormat: ["cjs", "esm"],

    /**
     * Se controllare i tipi di TypeScript durante il build.
     * Predefinito: false
     */
    checkTypes: false,
  },

  /**
   * Configurazione del Logger.
   */
  log: {
    /**
     * Livello di logging.
     * - "default": Logging standard.
     * - "verbose": Logging di debug dettagliato.
     * - "disabled": Nessun logging.
     * Predefinito: "default"
     */
    mode: "default",

    /**
     * Prefisso per tutti i messaggi nei log.
     * Predefinito: "[intlayer]"
     */
    prefix: "[intlayer]",
  },

  /**
   * Configurazione di sistema (per uso avanzato)
   */
  system: {
    /**
     * Directory in cui memorizzare i dizionari localizzati.
     */
    dictionariesDir: ".intlayer/dictionary",

    /**
     * Directory per l'aumento del modulo (module augmentation).
     */
    moduleAugmentationDir: ".intlayer/types",

    /**
     * Directory in cui memorizzare i dizionari non fusi (unmerged).
     */
    unmergedDictionariesDir: ".intlayer/unmerged_dictionary",

    /**
     * Directory in cui memorizzare i tipi del dizionario.
     */
    typesDir: ".intlayer/types",

    /**
     * Directory in cui si trovano i file principali dell'applicazione.
     */
    mainDir: ".intlayer/main",

    /**
     * Directory in cui si trovano i file di configurazione compilati.
     */
    configDir: ".intlayer/config",

    /**
     * Directory per i file di cache.
     */
    cacheDir: ".intlayer/cache",
  },

  /**
   * Configurazione del compilatore (per uso avanzato)
   */
  compiler: {
    /**
     * Se il compilatore è abilitato.
     *
     * - false: disabilita il compilatore.
     * - true: abilita il compilatore.
     * - "build-only": salta il compilatore durante lo sviluppo per un avvio più rapido.
     *
     * Predefinito: false
     */
    enabled: true,

    /**
     * Determina il percorso del file di output. Sostituisce `outputDir`.
     *
     * - I percorsi che iniziano con `./` sono risolti rispetto alla directory del componente.
     * - I percorsi che iniziano con `/` sono risolti rispetto alla directory base del progetto (`baseDir`).
     *
     * - La presenza della variabile `{{locale}}` nel percorso abilita la generazione del dizionario per locale.
     *
     * Esempi:
     * ```ts
     * {
     *   // Genera file .content.ts multilingue accanto al componente
     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,
     *
     *   // output: './{{fileName}}{{extension}}', // Equivalente tramite stringa template
     * }
     * ```
     *
     * ```ts
     * {
     *   // Genera JSON centralizzati per locale nella base del progetto
     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,
     *
     *   // output: '/locales/{{locale}}/{{key}}.content.json', // Equivalente tramite stringa template
     * }
     * ```
     *
     * Elenco delle variabili:
     *   - `fileName`: Nome del file.
     *   - `key`: Chiave del contenuto.
     *   - `locale`: Locale del contenuto.
     *   - `extension`: Estensione del file.
     *   - `componentFileName`: Nome del file del componente.
     *   - `componentExtension`: Estensione del file del componente.
     *   - `format`: Formato del dizionario.
     *   - `componentFormat`: Formato del dizionario del componente.
     *   - `componentDirPath`: Percorso della directory del componente.
     */
    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,

    /**
     * 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,

    /**
     * Conserva solo il contenuto nel file generato. Utile per formati i18next o output JSON ICU MessageFormat per locale.
     */
    noMetadata: false,

    /**
     * Prefisso della chiave del dizionario
     */
    dictionaryKeyPrefix: "", // Aggiungi un prefisso opzionale alle chiavi del dizionario estratto
  },

  /**
   * Schemi personalizzati per la convalida del contenuto del dizionario.
   */
  schemas: {
    "my-schema": z.object({
      title: z.string(),
    }),
  },

  /**
   * Configurazione del dizionario.
   */
  dictionary: {
    /**
     * Controlla come vengono importati i dizionari.
     * - "static": Importato staticamente in fase di compilazione.
     * - "dynamic": Importato dinamicamente usando Suspense.
     * - "fetch": Recuperato dinamicamente tramite API di sincronizzazione live.
     */
    importMode: "static",

    /**
     * Il formato del messaggio predefinito per tutti i dizionari nel progetto.
     * - 'intlayer': Formato intlayer nativo (predefinito).
     * - 'icu': Formato del messaggio ICU.
     * - 'i18next': Formato i18next.
     * - 'vue-i18n': Formato Vue I18n.
     * - 'po': Formato GNU Gettext PO.
     */
    format: "icu",
  },

  /**
   * Configurazione dei plugin.
   */
  plugins: [
    syncJSON({
      format: "icu",
      source: ({ locale }) => `./messages/${locale}.json`,
    }),
  ],
};

export default config;

routing: {
  mode: "prefix-no-default", // Strategia di fallback
  rewrite: nextjsRewrite({
    "/about": {
      en: "/about",
      fr: "/a-propos",
    },
    "/product/[slug]": {
      en: "/product/[slug]",
      fr: "/produit/[slug]",
    },
    "/blog/[category]/[id]": {
      en: "/blog/[category]/[id]",
      fr: "/journal/[category]/[id]",
    },
  }),
}

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default",
    storage: "localStorage",
    basePath: "",
  },
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default",
    storage: [
      {
        type: "localStorage",
        name: "user-locale",
      },
      {
        type: "cookie",
        name: "user-locale",
        secure: true,
        sameSite: "strict",
        httpOnly: false,
      },
    ],
    basePath: "",
  },
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "search-params",
    storage: "localStorage",
    basePath: "",
  },
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "no-prefix",
    storage: {
      type: "sessionStorage",
      name: "app-locale",
    },
    basePath: "/my-app",
  },
};

export default config;

// intlayer.config.ts
import { nextjsRewrite } from "intlayer/routing";

const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default", // Fallback per i percorsi non riscritti
    storage: "cookie",
    rewrite: nextjsRewrite({
      "/about": {
        en: "/about",
        fr: "/a-propos",
      },
      "/product/[slug]": {
        en: "/product/[slug]",
        fr: "/produit/[slug]",
      },
      "/blog/[category]/[id]": {
        en: "/blog/[category]/[id]",
        fr: "/journal/[category]/[id]",
      },
    }),
  },
};

export default config;

dictionary: {
  fill: {
    en: "/locales/en/{{key}}.content.json",
    fr: ({ key }) => `/locales/fr/${key}.content.json`,
    es: false,
  },
};