config

Panoramica

L'API di configurazione gestisce il singleton globale di @pzeta/vue-i18n. configureI18n va chiamata una sola volta all'avvio dell'applicazione, prima di montare l'app Vue. Le altre funzioni (isI18nConfigured, getI18nConfig) sono utility ispettive utili in helper, plugin o test.

configureI18n

Inizializza il sistema i18n. Registra i loader per ogni lingua, popola la cache con eventuali dizionari preloaded e imposta defaultLocale come lingua corrente.

Firma

function configureI18n<
  TLocale extends string,
  TDict extends TranslationDictionary = TranslationDictionary,
>(config: I18nConfig<TLocale, TDict>): void

Esempio

// main.ts
import { configureI18n } from '@pzeta/vue-i18n'
import itLocale from './locales/it'

configureI18n({
  defaultLocale: 'it',
  fallbackLocale: 'it',
  locales: {
    it: {
      loader: () => Promise.resolve({ default: itLocale }),
      preloaded: itLocale,
    },
    en: {
      loader: () => import('./locales/en'),
    },
    de: {
      loader: () => import('./locales/de'),
    },
  },
  onLocaleChange: (locale) => {
    document.documentElement.lang = locale
    localStorage.setItem('locale', locale)
  },
  warnPrefix: '[my-app/i18n]',
})

I18nConfig

LocaleConfig

interface LocaleConfig<T extends TranslationDictionary = TranslationDictionary> {
  loader: LocaleLoader<T>
  preloaded?: T
}

Comportamento di inizializzazione

1. setConfig(config) — registra la configurazione.
2. Per ogni LocaleConfig con preloaded, popola localeCache.
3. currentLocale = defaultLocale. Se defaultLocale è in cache (preloaded), translations sono settate sincronamente; altrimenti restano vuote finché un setLocale non le carica.
4. Setta il flag isConfigured = true.

Note

• Chiamare configureI18n due volte sovrascrive la configurazione, ma non svuota la cache delle lingue già caricate. Per un reset completo usare resetI18nFull (vedi sezione reset).
• Il sistema non importa automaticamente le traduzioni: ogni file locales/xx.ts deve esportare le traduzioni come default per essere compatibile con LocaleLoader.

isI18nConfigured

Verifica se configureI18n è già stata chiamata.

Firma

function isI18nConfigured(): boolean

Esempio

import { isI18nConfigured, configureI18n } from '@pzeta/vue-i18n'

if (!isI18nConfigured()) {
  configureI18n({ /* ... */ })
}

Utile in librerie/plugin che possono essere caricati prima del bootstrap dell'app, o in test che girano su processo lungo.

getI18nConfig

Ritorna la configurazione corrente o null se il sistema non è configurato.

Firma

function getI18nConfig(): I18nConfig | null

Esempio

import { getI18nConfig } from '@pzeta/vue-i18n'

const cfg = getI18nConfig()
if (cfg) {
  console.log('Lingue supportate:', Object.keys(cfg.locales))
  console.log('Fallback:', cfg.fallbackLocale ?? cfg.defaultLocale)
}

Il tipo restituito è I18nConfig "non generico": utile per ispezione, non per usare il dizionario tipizzato.

Note

• Lo stato di configureI18n è un singleton di modulo: condiviso tra tutti gli import di @pzeta/vue-i18n nello stesso bundle.
• In progetti con SSR o micro-frontend con bundle separati, ogni bundle ha la propria istanza — assicurarsi che configureI18n venga chiamata su ognuno (oppure dedupare la dipendenza nel build).