Autore:
    Creazione:2024-08-13Ultimo aggiornamento:2025-08-20

    Formattatori Intlayer

    Panoramica

    Intlayer fornisce un set di helper leggeri costruiti sopra le API native Intl, oltre a un wrapper Intl con cache per evitare di costruire ripetutamente formattatori pesanti. Queste utilità sono completamente sensibili alla localizzazione e possono essere utilizzate dal pacchetto principale intlayer.

    Intl con cache

    L'Intl esportato è un wrapper sottile con cache attorno all'Intl globale. Memorizza in cache le istanze di NumberFormat, DateTimeFormat, RelativeTimeFormat, ListFormat, DisplayNames, Collator e PluralRules, evitando così di ricostruire ripetutamente lo stesso formattatore.

    Poiché la costruzione del formatter è relativamente costosa, questa cache migliora le prestazioni senza modificare il comportamento. Il wrapper espone la stessa API dell'Intl nativo, quindi l'uso è identico.

    • La cache è per processo e trasparente per i chiamanti.
    Se Intl.DisplayNames non è disponibile nell'ambiente, viene stampato un unico avviso solo per gli sviluppatori (considera un polyfill).

    Esempi:

    ts
    import { Intl } from "intlayer";// Formattazione numericaconst numberFormat = new Intl.NumberFormat("en-GB", {  style: "currency",  currency: "GBP",});numberFormat.format(1234.5); // "£1,234.50"// Nomi visualizzati per lingue, regioni, ecc.const displayNames = new Intl.DisplayNames("fr", { type: "language" });displayNames.of("en"); // "anglais"// Ordinamento per confrontoconst collator = new Intl.Collator("fr", { sensitivity: "base" });collator.compare("é", "e"); // 0 (uguale)// Regole pluraliconst pluralRules = new Intl.PluralRules("fr");pluralRules.select(1); // "one"pluralRules.select(2); // "other"

    React Formatters

    Intl.DisplayNames

    Per nomi localizzati di lingue, regioni, valute e script:

    ts
    import { Intl } from "intlayer";const languageNames = new Intl.DisplayNames("en", { type: "language" });languageNames.of("fr"); // "French"const regionNames = new Intl.DisplayNames("fr", { type: "region" });regionNames.of("US"); // "États-Unis"

    Hook Disponibili

    Tutti gli hook utilizzano automaticamente la locale da IntlayerProvider o IntlayerServerProvider.

    Hook Description Example Output
    useNumber() Formatta numeri con raggruppamento "123,456.789"
    useCurrency() Formatta valori di valuta "€1,234.50"
    usePercentage() Formatta percentuali "25%"
    useDate() Formatta date e orari "Aug 2, 2025"
    useRelativeTime() Formatta tempo relativo "in 3 days"
    useUnit() Formatta valori con unità "5 kilometers"
    useCompact() Formatta numeri in notazione compatta "1.2K"
    useList() Formatta array come liste "apple, banana, and orange"
    useIntl() Ottieni oggetto Intl legato alla locale Accesso completo API Intl

    Intl.Collator

    Per il confronto e l'ordinamento di stringhe sensibili alla localizzazione:

    ts
    import { Intl } from "intlayer";const collator = new Intl.Collator("de", {  sensitivity: "base",  numeric: true,});const words = ["äpfel", "zebra", "100", "20"];words.sort(collator.compare); // ["20", "100", "äpfel", "zebra"]

    Intl.PluralRules

    Per determinare le forme plurali in diverse localizzazioni:

    ts
    import { Intl } from "intlayer";const pluralRules = new Intl.PluralRules("ar");pluralRules.select(0); // "zero"pluralRules.select(1); // "one"pluralRules.select(2); // "two"pluralRules.select(3); // "few"pluralRules.select(11); // "many"

    Utilità per le localizzazioni

    getLocaleName(displayLocale, targetLocale?)

    Ottiene il nome localizzato di una localizzazione in un'altra localizzazione:

    ts
    import { getLocaleName } from "intlayer";getLocaleName("fr", "en"); // "French"getLocaleName("en", "fr"); // "anglais"getLocaleName("de", "es"); // "alemán"
    • displayLocale: La localizzazione di cui ottenere il nome
    • targetLocale: La localizzazione in cui visualizzare il nome (predefinita a displayLocale)

    Composables Disponibili

    Tutti i composables restituiscono computed refs che utilizzano automaticamente la locale dalla IntlayerProvider iniettata.

    Composable Descrizione Esempio di Output
    useNumber() Formatta numeri con raggruppamento "123,456.789"
    useCurrency() Formatta valori di valuta "€1,234.50"
    usePercentage() Formatta percentuali "25%"
    useDate() Formatta date e ore "Aug 2, 2025"
    useRelativeTime() Formatta tempo relativo "in 3 days"
    useUnit() Formatta valori con unità "5 kilometers"
    useCompact() Formatta numeri in notazione compatta "1.2K"
    useList() Formatta array come liste "apple, banana, and orange"
    useIntl() Ottieni oggetto Intl associato alla locale Accesso completo API Intl

    Esempio Completo

    vue
    <script setup>import {  useNumber,  useCurrency,  useDate,  usePercentage,  useCompact,  useList,  useRelativeTime,  useUnit,} from "vue-intlayer/format";const number = useNumber();const currency = useCurrency();const date = useDate();const percentage = usePercentage();const compact = useCompact();const list = useList();const relativeTime = useRelativeTime();const unit = useUnit();</script><template>  <div>    <p>{{ number.value(123456.789) }}</p>    <p>{{ currency.value(1234.5, { currency: "EUR" }) }}</p>    <p>{{ date.value(new Date(), "short") }}</p>    <p>{{ percentage.value(0.25) }}</p>    <p>{{ compact.value(1200) }}</p>    <p>{{ list.value(["apple", "banana", "orange"]) }}</p>    <p>{{ relativeTime.value(new Date(), new Date(Date.now() + 86400000)) }}</p>    <p>{{ unit.value(5, { unit: "kilometer" }) }}</p>  </div></template>

    getLocaleLang(locale?)

    Estrae il codice della lingua da una stringa di localizzazione:

    ts
    import { getLocaleLang } from "intlayer";getLocaleLang("en-US"); // "en"getLocaleLang("fr-CA"); // "fr"getLocaleLang("de"); // "de"
    • locale: La localizzazione da cui estrarre la lingua (predefinita alla localizzazione corrente)

    Vanilla JS / Node.js Formatters

    Per contesti non-framework, importa i formatter direttamente da intlayer. Nota che devi passare il locale manualmente.

    getLocaleFromPath(inputUrl)

    Estrae il segmento di localizzazione da un URL o pathname:

    ts
    import { getLocaleFromPath } from "intlayer";getLocaleFromPath("/en/dashboard"); // "en"getLocaleFromPath("/fr/dashboard"); // "fr"getLocaleFromPath("/dashboard"); // "en" (localizzazione predefinita)getLocaleFromPath("https://example.com/es/about"); // "es"
    • inputUrl: La stringa URL completa o il percorso da elaborare
    • returns: La localizzazione rilevata o la localizzazione predefinita se non viene trovata alcuna localizzazione

    Funzioni Formatter

    number(value, options?)

    Formatta un valore numerico utilizzando il raggruppamento e i decimali consapevoli della locale.

    • value: number | string
    • options: Intl.NumberFormatOptions & { locale?: LocalesValues }
    ts
    number(123456.789); // "123,456.789" (in en-US)number("1000000", { locale: "fr" }); // "1 000 000"number(1234.5, { minimumFractionDigits: 2 }); // "1,234.50"

    percentage(value, options?)

    Formatta un numero come stringa percentuale. I valori maggiori di 1 sono normalizzati (es. 25 → 25%, 0.25 → 25%).

    • value: number | string
    • options: Intl.NumberFormatOptions & { locale?: LocalesValues }
    ts
    percentage(0.25); // "25%"percentage(25); // "25%"percentage(0.237, { minimumFractionDigits: 1 }); // "23.7%"

    currency(value, options?)

    Formatta un valore come valuta localizzata. Il valore predefinito è USD.

    • value: number | string
    • options: Intl.NumberFormatOptions & { locale?: LocalesValues }
      • Comuni: currency, currencyDisplay ("symbol" | "code" | "name")
    ts
    currency(1234.5, { currency: "EUR" }); // "€1,234.50"currency("5000", { locale: "fr", currency: "CAD", currencyDisplay: "code" }); // "5 000,00 CAD"

    date(date, optionsOrPreset?)

    Formatta un valore di data/ora.

    • date: Date | string | number
    • optionsOrPreset: Intl.DateTimeFormatOptions & { locale?: LocalesValues } o preset: "short" | "long" | "dateOnly" | "timeOnly" | "full"
    ts
    date(new Date(), "short"); // es. "08/02/25, 14:30"date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"

    relativeTime(from, to?, options?)

    Formatta il tempo relativo tra due istanti.

    • from: Date | string | number
    • to: Date | string | number (predefinito new Date())
    • options: { locale?, unit?, numeric?, style? }
    ts
    const now = new Date();const in3Days = new Date(now.getTime() + 3 * 864e5);relativeTime(now, in3Days, { unit: "day" }); // "in 3 days"const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 hours ago"

    units(value, options?)

    Formatta un valore numerico con un'unità.

    • value: number | string
    • options: Intl.NumberFormatOptions & { locale?: LocalesValues }
      • Common: unit (e.g., "kilometer", "byte"), unitDisplay ("short" | "narrow" | "long")
    ts
    units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 kilometers"units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B"

    compact(value, options?)

    Formatta un numero utilizzando la notazione compatta.

    • value: number | string
    • options: Intl.NumberFormatOptions & { locale?: LocalesValues }
    ts
    compact(1200); // "1.2K"compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"

    list(values, options?)

    Formatta un array in una stringa di lista localizzata.

    • values: (string | number)[]
    • options: Intl.ListFormatOptions & { locale?: LocalesValues }
      • Common: type ("conjunction" | "disjunction" | "unit"), style ("long" | "short" | "narrow")
    ts
    list(["apple", "banana", "orange"]); // "apple, banana, and orange"list(["red", "green", "blue"], { locale: "fr", type: "disjunction" }); // "rouge, vert ou bleu"

    Formatter

    Tutti gli helper seguenti sono esportati da intlayer.

    Funzionalità Intl Aggiuntive

    Intl.DisplayNames

    Per nomi localizzati di lingue, regioni, valute e script:

    ts
    import { Intl } from "intlayer";const languageNames = new Intl.DisplayNames("en", { type: "language" });languageNames.of("fr"); // "French"const regionNames = new Intl.DisplayNames("fr", { type: "region" });regionNames.of("US"); // "États-Unis"

    Intl.Collator

    Per il confronto e l'ordinamento di stringhe consapevoli della locale:

    ts
    import { Intl } from "intlayer";const collator = new Intl.Collator("de", {  sensitivity: "base",  numeric: true,});const words = ["äpfel", "zebra", "100", "20"];words.sort(collator.compare); // ["20", "100", "äpfel", "zebra"]

    Intl.PluralRules

    Per determinare le forme plurali in diverse lingue:

    ts
    import { Intl } from "intlayer";const pluralRules = new Intl.PluralRules("ar");pluralRules.select(0); // "zero"pluralRules.select(1); // "one"pluralRules.select(2); // "two"pluralRules.select(3); // "few"pluralRules.select(11); // "many"

    Locale Utilities

    currency(value, options?)

    Formatta un valore come valuta localizzata. Il valore predefinito è USD con due cifre decimali.

    • value: number | string
    • options: Intl.NumberFormatOptions & { locale?: LocalesValues }
      • Campi comuni: currency (es. "EUR"), currencyDisplay ("symbol" | "code" | "name")

    Esempi:

    ts
    import { currency } from "intlayer";currency(1234.5, { currency: "EUR" }); // "€1,234.50"currency("5000", { locale: "fr", currency: "CAD", currencyDisplay: "code" }); // "5 000,00 CAD"

    date(date, optionsOrPreset?)

    Formatta un valore data/ora con Intl.DateTimeFormat.

    • date: Date | string | number
    • optionsOrPreset: Intl.DateTimeFormatOptions & { locale?: LocalesValues } oppure uno dei preset:
      • Preset: "short" | "long" | "dateOnly" | "timeOnly" | "full"

    Esempi:

    ts
    import { date } from "intlayer";date(new Date(), "short"); // es., "08/02/25, 14:30"date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"

    relativeTime(from, to = new Date(), options?)

    Formatta il tempo relativo tra due istanti con Intl.RelativeTimeFormat.

    • Passa "now" come primo argomento e il target come secondo per ottenere una frase naturale.
    • from: Date | string | number
    • to: Date | string | number (default è new Date())
    • options: { locale?: LocalesValues; unit?: Intl.RelativeTimeFormatUnit; numeric?: Intl.RelativeTimeFormatNumeric; style?: Intl.RelativeTimeFormatStyle }
      • L'unit predefinita è "second".

    Esempi:

    ts
    import { relativeTime } from "intlayer";const now = new Date();const in3Days = new Date(now.getTime() + 3 * 864e5);relativeTime(now, in3Days, { unit: "day" }); // "in 3 giorni"const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 ore fa"

    units(value, options?)

    Formatta un valore numerico come stringa di unità localizzata usando Intl.NumberFormat con style: 'unit'.

    • value: number | string
    • options: Intl.NumberFormatOptions & { locale?: LocalesValues }
      • Campi comuni: unit (es., "kilometer", "byte"), unitDisplay ("short" | "narrow" | "long")
      • Predefiniti: unit: 'day', unitDisplay: 'short', useGrouping: false

    Esempi:

    ts
    import { units } from "intlayer";units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 kilometers"units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B" (dipendente dalla localizzazione)

    compact(value, options?)

    Formatta un numero usando la notazione compatta (es., 1.2K, 1M).

    • value: number | string
    • options: Intl.NumberFormatOptions & { locale?: LocalesValues } (usa internamente notation: 'compact')

    Esempi:

    ts
    import { compact } from "intlayer";compact(1200); // "1.2K"compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"

    list(values, options?)

    Formatta un array di valori in una stringa di elenco localizzata utilizzando Intl.ListFormat.

    • values: (string | number)[]
    • options: Intl.ListFormatOptions & { locale?: LocalesValues }
      • Campi comuni: type ("conjunction" | "disjunction" | "unit"), style ("long" | "short" | "narrow")
      • Predefiniti: type: 'conjunction', style: 'long'

    Esempi:

    ts
    import { list } from "intlayer";list(["apple", "banana", "orange"]); // "apple, banana, and orange"list(["red", "green", "blue"], { locale: "fr", type: "disjunction" }); // "rouge, vert ou bleu"list([1, 2, 3], { type: "unit" }); // "1, 2, 3"

    Utility di Gestione dei Contenuti

    React

    Componenti client:

    tsx
    import {  useNumber,  useCurrency,  useDate,  usePercentage,  useCompact,  useList,  useRelativeTime,  useUnit,} da "react-intlayer/format";// oppure nelle app Next.jsimport {  useNumber,  useCurrency,  useDate,  usePercentage,  useCompact,  useList,  useRelativeTime,  useUnit,} da "next-intlayer/client/format";const MyComponent = () => {  const number = useNumber();  const currency = useCurrency();  const date = useDate();  const percentage = usePercentage();  const compact = useCompact();  const list = useList();  const relativeTime = useRelativeTime();  const unit = useUnit();  return (    <div>      <p>{number(123456.789)}</p>      <p>{currency(1234.5, { currency: "EUR" })}</p>      <p>{date(new Date(), "short")}</p>      <p>{percentage(0.25)}</p>      <p>{compact(1200)}</p>      <p>{list(["apple", "banana", "orange"])}</p>      <p>{relativeTime(new Date(), new Date() + 1000)}</p>      <p>{unit(123456.789, { unit: "kilometer" })}</p>    </div>  );};

    Componenti server (o runtime React Server):

    ts
    import {  useNumber,  useCurrency,  useDate,  usePercentage,  useCompact,  useList,  useRelativeTime,  useUnit,} from "react-intlayer/server/format";// oppure nelle app Next.jsimport {  useNumber,  useCurrency,  useDate,  usePercentage,  useCompact,  useList,  useRelativeTime,  useUnit,} from "next-intlayer/server/format";
    Questi hook considereranno la locale fornita da IntlayerProvider o IntlayerServerProvider

    Vue

    Componenti client:

    ts
    import {  useNumber,  useCurrency,  useDate,  usePercentage,  useCompact,  useList,  useRelativeTime,  useUnit,} from "vue-intlayer/format";
    Questi composables considereranno la localizzazione dal IntlayerProvider iniettato

    getIntlayer(dictionaryKey, locale?, plugins?)

    Recupera e trasforma il contenuto da un dizionario:

    ts
    import { getIntlayer } from "intlayer";const content = getIntlayer("common", "fr");

    Note

    • Tutti gli helper accettano input string; vengono convertiti internamente a numeri o date.
    • La locale predefinita è quella configurata in internationalization.defaultLocale se non fornita.
    • Questi utility sono wrapper sottili; per la formattazione avanzata, passa attraverso le opzioni standard Intl.
    Perché Intlayer?