loader

Panoramica

Il modulo loader gestisce il caricamento on-demand delle traduzioni e la loro cache. È usato internamente da setLocale, ma è esportato anche pubblicamente per scenari avanzati: pre-caricamento manuale, ispezione cache, prefetch in idle.

La cache è una Map<string, TranslationDictionary> globale: viene popolata da configureI18n con i dizionari preloaded e da loadLocale dopo ogni caricamento riuscito. Una lingua già in cache non viene mai ricaricata.

loadLocale

Carica le traduzioni per una lingua specifica usando il loader configurato. Restituisce direttamente dalla cache se la lingua è già stata caricata.

Firma

function loadLocale<
  TDict extends TranslationDictionary = TranslationDictionary,
>(locale: string): Promise<TDict>

Comportamento

1. Lancia Error se configureI18n non è stata chiamata.
2. Cache hit → ritorna il dizionario sincronamente (Promise risolta).
3. Lingua sconosciuta (non in config.locales) → warning in console e fallback ricorsivo a fallbackLocale ?? defaultLocale.
4. Loader OK → memorizza il dizionario in cache e lo ritorna.
5. Loader in errore → console.error, fallback ricorsivo come sopra.

Esempio — prefetch manuale

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

// All'avvio: precarica EN in idle
requestIdleCallback(() => {
  void loadLocale('en')
})

// In hover su un selettore lingua: pre-carica per ridurre latenza
function onHover(locale: string) {
  void loadLocale(locale)
}

Esempio — caricamento tipizzato

const dict = await loadLocale<AppDict>('en')
console.log(dict.pages.home.title)

Note

• Il fallback è ricorsivo: se anche fallbackLocale non è caricabile, la promise può ancora rigettare. In pratica, defaultLocale dovrebbe sempre avere preloaded per garantire la disponibilità sincrona.
• Il loader è invocato una sola volta per lingua: errori intermittenti non vengono ritentati automaticamente.

isLocaleLoaded

Verifica sincronamente se una lingua è già in cache.

Firma

function isLocaleLoaded(locale: string): boolean

Esempio

import { isLocaleLoaded, loadLocale } from '@pzeta/vue-i18n'

if (!isLocaleLoaded('en')) {
  await loadLocale('en')
}

Utile per evitare di mostrare uno spinner se il cambio sarà istantaneo, o per decidere se vale la pena disabilitare un controllo.

getLocaleFromCache

Ottiene il dizionario di una lingua dalla cache senza fare richieste async. Restituisce null se non caricata.

Firma

function getLocaleFromCache(locale: string): TranslationDictionary | null

Esempio

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

const en = getLocaleFromCache('en')
if (en) {
  // accesso diretto, no await
  console.log(en.common.greeting)
}

Caso d'uso tipico: leggere una stringa di una lingua diversa dalla corrente (es. mostrare il nome di una lingua nella sua stessa lingua dentro un selettore).

LocaleLoader

Tipo della funzione di caricamento usata in LocaleConfig.

type LocaleLoader<T extends TranslationDictionary = TranslationDictionary> =
  () => Promise<{ default: T }>

Compatibile out-of-the-box con () => import('./locales/xx') di Vite e webpack: i moduli ESM con export default ritornano automaticamente nel formato { default: T }.

Esempio — loader custom

const loader: LocaleLoader<AppDict> = async () => {
  const res = await fetch('/api/i18n/en')
  return { default: (await res.json()) as AppDict }
}

configureI18n({
  defaultLocale: 'it',
  locales: {
    it: { loader: () => Promise.resolve({ default: itLocale }), preloaded: itLocale },
    en: { loader },
  },
})

Comportamento della cache

La cache non ha eviction automatica: una lingua caricata resta in memoria per tutta la vita dell'app. Per applicazioni con molte lingue, considerare di non chiamare loadLocale per lingue mai visualizzate.

Note

• Le funzioni loadLocale, isLocaleLoaded e getLocaleFromCache accettano string (non TLocale): non sono generiche sulla configurazione, perché operano sul singleton globale.
• In ambienti SSR le scritture in cache sono per processo: ogni request worker ha la propria cache.