I18nFormPlugin
Cosa fa
I18nFormPlugin integra le traduzioni di @pzeta/vue-form nel sistema @pzeta/vue-i18n. Gestisce:
- Registrazione dei messaggi di validazione in italiano (precaricati) e inglese (lazy-loaded)
- Merge automatico con traduzioni di altre librerie (es.
@pzeta/vue-components) - Riconfigurazione dell'istanza i18n se già inizializzata dall'applicazione
Ordine di registrazione
I18nFormPlugin deve essere registrato prima di VueFormPlugin. Il plugin configura il sistema i18n che i componenti usano al momento della loro inizializzazione.
// CORRETTO
app.use(I18nFormPlugin)
app.use(VueFormPlugin)
// SBAGLIATO — i componenti non trovano le traduzioni
app.use(VueFormPlugin)
app.use(I18nFormPlugin)
Opzioni
interface I18nFormPluginOptions {
defaultLocale?: 'it' | 'en' // default: 'it'
fallbackLocale?: 'it' | 'en' // default: 'it'
warnPrefix?: string // default: '[@pzeta/vue-form]'
onLocaleChange?: (locale: 'it' | 'en') => void
mergeTranslations?: {
it?: Record<string, unknown> | (() => Promise<Record<string, unknown>>)
en?: Record<string, unknown> | (() => Promise<Record<string, unknown>>)
}
}
Uso base
import { I18nFormPlugin } from '@pzeta/vue-form'
app.use(I18nFormPlugin)
// usa italiano come lingua default, inglese caricato lazy
Attenzione — I18nFormPlugin riconfigura @pzeta/vue-i18n
@pzeta/vue-i18n mantiene una singola istanza globale di dizionario tradotto. Durante install(), I18nFormPlugin invoca configureI18n() e sostituisce il dizionario corrente con quello di vue-form (più eventuale mergeTranslations).
Antipattern frequente — chiamare manualmente configureI18n({ locales: { it: { preloaded: mioDizionario } } }) prima di app.use(I18nFormPlugin) non funziona: il plugin sovrascrive il dizionario al momento dell'install, lasciando solo le chiavi validation.* di vue-form. Risultato: i componenti che cercano chiavi tipo paginator.ariaLabel, form.datePlaceholder, panel.toggleAriaLabel non le trovano e loggano "Traduzione mancante".
Soluzione: passare tutti i dizionari aggiuntivi via mergeTranslations di I18nFormPlugin, evitando configureI18n manuale.
// SBAGLIATO — il configureI18n manuale verrà sovrascritto da I18nFormPlugin
configureI18n({ locales: { it: { preloaded: myDict } } })
app.use(I18nFormPlugin)
// CORRETTO — un solo punto di configurazione
app.use(I18nFormPlugin, { mergeTranslations: { it: myDict } })
Integrazione con @pzeta/vue-components
Se l'applicazione usa già @pzeta/vue-components, le relative traduzioni devono essere mergiate per evitare che vengano sovrascritte:
import { it as compIt, loadEn as loadCompEn } from '@pzeta/vue-components'
import { I18nFormPlugin } from '@pzeta/vue-form'
app.use(I18nFormPlugin, {
mergeTranslations: {
it: compIt,
en: async () => (await loadCompEn()).default,
},
})
Le traduzioni passate via mergeTranslations vengono mergiate con quelle di @pzeta/vue-form. In caso di chiavi duplicate, le traduzioni della libreria hanno la precedenza.
Traduzioni custom
Per personalizzare i messaggi di errore di validazione, passa un oggetto parziale che sovrascriva solo le chiavi desiderate:
import { I18nFormPlugin } from '@pzeta/vue-form'
const customIt = {
validation: {
core: {
required: 'Campo obbligatorio',
},
format: {
email: 'Email non valida',
},
},
}
const loadCustomEn = async () => ({
validation: {
core: {
required: 'This field is required',
},
format: {
email: 'Invalid email address',
},
},
})
app.use(I18nFormPlugin, {
mergeTranslations: {
it: customIt,
en: loadCustomEn,
},
})
Struttura chiavi i18n
Le chiavi sono organizzate per categoria sotto il namespace validation:
| Chiave | Esempio messaggio IT |
|---|---|
validation.core.required | Questo campo è obbligatorio |
validation.core.minString | Il campo deve contenere almeno {min} caratteri |
validation.core.maxString | Il campo può contenere al massimo {max} caratteri |
validation.format.email | Inserisci un indirizzo email valido |
validation.format.url | Inserisci un URL valido |
validation.format.phone | Numero di telefono non valido |
validation.numeric.integer | Il valore deve essere un numero intero |
validation.date.invalid | Data non valida |
validation.italian.codiceFiscale | Codice fiscale non valido |
validation.italian.partitaIva | Partita IVA non valida |
validation.financial.iban | IBAN non valido |
validation.security.password | Password non valida |
Le chiavi UI per le etichette dei componenti si trovano sotto ui.* (es. ui.common.save, ui.actions.moveUp).
Configurazione avanzata
app.use(I18nFormPlugin, {
defaultLocale: 'en',
fallbackLocale: 'it',
warnPrefix: '[MyApp]',
onLocaleChange: (locale) => {
document.documentElement.lang = locale
},
mergeTranslations: {
it: customIt,
en: loadCustomEn,
},
})