Documentazione della Configurazione di Intlayer

Panoramica

I file di configurazione di Intlayer consentono 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.

Supporto per File di Configurazione

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],  },  content: {    contentDir: ["src", "../ui-library"],  },  middleware: {    noPrefix: false,  },  editor: {    applicationURL: "https://example.com",  },  ai: {    apiKey: process.env.OPENAI_API_KEY,    applicationContext: "This is a test application",  },  build: {    importMode: "dynamic",  },};export default config;

Riferimento Configurazione

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

Configurazione Internazionalizzazione

Definisce le impostazioni relative all'internazionalizzazione, inclusi i locali disponibili e il locale predefinito per l'applicazione.

Proprietà

• locales:

  • Tipo: string[]
  • Predefinito: ['en']
  • Descrizione: L'elenco dei locali supportati nell'applicazione.
  • Esempio: ['en', 'fr', 'es']
• requiredLocales:
  • Tipo: string[]
  • Predefinito: []
  • Descrizione: L'elenco dei locali richiesti nell'applicazione.
  • Esempio: []
  • Nota: Se vuoto, tutti i locali sono richiesti in modalità strict.
  • Nota: Assicurarsi che i locali richiesti siano anche definiti nel campo locales.

• strictMode:

  • Tipo: string
  • Predefinito: inclusive
  • Descrizione: Garantisce implementazioni rigorose di contenuti internazionalizzati utilizzando TypeScript.
  • Nota: Se impostato su "strict", la funzione di traduzione t richiederà che ogni locale dichiarato sia definito. Se manca un locale o se un locale non è dichiarato nella configurazione, verrà generato un errore.
  • Nota: Se impostato su "inclusive", la funzione di traduzione t richiederà che ogni locale dichiarato sia definito. Se manca un locale, verrà generato un avviso. Tuttavia, accetterà se un locale non è dichiarato nella configurazione ma esiste.
  • Nota: Se impostato su "loose", la funzione di traduzione t accetterà qualsiasi locale esistente.

• defaultLocale:

  • Tipo: string
  • Predefinito: 'en'
  • Descrizione: Il locale predefinito utilizzato come fallback se il locale richiesto non viene trovato.
  • Esempio: 'en'
  • Nota: Questo viene utilizzato per determinare il locale quando non è specificato nell'URL, nei cookie o nell'intestazione.

Configurazione Editor

Definisce le impostazioni relative all'editor integrato, inclusi la porta del server e lo stato attivo.

Proprietà

• applicationURL:

  • Tipo: string
  • Predefinito: http://localhost:3000
  • Descrizione: L'URL dell'applicazione. Utilizzato 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 su '*', l'editor è accessibile da qualsiasi origine.

• port:

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

• 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. Utilizzato per limitare le origini che possono interagire con l'applicazione per motivi di sicurezza. Se impostato su '*', l'editor è accessibile da qualsiasi origine. Dovrebbe essere impostato se la porta viene modificata o se l'editor è ospitato su un dominio diverso.

• cmsURL:

  • Tipo: string
  • Predefinito: 'https://intlayer.org'
  • Descrizione: L'URL del CMS di Intlayer.
  • Esempio: 'https://intlayer.org'
  • Nota: L'URL del CMS di 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 visivo.
  • Esempio: process.env.NODE_ENV !== 'production'
  • Nota: Se true, l'editor sarà in grado di interagire con l'applicazione. Se false, l'editor non sarà in grado di interagire con l'applicazione. In ogni caso, l'editor può essere abilitato solo dall'editor visivo. Disabilitare l'editor per ambienti specifici è un modo per rafforzare la sicurezza.

• clientId:

  • Tipo: string | undefined
  • Predefinito: undefined
  • Descrizione: clientId e clientSecret consentono 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: Il clientId e il clientSecret devono essere mantenuti segreti e non condivisi pubblicamente. Assicurati di conservarli in un luogo sicuro, come variabili di ambiente.

• clientSecret:

  • Tipo: string | undefined
  • Predefinito: undefined
  • Descrizione: clientId e clientSecret consentono 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: Il clientId e il clientSecret devono essere mantenuti segreti e non condivisi pubblicamente. Assicurarsi di conservarli in un luogo sicuro, come variabili di ambiente.

• liveSync:

  • Tipo: boolean
  • Predefinito: false
  • Descrizione: Indica se l'applicazione deve ricaricare automaticamente le configurazioni dei locali quando viene rilevata una modifica.
  • Esempio: true
  • Nota: Ad esempio, quando viene aggiunto o aggiornato un nuovo dizionario, l'applicazione aggiornerà il contenuto da visualizzare nella pagina.
  • Nota: Poiché il ricaricamento automatico richiede una connessione continua al server, è disponibile solo per i clienti del piano enterprise.

• 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'

Configurazione Middleware

Impostazioni che controllano il comportamento del middleware, inclusa la gestione di cookie, intestazioni e prefissi URL per la gestione dei locali.

Proprietà

• headerName:

  • Tipo: string
  • Predefinito: 'x-intlayer-locale'
  • Descrizione: Il nome dell'intestazione HTTP utilizzata per determinare il locale.
  • Esempio: 'x-custom-locale'
  • Nota: Utile per la determinazione del locale basata su API.

• cookieName:

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

• prefixDefault:

  • Tipo: boolean
  • Predefinito: false
  • Descrizione: Indica se includere il locale predefinito nell'URL.
  • Esempio: true
  • Nota:
    • Se true e defaultLocale = 'en': path = /en/dashboard o /fr/dashboard
    • Se false e defaultLocale = 'en': path = /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 su ogni richiesta o mai.

• noPrefix:

  • Tipo: boolean
  • Predefinito: false
  • Descrizione: Indica 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

• detectLocaleOnPrefetchNoPrefix:

  • Tipo: boolean
  • Predefinito: false
  • Descrizione: Controlla se la rilevazione del locale avviene durante le richieste di prefetch di Next.js.
  • Esempio: true
  • Nota: Questa impostazione influisce su come Next.js gestisce il prefetch del locale:
    • Scenario di esempio:
      • La lingua del browser dell'utente è 'fr'
      • La pagina corrente è /fr/about
      • Il link fa prefetch di /about
    • Con detectLocaleOnPrefetchNoPrefix: true:
      • Il prefetch rileva il locale 'fr' dal browser
      • Reindirizza il prefetch a /fr/about
    • Con detectLocaleOnPrefetchNoPrefix: false (predefinito):
      • Il prefetch usa il locale predefinito
      • Reindirizza il prefetch a /en/about (assumendo che 'en' sia il predefinito)
    • Quando usare true:
      • La tua app usa link interni non localizzati (es. <a href="/about">)
      • Vuoi un comportamento di rilevazione del locale coerente tra richieste normali e di prefetch
    • Quando usare false (predefinito):
      • La tua app usa link con prefisso del locale (es. <a href="/fr/about">)
      • Vuoi ottimizzare le prestazioni del prefetch
      • Vuoi evitare potenziali loop di reindirizzamento

Configurazione del Contenuto

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

Proprietà

• 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 di 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: ['src']
  • Esempio: ['src', '../../ui-library', require.resolve("@my-package/content")]
  • Descrizione: Il percorso della directory in cui sono memorizzati i contenuti.

• dictionariesDir:

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

• moduleAugmentationDir:

  • Tipo: string
  • Predefinito: '.intlayer/types'
  • Descrizione: Directory per l'augmentazione dei moduli, consentendo migliori suggerimenti IDE e controllo dei tipi.
  • Esempio: 'intlayer-types'
  • Nota: Assicurati di includerlo in tsconfig.json.

• unmergedDictionariesDir:

  • Tipo: string
  • Predefinito: '.intlayer/unmerged_dictionary'
  • Descrizione: La directory per memorizzare i 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: Assicurati 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 in cui sono memorizzati i file principali dell'applicazione.
  • Esempio: 'intlayer-main'

• excludedPath:

  • Tipo: string[]
  • Predefinito: ['node_modules']
  • Descrizione: Directory escluse dalla ricerca di 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 registrerà più informazioni, ma può essere utilizzata per scopi di debug. La modalità disabled disabiliterà 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, incluso il provider, il modello e la chiave API. Questa configurazione è opzionale se sei registrato sulla Dashboard di Intlayer utilizzando una chiave di accesso. Intlayer gestirà automaticamente la soluzione AI più efficiente ed economica per le tue esigenze. Utilizzare le opzioni predefinite garantisce una migliore manutenibilità a lungo termine poiché Intlayer si 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 predefinite 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: I diversi provider possono richiedere chiavi API diverse e avere modelli di prezzo differenti.

• 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 in base al provider.

• temperature:

  • Tipo: number
  • Predefinito: Nessuno
  • Descrizione: La temperatura controlla la casualità delle risposte dell'AI.
  • Esempio: 0.1
  • Nota: Una temperatura più alta renderà 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ù precise e contestualmente appropriate. Questo può includere informazioni sul dominio della tua applicazione, pubblico target, tono o terminologia specifica.

Configurazione del Build

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

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

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

Durante l'ottimizzazione, Intlayer sostituirà le chiamate ai dizionari per ottimizzare il chunking, in modo che il bundle finale importi solo i dizionari che vengono effettivamente utilizzati.

Proprietà

• optimize:

  • Tipo: boolean
  • Predefinito: process.env.NODE_ENV === 'production'
  • Descrizione: Controlla se il build deve essere ottimizzato.
  • Esempio: true
  • Nota: Quando abilitato, Intlayer sostituirà tutte le chiamate dei 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: Assicurati che tutte le chiavi siano dichiarate staticamente nelle chiamate useIntlayer. ad esempio: useIntlayer('navbar').

• importMode:

  • Tipo: 'static' | 'dynamic' | 'async'
  • Predefinito: 'static'
  • Descrizione: Controlla come vengono importati i dizionari.
  • Esempio: 'dynamic'
  • Nota: Modalità disponibili:
    • "static": I dizionari vengono importati staticamente. Sostituisce useIntlayer con useDictionary.
    • "dynamic": I dizionari vengono importati dinamicamente utilizzando Suspense. Sostituisce useIntlayer con useDictionaryDynamic.
    • "async": I dizionari vengono importati dinamicamente in modo asincrono. Sostituisce useIntlayer con await useDictionaryAsync.
  • Nota: Le importazioni dinamiche si basano su Suspense e possono influire leggermente sulle prestazioni di rendering.
  • Nota: Se disabilitato, tutte le lingue verranno caricate contemporaneamente, anche se non vengono utilizzate.
  • Nota: Questa opzione si basa sui plugin @intlayer/babel e @intlayer/swc.
  • Nota: Assicurati che tutte le chiavi siano dichiarate staticamente nelle chiamate useIntlayer. ad esempio: useIntlayer('navbar').
  • Nota: Questa opzione verrà ignorata se optimize è disabilitato.
  • Nota: Nella maggior parte dei casi, "dynamic" verrà utilizzato per le applicazioni React, "async" per le applicazioni Vue.js.
  • 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: Usa questo per limitare l'ottimizzazione ai file di codice rilevanti e migliorare le prestazioni del build.
  • Nota: Questa opzione verrà ignorata se optimize è disabilitato.
  • Nota: Usa il pattern glob.

Cronologia della documentazione

• 5.5.11 - 2025-06-29: Aggiunti comandi docs