utils

Panoramica

Il modulo utils contiene due helper utilizzati internamente dal composable useI18n per implementare la funzione di traduzione t:

• interpolate(template, params) — sostituisce i segnaposto {nome} in una stringa.
• getNestedValue(obj, path) — naviga un oggetto tramite path dot-notation.

Queste funzioni non sono esportate dall'index.ts del pacchetto e fanno parte dell'API privata. Sono documentate qui per completezza, in particolare per chi legge il codice sorgente o vuole replicarne il comportamento.

interpolate

Sostituisce i segnaposto {chiave} in una stringa template con i valori del parametro params.

Firma

function interpolate(template: string, params: InterpolationParams): string

dove:

type InterpolationParams = Record<string, string | number>

Comportamento

• Pattern di match: /\{(\w+)\}/g — solo caratteri parola ([A-Za-z0-9_]) tra graffe singole.
• Se la chiave esiste in params, viene sostituita con String(params[key]) (i numeri vengono convertiti in stringa).
• Se la chiave non esiste, il segnaposto viene lasciato invariato (es. {name} resta nella stringa).

Esempi

interpolate('Ciao {name}!', { name: 'Mario' })
// → 'Ciao Mario!'

interpolate('Hai {count} messaggi su {total}', { count: 3, total: 10 })
// → 'Hai 3 messaggi su 10'

interpolate('Benvenuto {name}', {})
// → 'Benvenuto {name}' (segnaposto lasciato invariato)

Note

• Non supporta pluralizzazione né formattazione (date, numeri locale): per quei casi usare Intl direttamente nel componente.
• Non supporta segnaposto annidati né escape delle graffe.

getNestedValue

Naviga un oggetto tramite path dot-notation e restituisce la stringa trovata, oppure undefined.

Firma

function getNestedValue(
  obj: Record<string, unknown>,
  path: string,
): string | undefined

Comportamento

• Splitta path su . e naviga ricorsivamente.
• Ritorna undefined se incontra null, undefined o un non-oggetto prima della fine del path.
• Ritorna undefined anche se il valore finale non è una stringa (gli oggetti foglia non sono considerati validi: solo i terminali stringa).

Esempi

const dict = {
  pages: { home: { title: 'Benvenuto' } },
  common: { greeting: 'Ciao' },
}

getNestedValue(dict, 'pages.home.title')   // → 'Benvenuto'
getNestedValue(dict, 'common.greeting')    // → 'Ciao'
getNestedValue(dict, 'pages.home')         // → undefined (oggetto, non stringa)
getNestedValue(dict, 'pages.about.title')  // → undefined (path inesistente)
getNestedValue(dict, 'inesistente')        // → undefined

Note

• Questo vincolo (solo stringhe terminali) è il motivo per cui t('pages.home') restituisce la chiave stessa con warning anziché [object Object]: previene errori di rendering.
• Il path è splittato letteralmente su .: chiavi contenenti punti non sono supportate.

Estensione

Se servono helper di formattazione o pluralizzazione, si raccomanda di costruirli sopra useI18n nel proprio progetto:

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

export function useI18nPlural() {
  const { t } = useI18n()
  return (key: string, count: number) => {
    const suffix = count === 1 ? '.one' : '.other'
    return t(`${key}${suffix}`, { count })
  }
}

In questo modo la libreria resta minimale e ogni applicazione può adottare la propria strategia.