API JavaScript Intl (Internazionalizzazione)

Intl è uno spazio dei nomi JavaScript integrato per la formattazione e il confronto locale. Non c'è nessuna libreria da installare e nulla da importare — è incluso in ogni browser moderno e in Node.js. Con esso puoi formattare numeri, valute, date, tempi relativi e liste esattamente nel modo in cui gli utenti di una determinata regione si aspettano, e puoi ordinare il testo correttamente per le lingue in cui l'ordinamento solo in inglese produce risultati errati.

Quasi ogni costruttore Intl segue la stessa struttura: si passa un locale (o un array di locale di fallback) e un oggetto options. Un locale è un tag linguistico BCP 47 come 'en-US', 'de-DE', 'fr-FR', o 'ja-JP'. Se si omette completamente il locale, Intl utilizza il locale predefinito del runtime (l'impostazione della lingua del browser, o il locale di sistema in Node).

// locale + options
new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' });

// no locale → uses the runtime default
new Intl.NumberFormat();

// an array provides fallbacks: try Welsh, then fall back to English
new Intl.NumberFormat(['cy', 'en']);

Intl.NumberFormat

Intl.NumberFormat formatta i numeri secondo le convenzioni di un locale. Questo è importante perché i separatori di raggruppamento e decimale variano da posto a posto: il numero 1234.56 si scrive 1,234.56 negli Stati Uniti ma 1.234,56 in Germania.

const n = 1234.56;

console.log(new Intl.NumberFormat('en-US').format(n)); // "1,234.56"
console.log(new Intl.NumberFormat('de-DE').format(n)); // "1.234,56"
console.log(new Intl.NumberFormat('fr-FR').format(n)); // "1 234,56"

L'opzione style seleziona il tipo di valore che si sta formattando: 'decimal' (il valore predefinito), 'currency', 'percent', o 'unit'.

Valuta

Per i valori monetari, imposta style: 'currency' e specifica la valuta con l'opzione currency (un codice ISO 4217 come 'USD' o 'EUR'). Il locale determina la posizione del simbolo e i separatori.

const price = 1499.9;

console.log(
  new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(price)
); // "$1,499.90"

console.log(
  new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(price)
); // "1.499,90 €"

console.log(
  new Intl.NumberFormat('ja-JP', { style: 'currency', currency: 'JPY' }).format(price)
); // "￥1,500"   (yen has no minor unit, so it is rounded)

Percentuale, cifre decimali e notazione compatta

Usa style: 'percent' per formattare un rapporto come percentuale — il valore viene moltiplicato per 100. Controlla quanti decimali vengono visualizzati con minimumFractionDigits e maximumFractionDigits. Imposta notation: 'compact' per produrre forme abbreviate come 1.2K e 3.4M.

console.log(
  new Intl.NumberFormat('en-US', { style: 'percent' }).format(0.1875)
); // "19%"

console.log(
  new Intl.NumberFormat('en-US', {
    style: 'percent',
    minimumFractionDigits: 2,
  }).format(0.1875)
); // "18.75%"

console.log(
  new Intl.NumberFormat('en-US', { notation: 'compact' }).format(1200000)
); // "1.2M"

Unità

Con style: 'unit' puoi formattare misure. Specifica l'unità con l'opzione unit (ad esempio 'kilometer-per-hour' o 'megabyte') e scegli un unitDisplay tra 'short', 'long', o 'narrow'.

console.log(
  new Intl.NumberFormat('en-US', {
    style: 'unit',
    unit: 'kilometer-per-hour',
  }).format(90)
); // "90 km/h"

console.log(
  new Intl.NumberFormat('en-US', {
    style: 'unit',
    unit: 'megabyte',
    unitDisplay: 'long',
  }).format(16)
); // "16 megabytes"

Per un lavoro più approfondito con i numeri — arrotondamento, precisione e aritmetica — vedi Numeri e JavaScript Math.

Intl.DateTimeFormat

Intl.DateTimeFormat formatta oggetti Date (e timestamp) per un locale. L'approccio più rapido è tramite le opzioni dateStyle e timeStyle, ognuna delle quali accetta 'full', 'long', 'medium', o 'short'.

Per un controllo più preciso, imposta singoli componenti come year, month, day, hour, minute, e second, e ancorare l'output a un fuso orario con timeZone.

const date = new Date('2026-06-19T14:30:00Z');

const fmt = new Intl.DateTimeFormat('en-GB', {
  year: 'numeric',
  month: 'short',
  day: '2-digit',
  hour: '2-digit',
  minute: '2-digit',
  timeZone: 'Europe/Berlin',
});

console.log(fmt.format(date)); // "19 Jun 2026, 16:30"

Vale la pena conoscere due metodi aggiuntivi. .formatToParts() restituisce l'output suddiviso in parti etichettate ({ type: 'month', value: 'Jun' }, e così via), il che ti consente di applicare stili alle singole parti. .formatRange(start, end) formatta un intervallo di date in modo compatto, comprimendo le parti condivise.

const fmt = new Intl.DateTimeFormat('en-US', { month: 'long', day: 'numeric' });

console.log(fmt.formatRange(new Date(2026, 5, 1), new Date(2026, 5, 5)));
// "June 1 – 5"

Per tutto ciò che riguarda la creazione e la manipolazione delle date, vedi JavaScript Date.

Intl.RelativeTimeFormat

Intl.RelativeTimeFormat produce frasi comprensibili come "2 giorni fa" o "tra 3 ore". Si chiama .format(value, unit), dove un value negativo indica il passato e un value positivo indica il futuro. L'opzione numeric: 'auto' consente al formattatore di usare parole come "yesterday" e "tomorrow" invece di "1 day ago".

const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });

console.log(rtf.format(-1, 'day'));  // "yesterday"
console.log(rtf.format(3, 'hour'));  // "in 3 hours"
console.log(rtf.format(-2, 'day'));  // "2 days ago"
console.log(rtf.format(1, 'week'));  // "next week"

La stessa chiamata in un altro locale produce una formulazione nativa — new Intl.RelativeTimeFormat('fr').format(-1, 'day') restituisce "il y a 1 jour".

Intl.Collator

L'ordinamento del testo è il punto in cui il codice ingenuo sbaglia più spesso. Il metodo predefinito Array.prototype.sort() di JavaScript confronta le stringhe in base alle loro unità di codice UTF-16, non secondo le regole alfabetiche. Ciò significa che le lettere maiuscole vengono ordinate prima di quelle minuscole, e le lettere accentate o non latine finiscono in posizioni sorprendenti.

const words = ['Zürich', 'apple', 'Banana', 'Älpler'];

console.log([...words].sort());
// ["Banana", "Zürich", "Älpler", "apple"]  ← not what a reader expects

Intl.Collator risolve questo problema confrontando le stringhe nel modo in cui lo fa una determinata lingua. Il suo metodo .compare ha esattamente la firma richiesta da sort(), quindi puoi passarlo direttamente.

Per un confronto occasionale di due stringhe puoi usare anche String.prototype.localeCompare, che accetta gli stessi argomenti di locale e opzioni: 'ä'.localeCompare('z', 'de'). Quando si ordina un intero array, è preferibile usare un Intl.Collator riutilizzato — è più veloce che chiamare localeCompare su ogni coppia. Vedi Strings per ulteriori informazioni sull'uso del testo.

Intl.PluralRules

Le diverse lingue hanno diverse categorie di plurale. L'inglese ne ha solo due ('one' e 'other'), ma molte lingue ne hanno di più. Intl.PluralRules indica in quale categoria rientra un numero, così da poter selezionare la formulazione corretta in un messaggio tradotto.

const pr = new Intl.PluralRules('en-US');

console.log(pr.select(0)); // "other"
console.log(pr.select(1)); // "one"
console.log(pr.select(5)); // "other"

function items(count) {
  const word = pr.select(count) === 'one' ? 'item' : 'items';
  return `${count} ${word}`;
}

console.log(items(1)); // "1 item"
console.log(items(3)); // "3 items"

Intl.ListFormat

Intl.ListFormat unisce un array di stringhe in un elenco dal suono naturale, inserendo i separatori e la congiunzione corretti per il locale — inclusa la virgola seriale dove la lingua la prevede.

const items = ['apples', 'bananas', 'oranges'];

const en = new Intl.ListFormat('en-US', { style: 'long', type: 'conjunction' });
console.log(en.format(items)); // "apples, bananas, and oranges"

const enOr = new Intl.ListFormat('en-US', { type: 'disjunction' });
console.log(enOr.format(items)); // "apples, bananas, or oranges"

const de = new Intl.ListFormat('de-DE', { type: 'conjunction' });
console.log(de.format(items)); // "apples, bananas und oranges"

Riutilizzare i formattatori per le prestazioni

// Slow: a new formatter is built on every iteration
prices.forEach((p) =>
  console.log(new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(p))
);

// Fast: build it once, reuse it
const money = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' });
prices.forEach((p) => console.log(money.format(p)));

Riepilogo

L'API Intl copre le attività di formattazione e confronto che un tempo richiedevano librerie di terze parti pesanti: numeri, valute, date, tempi relativi, plurali e liste con riconoscimento del locale, oltre all'ordinamento corretto del testo tramite Intl.Collator. Poiché è integrato in ogni browser moderno e in Node.js, usarla per prima mantiene il bundle leggero e l'output corretto per gli utenti di tutto il mondo. Ricorda l'unica regola che porta i maggiori benefici: crea ogni formattatore una volta sola e riutilizzalo.

Metti alla prova le tue conoscenze