Documentazione di Configurazione di Intlayer

Panoramica

I file di configurazione di Intlayer permettono la personalizzazione di vari aspetti del plugin, come l'internazionalizzazione, il middleware e la gestione dei contenuti. Questo documento fornisce una descrizione dettagliata di ogni proprietà nella configurazione.

Formati di File di Configurazione Supportati

Intlayer accetta formati di file di configurazione JSON, JS, MJS e TS:

• intlayer.config.ts
• intlayer.config.js
• intlayer.config.json
• intlayer.config.cjs
• intlayer.config.mjs
• .intlayerrc

Esempio di file di configurazione

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH], // località supportate  },  content: {    autoFill: "./{{fileName}}.content.json", // percorso per il riempimento automatico del contenuto    contentDir: ["src", "../ui-library"], // directory dei contenuti  },  middleware: {    noPrefix: false, // se true, disabilita il prefisso della località  },  editor: {    applicationURL: "https://example.com", // URL dell'applicazione per l'editor  },  ai: {    apiKey: process.env.OPENAI_API_KEY, // chiave API per AI    applicationContext: "This is a test application", // contesto dell'applicazione per AI  },  build: {    importMode: "dynamic", // modalità di importazione durante la build  },};export default config;

Riferimento alla Configurazione

Le sezioni seguenti descrivono le varie impostazioni di configurazione disponibili per Intlayer.

Configurazione dell'Internazionalizzazione

Definisce le impostazioni relative all'internazionalizzazione, incluse le località disponibili e la località predefinita per l'applicazione.

Proprietà

• locales:

  • Tipo: string[]
  • Predefinito: ['en']
  • Descrizione: L'elenco delle località supportate nell'applicazione.
  • Esempio: ['en', 'fr', 'es']
• requiredLocales:
  • Tipo: string[]
  • Predefinito: []
  • Descrizione: L'elenco delle località obbligatorie nell'applicazione.
  • Esempio: []
  • Nota: Se vuoto, tutte le localizzazioni sono richieste in modalità strict.
  • Nota: Assicurarsi che le localizzazioni richieste siano anche definite nel campo locales.

• strictMode:

  • Tipo: string
  • Predefinito: inclusive
  • Descrizione: Garantisce implementazioni rigorose dei contenuti internazionalizzati usando typescript.
  • Nota: Se impostato su "strict", la funzione di traduzione t richiederà che ogni localizzazione dichiarata sia definita. Se manca una localizzazione, o se una localizzazione non è dichiarata nella tua configurazione, genererà un errore.
  • Nota: Se impostato su "inclusive", la funzione di traduzione t richiederà che ogni localizzazione dichiarata sia definita. Se manca una localizzazione, genererà un avviso. Ma accetterà se una localizzazione non è dichiarata nella tua configurazione, ma esiste.
  • Nota: Se impostato su "loose", la funzione di traduzione t accetterà qualsiasi locale esistente.

• defaultLocale:

  • Tipo: string
  • Predefinito: 'en'
  • Descrizione: La locale predefinita utilizzata come fallback se la locale richiesta non viene trovata.
  • Esempio: 'en'
  • Nota: Viene utilizzata per determinare la locale quando nessuna è specificata nell'URL, nel cookie o nell'header.

Configurazione dell'Editor

Definisce le impostazioni relative all'editor integrato, incluso il porto del server e lo stato attivo.

Proprietà

• applicationURL:
  • Tipo: string
  • Predefinito: http://localhost:3000
  • Descrizione: L'URL dell'applicazione. Usato per limitare l'origine dell'editor per motivi di sicurezza.
  • Esempio:
    • 'http://localhost:3000'
    • 'https://example.com'

• process.env.INTLAYER_EDITOR_URL

  • Nota: L'URL dell'applicazione. Utilizzato per limitare l'origine dell'editor per motivi di sicurezza. Se impostato a '*', l'editor è accessibile da qualsiasi origine.

• port:

  • Tipo: number
  • Predefinito: 8000
  • Descrizione: La porta utilizzata dal server dell'editor visuale.

• editorURL:

  • Tipo: string
  • Predefinito: 'http://localhost:8000'
  • Descrizione: L'URL del server dell'editor. Utilizzato per limitare l'origine dell'editor per motivi di sicurezza.
    • 'http://localhost:3000'
    • 'https://example.com'
    • process.env.INTLAYER_EDITOR_URL
  • Nota: L'URL del server dell'editor da raggiungere dall'applicazione. Usato per limitare le origini che possono interagire con l'applicazione per motivi di sicurezza. Se impostato a '*', l'editor è accessibile da qualsiasi origine. Deve essere impostato se la porta viene cambiata o se l'editor è ospitato su un dominio diverso.

• cmsURL:

  • Tipo: string
  • Predefinito: 'https://intlayer.org'
  • Descrizione: L'URL del CMS Intlayer.
  • Esempio: 'https://intlayer.org'
  • Nota: L'URL del CMS Intlayer.

• backendURL:

  • Tipo: string
  • Predefinito: https://back.intlayer.org
  • Descrizione: L'URL del server backend.
  • Esempio: http://localhost:4000

• enabled:

  • Tipo: boolean
  • Predefinito: true
  • Descrizione: Indica se l'applicazione interagisce con l'editor visuale.
  • Esempio: process.env.NODE_ENV !== 'production'
  • Nota: Se true, l'editor sarà in grado di interagire con l'applicazione. Se false, l'editor non potrà interagire con l'applicazione. In ogni caso, l'editor può essere abilitato solo dall'editor visuale. Disabilitare l'editor per ambienti specifici è un modo per rafforzare la sicurezza.

• clientId:

  • Tipo: string | undefined
  • Predefinito: undefined
  • Descrizione: clientId e clientSecret permettono ai pacchetti intlayer di autenticarsi con il backend utilizzando l'autenticazione oAuth2. Un token di accesso viene utilizzato per autenticare l'utente relativo al progetto. Per ottenere un token di accesso, vai su https://intlayer.org/dashboard/project e crea un account.
  • Esempio: true
  • Nota: Importante: clientId e clientSecret devono essere mantenuti segreti e non condivisi pubblicamente. Assicurati di conservarli in un luogo sicuro, come le variabili d'ambiente.

• clientSecret:

  • Tipo: string | undefined
  • Predefinito: undefined
  • Descrizione: clientId e clientSecret permettono ai pacchetti intlayer di autenticarsi con il backend utilizzando l'autenticazione oAuth2. Un token di accesso viene utilizzato per autenticare l'utente relativo al progetto. Per ottenere un token di accesso, vai su https://intlayer.org/dashboard/project e crea un account.
  • Esempio: true
  • Nota: Importante: clientId e clientSecret devono essere mantenuti segreti e non condivisi pubblicamente. Assicurati di conservarli in un luogo sicuro, come variabili d'ambiente.

• dictionaryPriorityStrategy:

  • Tipo: string
  • Predefinito: 'local_first'
  • Descrizione: La strategia per dare priorità ai dizionari nel caso in cui siano presenti sia dizionari locali che remoti. Se impostato su 'distant_first', l'applicazione darà priorità ai dizionari remoti rispetto a quelli locali. Se impostato su 'local_first', l'applicazione darà priorità ai dizionari locali rispetto a quelli remoti.
  • Esempio: 'distant_first'

• liveSync:

  • Tipo: boolean
  • Predefinito: false
  • Descrizione: Indica se il server dell'applicazione deve ricaricare dinamicamente il contenuto dell'applicazione quando viene rilevata una modifica nel CMS / Visual Editor / Backend.
  • Esempio: true
  • Nota: Ad esempio, quando un nuovo dizionario viene aggiunto o aggiornato, l'applicazione aggiornerà il contenuto da visualizzare nella pagina.
  • Nota: La sincronizzazione live necessita di esternalizzare il contenuto dell'applicazione su un altro server. Ciò significa che può influire leggermente sulle prestazioni dell'applicazione. Per limitare questo, consigliamo di ospitare l'applicazione e il server di sincronizzazione live sulla stessa macchina. Inoltre, la combinazione di sincronizzazione live e optimize può generare un numero considerevole di richieste al server di sincronizzazione live. A seconda della tua infrastruttura, consigliamo di testare entrambe le opzioni e la loro combinazione.

• liveSyncPort:

  • Tipo: number
  • Predefinito: 4000
  • Descrizione: La porta del server di sincronizzazione live.
  • Esempio: 4000
  • Nota: La porta del server di sincronizzazione live.

• liveSyncURL:

  • Tipo: string
  • Predefinito: 'http://localhost:{liveSyncPort}'
  • Descrizione: L'URL del server di sincronizzazione live.
  • Esempio: 'https://example.com'
  • Nota: Punta a localhost di default ma può essere cambiato in qualsiasi URL nel caso di un server di sincronizzazione live remoto.

Configurazione del Middleware

Impostazioni che controllano il comportamento del middleware, incluso come l'applicazione gestisce cookie, header e prefissi URL per la gestione della localizzazione.

Proprietà

• headerName:

  • Tipo: string
  • Predefinito: 'x-intlayer-locale'
  • Descrizione: Il nome dell'header HTTP usato per determinare la localizzazione.
  • Esempio: 'x-custom-locale'
  • Nota: Utile per la determinazione della localizzazione basata su API.

• cookieName:

  • Tipo: string
  • Predefinito: 'intlayer-locale'
  • Descrizione: Il nome del cookie usato per memorizzare la localizzazione.
  • Esempio: 'custom-locale'
  • Nota: Utilizzato per mantenere la localizzazione tra le sessioni.

• prefixDefault:

  • Tipo: boolean
  • Predefinito: false
  • Descrizione: Se includere la localizzazione predefinita nell'URL.
  • Esempio: true
  • Nota:
    • Se true e defaultLocale = 'en': percorso = /en/dashboard o /fr/dashboard
    • Se false e defaultLocale = 'en': percorso = /dashboard o /fr/dashboard

• basePath:

  • Tipo: string
  • Predefinito: ''
  • Descrizione: Il percorso base per gli URL dell'applicazione.
  • Esempio: '/my-app'
  • Nota:
    • Se l'applicazione è ospitata su https://example.com/my-app
    • Il percorso base è '/my-app'
    • L'URL sarà https://example.com/my-app/en
    • Se il percorso base non è impostato, l'URL sarà https://example.com/en

• serverSetCookie:

  • Tipo: string
  • Predefinito: 'always'
  • Descrizione: Regola per impostare il cookie della lingua sul server.
  • Opzioni: 'always', 'never'
  • Esempio: 'never'
  • Nota: Controlla se il cookie della lingua viene impostato ad ogni richiesta o mai.

• noPrefix:

  • Tipo: boolean
  • Predefinito: false
  • Descrizione: Se omettere il prefisso della lingua dagli URL.
  • Esempio: true
  • Nota:
    • Se true: Nessun prefisso nell'URL
    • Se false: Prefisso nell'URL
    • Esempio con basePath = '/my-app':
      • Se noPrefix = false: l'URL sarà https://example.com/my-app/en
      • Se noPrefix = true: l'URL sarà https://example.com

Configurazione del Contenuto

Impostazioni relative alla gestione del contenuto all'interno dell'applicazione, inclusi nomi delle directory, estensioni dei file e configurazioni derivate.

Proprietà

• autoFill:

  • Tipo: boolean | string | { [key in Locales]?: string }
  • Predefinito: undefined
  • Descrizione: Indica come il contenuto dovrebbe essere compilato automaticamente usando l'IA. Può essere dichiarato globalmente nel file intlayer.config.ts.
  • Esempio: true
  • Esempio: './{{fileName}}.content.json'
  • Esempio: { fr: './{{fileName}}.fr.content.json', es: './{{fileName}}.es.content.json' }
  • Nota: La configurazione di auto compilazione. Può essere:
    • booleano: Abilita l'auto compilazione per tutte le localizzazioni
    • stringa: Percorso a un singolo file o modello con variabili
    • oggetto: Percorsi file per ogni localizzazione

• watch:

  • Tipo: boolean
  • Predefinito: process.env.NODE_ENV === 'development'
  • Descrizione: Indica se Intlayer deve monitorare le modifiche nei file di dichiarazione del contenuto nell'app per ricostruire i dizionari correlati.

• fileExtensions:

  • Tipo: string[]
  • Predefinito: ['.content.ts', '.content.js', '.content.cjs', '.content.mjs', '.content.json', '.content.tsx', '.content.jsx']
  • Descrizione: Estensioni dei file da cercare durante la costruzione dei dizionari.
  • Esempio: ['.data.ts', '.data.js', '.data.json']
  • Nota: Personalizzare le estensioni dei file può aiutare a evitare conflitti.

• baseDir:

  • Tipo: string
  • Predefinito: process.cwd()
  • Descrizione: La directory base per il progetto.
  • Esempio: '/path/to/project'
  • Nota: Viene utilizzata per risolvere tutte le directory relative a Intlayer.

• dictionaryOutput:

  • Tipo: string[]
  • Predefinito: ['intlayer']
  • Descrizione: Il tipo di output del dizionario da utilizzare, ad esempio 'intlayer' o 'i18next'.

• contentDir:

  • Tipo: string[]
  • Predefinito: ['.']
  • Esempio: ['src', '../../ui-library', require.resolve("@my-package/content")]
  • Descrizione: Il percorso della directory dove è memorizzato il contenuto.

• dictionariesDir:

  • Tipo: string
  • Predefinito: '.intlayer/dictionaries'
  • Descrizione: Il percorso della directory per memorizzare risultati intermedi o output.

• moduleAugmentationDir:

  • Tipo: string
  • Predefinito: '.intlayer/types'
  • Descrizione: Directory per l'augmentation dei moduli, che permette migliori suggerimenti IDE e controllo dei tipi.
  • Esempio: 'intlayer-types'
  • Nota: Assicurarsi di includere questa directory in tsconfig.json.

• unmergedDictionariesDir:

  • Tipo: string
  • Predefinito: '.intlayer/unmerged_dictionary'
  • Descrizione: La directory per memorizzare dizionari non uniti.
  • Esempio: 'translations'

• dictionariesDir:

  • Tipo: string
  • Predefinito: '.intlayer/dictionary'
  • Descrizione: La directory per memorizzare i dizionari di localizzazione.
  • Esempio: 'translations'

• i18nextResourcesDir:

  • Tipo: string
  • Predefinito: 'i18next_dictionary'
  • Descrizione: La directory per memorizzare i dizionari i18n.
  • Esempio: 'translations'
  • Nota: Assicurarsi che questa directory sia configurata per il tipo di output i18next.

• typesDir:

  • Tipo: string
  • Predefinito: 'types'
  • Descrizione: La directory per memorizzare i tipi di dizionario.
  • Esempio: 'intlayer-types'

• mainDir:

  • Tipo: string
  • Predefinito: 'main'
  • Descrizione: La directory dove sono memorizzati i file principali dell'applicazione.
  • Esempio: 'intlayer-main'

• excludedPath:

  • Tipo: string[]
  • Predefinito: ['node_modules']
  • Descrizione: Directory escluse dalla ricerca dei contenuti.
  • Nota: Questa impostazione non è ancora utilizzata, ma è prevista per implementazioni future.

Configurazione del Logger

Impostazioni che controllano il logger, incluso il prefisso da utilizzare.

Proprietà

• mode:

  • Tipo: string
  • Predefinito: default
  • Descrizione: Indica la modalità del logger.
  • Opzioni: default, verbose, disabled
  • Esempio: default
  • Nota: La modalità del logger. La modalità verbose registra più informazioni, ma può essere usata per scopi di debug. La modalità disabled disabilita il logger.

• prefix:

  • Tipo: string
  • Predefinito: '[intlayer] '
  • Descrizione: Il prefisso del logger.
  • Esempio: '[my custom prefix] '
  • Nota: Il prefisso del logger.

Configurazione AI

Impostazioni che controllano le funzionalità AI di Intlayer, inclusi provider, modello e chiave API.

Questa configurazione è opzionale se sei registrato sul Cruscotto Intlayer utilizzando una chiave di accesso. Intlayer gestirà automaticamente la soluzione AI più efficiente e conveniente per le tue esigenze. Utilizzare le opzioni predefinite garantisce una migliore manutenzione a lungo termine poiché Intlayer aggiorna continuamente per utilizzare i modelli più rilevanti.

Se preferisci utilizzare la tua chiave API o un modello specifico, puoi definire la tua configurazione AI personalizzata. Questa configurazione AI sarà utilizzata globalmente in tutto il tuo ambiente Intlayer. I comandi CLI utilizzeranno queste impostazioni come valori predefiniti per i comandi (ad esempio fill), così come l’SDK, l’Editor Visivo e il CMS. Puoi sovrascrivere questi valori predefiniti per casi d’uso specifici utilizzando i parametri dei comandi.

Intlayer supporta più provider AI per una maggiore flessibilità e scelta. I provider attualmente supportati sono:

• OpenAI (predefinito)
• Anthropic Claude
• Mistral AI
• DeepSeek
• Google Gemini
• Meta Llama

Proprietà

• provider:

  • Tipo: string
  • Predefinito: 'openai'
  • Descrizione: Il provider da utilizzare per le funzionalità AI di Intlayer.
  • Opzioni: 'openai', 'anthropic', 'mistral', 'deepseek', 'gemini'
  • Esempio: 'anthropic'
  • Nota: Diversi provider potrebbero richiedere chiavi API differenti e avere modelli di prezzo diversi.

• model:

  • Tipo: string
  • Predefinito: Nessuno
  • Descrizione: Il modello da utilizzare per le funzionalità AI di Intlayer.
  • Esempio: 'gpt-4o-2024-11-20'
  • Nota: Il modello specifico da utilizzare varia a seconda del provider.

• temperature:

  • Tipo: number
  • Predefinito: Nessuno
  • Descrizione: La temperatura controlla la casualità delle risposte dell'AI.
  • Esempio: 0.1
  • Nota: Una temperatura più alta rende l'AI più creativa e meno prevedibile.

• apiKey:

  • Tipo: string
  • Predefinito: Nessuno
  • Descrizione: La tua chiave API per il provider selezionato.
  • Esempio: process.env.OPENAI_API_KEY
  • Nota: Importante: le chiavi API devono essere mantenute segrete e non condivise pubblicamente. Assicurati di conservarle in un luogo sicuro, come le variabili d'ambiente.

• applicationContext:

  • Tipo: string
  • Predefinito: Nessuno
  • Descrizione: Fornisce un contesto aggiuntivo sulla tua applicazione al modello AI, aiutandolo a generare traduzioni più accurate e contestualmente appropriate. Questo può includere informazioni sul dominio della tua app, il pubblico target, il tono o terminologia specifica.

Configurazione della Build

Impostazioni che controllano come Intlayer ottimizza e costruisce l'internazionalizzazione della tua applicazione.

Le opzioni di build si applicano ai plugin @intlayer/babel e @intlayer/swc.

In modalità di sviluppo, Intlayer utilizza importazioni statiche per i dizionari per semplificare l'esperienza di sviluppo.

Quando ottimizzato, Intlayer sostituirà le chiamate ai dizionari per ottimizzare il chunking, in modo che il bundle finale importi solo i dizionari effettivamente utilizzati.

Proprietà

• optimize:

  • Tipo: boolean
  • Predefinito: process.env.NODE_ENV === 'production'
  • Descrizione: Controlla se la build deve essere ottimizzata.
  • Esempio: true
  • Nota: Quando abilitato, Intlayer sostituirà tutte le chiamate ai dizionari per ottimizzare il chunking. In questo modo il bundle finale importerà solo i dizionari utilizzati. Tutte le importazioni rimarranno come importazioni statiche per evitare l'elaborazione asincrona durante il caricamento dei dizionari.
  • Nota: Intlayer sostituirà tutte le chiamate di useIntlayer con la modalità definita dall'opzione importMode e getIntlayer con getDictionary.
  • Nota: Questa opzione si basa sui plugin @intlayer/babel e @intlayer/swc.
  • Nota: Assicurarsi che tutte le chiavi siano dichiarate staticamente nelle chiamate a useIntlayer. Es. useIntlayer('navbar').

• importMode:

  • Tipo: 'static' | 'dynamic' | 'live'
  • Predefinito: 'static'
  • Descrizione: Controlla come vengono importati i dizionari.
  • Esempio: 'dynamic'
  • Nota: Modalità disponibili:
    • "static": I dizionari sono importati staticamente. Sostituisce useIntlayer con useDictionary.
    • "dynamic": I dizionari sono importati dinamicamente usando Suspense. Sostituisce useIntlayer con useDictionaryDynamic.
  • "live": I dizionari vengono recuperati dinamicamente utilizzando l'API di sincronizzazione live. Sostituisce useIntlayer con useDictionaryFetch.
  • Nota: Gli import dinamici si basano su Suspense e possono influire leggermente sulle prestazioni di rendering.
  • Nota: Se disabilitato, tutte le localizzazioni verranno caricate contemporaneamente, anche se non vengono utilizzate.
  • Nota: Questa opzione si basa sui plugin @intlayer/babel e @intlayer/swc.
  • Nota: Assicurarsi che tutte le chiavi siano dichiarate staticamente nelle chiamate a useIntlayer, ad esempio useIntlayer('navbar').
  • Nota: Questa opzione verrà ignorata se optimize è disabilitato.
  • Nota: Se impostato su "live", solo i dizionari che includono contenuti remoti e sono contrassegnati come "live" saranno trasformati in modalità live. Gli altri saranno importati dinamicamente in modalità "dynamic" per ottimizzare il numero di richieste di fetch e le prestazioni di caricamento.
  • Nota: La modalità live utilizzerà l'API di sincronizzazione live per recuperare i dizionari. Se la chiamata API fallisce, i dizionari saranno importati dinamicamente in modalità "dynamic".
  • Nota: Questa opzione non influenzerà le funzioni getIntlayer, getDictionary, useDictionary, useDictionaryAsync e useDictionaryDynamic.

• traversePattern:

  • Tipo: string[]
  • Predefinito: ['**/*.{js,ts,mjs,cjs,jsx,tsx,mjx,cjx}', '!**/node_modules/**']
  • Descrizione: Pattern che definiscono quali file devono essere attraversati durante l'ottimizzazione.
    • Esempio: ['src/**/*.{ts,tsx}', '../ui-library/**/*.{ts,tsx}', '!**/node_modules/**']
  • Nota: Usare questo per limitare l'ottimizzazione ai file di codice rilevanti e migliorare le prestazioni di build.
  • Nota: Questa opzione sarà ignorata se optimize è disabilitato.
  • Nota: Usare pattern glob.