JavaScriptAdvanced

JavaScript Intl API: Format Numbers, Dates, Plurals and Lists

Learn the JavaScript Intl API: NumberFormat, DateTimeFormat, RelativeTimeFormat, Collator, PluralRules and ListFormat for apps in any language.

All JavaScript lessons (83)View curriculum

What you will learn

The same number is written in different ways around the world: 1,234,567.89 in the US, 12,34,567.89 in India, 1.234.567,89 in Germany. A date like 10/2/2026 means October 2 in the US, but 10 February in India. Words are sorted differently in Swedish and in English. And “1 message, 2 messages” is not how most languages count.

If you build a website for people in more than one country, you cannot write all this by hand. JavaScript has a built-in toolbox for it: the Intl object. It knows the rules for almost every language. In this lesson you will learn how locales work, and the six main tools: Intl.NumberFormat, Intl.DateTimeFormat, Intl.RelativeTimeFormat, Intl.Collator, Intl.PluralRules and Intl.ListFormat, plus a few bonus tools. You have already met toLocaleString, toLocaleDateString and a small Intl.DateTimeFormat in the numbers and dates lessons. This lesson is the complete tour.

The idea in one line

Intl is a built-in expert that knows how every country writes numbers, dates, lists and plurals. You give it the data and a locale, and it gives you the text.

Think of a local guide in every country. You say: “Show this price the way people in Germany expect it.” The guide knows the symbols, the commas, the spacing and the order. You do not have to learn the rules of 200 countries. You only have to ask.

The problem with doing it by hand

const price = 1499.5;

console.log("₹" + price.toFixed(2));    // "₹1499.50"   (no thousands separator, only works for India)
console.log("$" + price.toFixed(2));    // "$1499.50"   (for Germany it should be "1.499,50 €")
const date = new Date(2026, 9, 10);
console.log(date.getDate() + "/" + (date.getMonth() + 1) + "/" + date.getFullYear());
// "10/10/2026"   (confusing for people who expect month first)

Every country needs different code, and you will miss many rules. Use Intl instead.

Locales: telling Intl who you are talking to

A locale is a short code for a language and (optionally) a region. The code follows a standard called BCP 47. The parts are joined with a dash:

Locale Meaning
en English (no country)
en-US English as used in the United States
en-IN English as used in India
en-GB English as used in the United Kingdom
hi-IN Hindi, India
de-DE German, Germany
fr-FR French, France
ja-JP Japanese, Japan
ar-EG Arabic, Egypt

Every Intl tool takes the locale as its first argument:

console.log(new Intl.NumberFormat("en-US").format(1234567.891));   // "1,234,567.891"
console.log(new Intl.NumberFormat("en-IN").format(1234567.891));   // "12,34,567.891"
console.log(new Intl.NumberFormat("de-DE").format(1234567.891));   // "1.234.567,891"
console.log(new Intl.NumberFormat("hi-IN").format(1234567.5));     // "12,34,567.5"

Where does the user’s locale come from?

The browser knows the user’s preferred language. You met it in the BOM lesson:

console.log(navigator.language);     // for example "en-IN"
console.log(navigator.languages);    // for example ["en-IN", "en", "hi"]

If you pass undefined instead of a locale, Intl uses the user’s default:

console.log(new Intl.NumberFormat(undefined).format(1234567.891));   // formatted for whoever opens the page

Fallbacks and checks

You can give a list of locales. Intl uses the first one it supports:

const nf = new Intl.NumberFormat(["xx-YY", "hi-IN", "en"]);   // "xx-YY" is not real

console.log(nf.resolvedOptions().locale);    // "hi-IN"
console.log(Intl.NumberFormat.supportedLocalesOf(["en-IN", "xx-YY", "hi"]));   // ["en-IN", "hi"]
console.log(Intl.getCanonicalLocales("EN-in"));                                  // ["en-IN"]

A tag that is written wrongly (for example "not_a_locale") throws a RangeError.

resolvedOptions(): what did I really get?

Every formatter can tell you the final settings it is using:

const formatter = new Intl.NumberFormat("en-IN", { style: "currency", currency: "INR" });

const settings = formatter.resolvedOptions();
console.log(settings.locale);                // "en-IN"
console.log(settings.minimumFractionDigits); // 2

For dates, new Intl.DateTimeFormat().resolvedOptions().timeZone gives the user’s time zone (for example "Asia/Calcutta").

Create once, use many times

Creating a formatter does real work (it loads language data). Using it is fast. So create it once and call format many times:

const money = new Intl.NumberFormat("en-IN", { style: "currency", currency: "INR" });

const prices = [499, 1299.5, 80000];

console.log(prices.map((p) => money.format(p)));   // ["₹499.00", "₹1,299.50", "₹80,000.00"]
console.log(prices.map(money.format));             // the same: format is already bound to its formatter

(Calling number.toLocaleString("en-IN", options) in a loop of thousands of items makes a new formatter every time, and is slower.)

Intl.NumberFormat: numbers, money, percentages, units

new Intl.NumberFormat(locale, options).format(number)

Currency

const inr = new Intl.NumberFormat("en-IN", { style: "currency", currency: "INR" });
const usd = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });
const eur = new Intl.NumberFormat("de-DE", { style: "currency", currency: "EUR" });

console.log(inr.format(1234567.5));   // "₹12,34,567.50"
console.log(usd.format(1234.5));      // "$1,234.50"
console.log(eur.format(1234.5));      // "1.234,50 €"

Two different things are at work:

  • The locale decides the format (commas, dots, the position of the symbol).
  • The currency ("INR", "USD", "EUR", from the ISO currency codes) decides which money it is.

You can mix them freely: an American user may want to see a price in rupees.

console.log(new Intl.NumberFormat("en-US", { style: "currency", currency: "INR" }).format(499));   // "₹499.00"

The currency is required when style is "currency". If you forget it, you get a TypeError. A wrong code like "XX" gives a RangeError.

Useful currency options:

const options = { style: "currency", currency: "USD" };

console.log(new Intl.NumberFormat("en-US", { ...options, currencyDisplay: "code" }).format(5));      // "USD 5.00"
console.log(new Intl.NumberFormat("en-US", { ...options, currencyDisplay: "name" }).format(5));      // "5.00 US dollars"
console.log(new Intl.NumberFormat("en-US", { ...options, currencySign: "accounting" }).format(-5)); // "($5.00)"
console.log(new Intl.NumberFormat("en-IN", { style: "currency", currency: "INR", maximumFractionDigits: 0 }).format(499));   // "₹499"

Each currency also has its own number of decimals. For example, Japanese yen has none:

console.log(new Intl.NumberFormat("ja-JP", { style: "currency", currency: "JPY" }).format(1234.5));   // "¥1,235"

Percentages and units

console.log(new Intl.NumberFormat("en-US", { style: "percent" }).format(0.256));                        // "26%"
console.log(new Intl.NumberFormat("en-US", { style: "percent", maximumFractionDigits: 1 }).format(0.256)); // "25.6%"

console.log(new Intl.NumberFormat("en", { style: "unit", unit: "kilometer-per-hour" }).format(72));    // "72 km/h"
console.log(new Intl.NumberFormat("en", { style: "unit", unit: "celsius" }).format(32));                // "32°C"
console.log(new Intl.NumberFormat("en", { style: "unit", unit: "liter", unitDisplay: "long" }).format(16)); // "16 liters"

Note that a percentage needs the fraction (0.256), not 25.6. Common units include kilometer, meter, kilogram, liter, celsius, megabyte, second, hour and many more. unitDisplay can be "short", "long" or "narrow".

Decimals and rounding

const two = new Intl.NumberFormat("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });

console.log(two.format(5));          // "5.00"
console.log(two.format(5.678));      // "5.68"

console.log(new Intl.NumberFormat("en-US", { maximumSignificantDigits: 3 }).format(123456));   // "123,000"
console.log(new Intl.NumberFormat("en-US", { minimumIntegerDigits: 3 }).format(7));            // "007"
Option Meaning
minimumFractionDigits, maximumFractionDigits Smallest and largest number of digits after the decimal point
maximumSignificantDigits Round to this many meaningful digits
minimumIntegerDigits Pad with leading zeros
useGrouping: false No thousands separators (1234567)
signDisplay "always" shows +5, "exceptZero" hides the sign for 0
roundingMode How to round: "halfExpand" (default), "floor", "ceil" and more

Compact numbers (for social counts)

const compact = new Intl.NumberFormat("en-US", { notation: "compact" });

console.log(compact.format(1500));        // "1.5K"
console.log(compact.format(1234567));     // "1.2M"

const long = new Intl.NumberFormat("en-US", { notation: "compact", compactDisplay: "long" });
console.log(long.format(1234567));        // "1.2 million"

console.log(new Intl.NumberFormat("en-IN", { notation: "compact" }).format(1234567));   // "12L"  (lakh)
console.log(new Intl.NumberFormat("hi-IN", { notation: "compact" }).format(1234567));   // "12 लाख"

Look at the last two lines: the Indian style uses lakh, because Intl follows the local way of counting.

Other features

const nf = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });

console.log(nf.formatToParts(1234.5).map((p) => p.type + ":" + p.value));
// ["currency:$", "integer:1", "group:,", "integer:234", "decimal:.", "fraction:50"]

console.log(new Intl.NumberFormat("en-US", { style: "currency", currency: "USD", maximumFractionDigits: 0 }).formatRange(3, 5));
// "$3 – $5"

console.log(new Intl.NumberFormat("en-US").format(12345678901234567890n));   // "12,345,678,901,234,567,890"  (BigInt works)
console.log(new Intl.NumberFormat("en-US").format("1234.5"));                // "1,234.5"  (numeric strings work too)

Remember: Intl.NumberFormat only formats. It cannot parse text like "1.234,5" back into a number. Always keep the real number in your data, and format it only when you show it.

Money and floating point errors

Remember that 0.1 + 0.2 is 0.30000000000000004 (see the numbers lesson). For money, many apps store the amount in the smallest unit (paise or cents) as a whole number, and divide only for display:

const priceInPaise = 149950;                    // ₹1,499.50 stored as a whole number

const money = new Intl.NumberFormat("en-IN", { style: "currency", currency: "INR" });
console.log(money.format(priceInPaise / 100));  // "₹1,499.50"

Intl.DateTimeFormat: dates and times

new Intl.DateTimeFormat(locale, options).format(date)

The input must be a valid Date (see the dates lesson). An invalid date throws a RangeError.

In the examples below, we set timeZone: "UTC" so that the output does not depend on the computer that runs the code. In a real app you usually leave it out, so that each visitor sees their own time zone.

const date = new Date(Date.UTC(2026, 9, 10, 14, 5, 9));   // 10 October 2026, 14:05:09 UTC

The easy way: dateStyle and timeStyle

const style = (locale, options) =>
  new Intl.DateTimeFormat(locale, { timeZone: "UTC", ...options }).format(date);

console.log(style("en-US", { dateStyle: "full" }));     // "Saturday, October 10, 2026"
console.log(style("en-US", { dateStyle: "long" }));     // "October 10, 2026"
console.log(style("en-GB", { dateStyle: "medium" }));   // "10 Oct 2026"
console.log(style("en-US", { dateStyle: "short" }));    // "10/10/26"

console.log(style("en-US", { timeStyle: "short" }));    // "2:05 PM"
console.log(style("en-GB", { timeStyle: "short" }));    // "14:05"

console.log(style("en-US", { dateStyle: "medium", timeStyle: "short" }));   // "Oct 10, 2026, 2:05 PM"

The same date in other languages:

console.log(style("en-IN", { dateStyle: "long" }));   // "10 October 2026"
console.log(style("de-DE", { dateStyle: "long" }));   // "10. Oktober 2026"
console.log(style("fr-FR", { dateStyle: "full" }));   // "samedi 10 octobre 2026"
console.log(style("hi-IN", { dateStyle: "long" }));   // "10 अक्टूबर 2026"
console.log(style("ja-JP", { dateStyle: "long" }));   // "2026年10月10日"

The detailed way: choose each part

console.log(style("en-US", { weekday: "long", month: "long", day: "numeric" }));          // "Saturday, October 10"
console.log(style("en-US", { month: "short", year: "numeric" }));                         // "Oct 2026"
console.log(style("en-US", { year: "numeric", month: "2-digit", day: "2-digit" }));       // "10/10/2026"
console.log(style("hi-IN", { weekday: "long", day: "numeric", month: "long" }));          // "शनिवार, 10 अक्टूबर"
console.log(style("en-US", { hour: "2-digit", minute: "2-digit", hour12: false }));       // "14:05"
Option Values
weekday "long", "short", "narrow"
year "numeric", "2-digit"
month "numeric", "2-digit", "long", "short", "narrow"
day "numeric", "2-digit"
hour, minute, second "numeric", "2-digit"
hour12 / hourCycle true or false / "h12", "h23"
timeZone "UTC", "Asia/Kolkata", "America/New_York"…
timeZoneName "short", "long"

Careful: do not mix dateStyle or timeStyle with the detailed options (month, hour, …) in one formatter. That throws a TypeError. Choose one way.

Time zones

The same moment looks different in different places:

const show = (timeZone) =>
  new Intl.DateTimeFormat("en-US", { dateStyle: "medium", timeStyle: "short", timeZone }).format(date);

console.log(show("UTC"));                  // "Oct 10, 2026, 2:05 PM"
console.log(show("Asia/Kolkata"));         // "Oct 10, 2026, 7:35 PM"
console.log(show("America/New_York"));     // "Oct 10, 2026, 10:05 AM"
console.log(show("Asia/Tokyo"));           // "Oct 10, 2026, 11:05 PM"

Time zone names use the form Region/City. You can read the visitor’s own zone with Intl.DateTimeFormat().resolvedOptions().timeZone. Store dates as UTC or ISO text, and convert to the viewer’s zone only when you show them, as the dates lesson recommends.

Date ranges and parts

const start = new Date(Date.UTC(2026, 9, 10));
const end = new Date(Date.UTC(2026, 9, 15));

const range = new Intl.DateTimeFormat("en-US", { dateStyle: "medium", timeZone: "UTC" });

console.log(range.formatRange(start, end));   // "Oct 10 – 15, 2026"  (smart: shared month and year)
console.log(range.formatToParts(start).map((p) => p.type + ":" + p.value));
// ["month:Oct", "literal: ", "day:10", "literal:, ", "year:2026"]

Note: the exact spaces in some results (like the one before PM) can be special narrow spaces, and small details may differ slightly between browsers. Never compare formatted text in your logic. Format only for display.

Intl.RelativeTimeFormat: “yesterday”, “in 3 hours”

new Intl.RelativeTimeFormat(locale, options).format(number, unit)

The number is negative for the past and positive for the future. The unit can be "second", "minute", "hour", "day", "week", "month", "quarter" or "year".

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

console.log(rtf.format(-1, "day"));     // "yesterday"
console.log(rtf.format(0, "day"));      // "today"
console.log(rtf.format(1, "day"));      // "tomorrow"
console.log(rtf.format(-3, "hour"));    // "3 hours ago"
console.log(rtf.format(2, "week"));     // "in 2 weeks"
console.log(rtf.format(-1, "month"));   // "last month"

numeric: "auto" gives natural words when there is one. The default, "always", always uses numbers:

console.log(new Intl.RelativeTimeFormat("en").format(-1, "day"));    // "1 day ago"
console.log(new Intl.RelativeTimeFormat("en", { style: "short" }).format(-5, "minute"));   // "5 min. ago"

Other languages work automatically:

console.log(new Intl.RelativeTimeFormat("hi", { numeric: "auto" }).format(-1, "day"));   // "कल"
console.log(new Intl.RelativeTimeFormat("es", { numeric: "auto" }).format(1, "day"));    // "mañana"

Intl does not choose the unit for you

RelativeTimeFormat only writes the text. You must work out the number and the unit. Here is a helper that picks the biggest sensible unit:

function timeAgo(date, now = new Date(), locale = "en") {
  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
  const seconds = Math.round((date - now) / 1000);   // negative for the past

  const units = [
    ["year", 31536000],
    ["month", 2592000],
    ["week", 604800],
    ["day", 86400],
    ["hour", 3600],
    ["minute", 60],
    ["second", 1]
  ];

  for (const [unit, size] of units) {
    if (Math.abs(seconds) >= size || unit === "second") {
      return rtf.format(Math.trunc(seconds / size), unit);
    }
  }
}

const now = new Date(Date.UTC(2026, 9, 10, 12, 0, 0));

console.log(timeAgo(new Date(now - 5 * 1000), now));              // "5 seconds ago"
console.log(timeAgo(new Date(now - 3 * 3600 * 1000), now));       // "3 hours ago"
console.log(timeAgo(new Date(now - 24 * 3600 * 1000), now));      // "yesterday"
console.log(timeAgo(new Date(now - 10 * 24 * 3600 * 1000), now)); // "last week"
console.log(timeAgo(new Date(+now + 2 * 24 * 3600 * 1000), now)); // "in 2 days"
console.log(timeAgo(new Date(now - 3 * 3600 * 1000), now, "hi"));  // "3 घंटे पहले"

Intl.Collator: sorting and comparing text correctly

The default array.sort() compares the raw character codes. For text that is wrong, because accented letters and capital letters end up in strange places:

const people = ["Zoë", "Åsa", "Ana", "Émile", "Zack", "ana"];

console.log([...people].sort());
// ["Ana", "Zack", "Zoë", "ana", "Åsa", "Émile"]   (capitals first, accents last)

A collator compares text the way a dictionary in that language would. Its compare method works directly with sort (you met localeCompare in the array sorting lesson; a collator is the same idea, but reusable):

const english = new Intl.Collator("en");

console.log([...people].sort(english.compare));
// ["ana", "Ana", "Åsa", "Émile", "Zack", "Zoë"]

Languages sort differently. In Swedish, å, ä and ö are separate letters at the end of the alphabet:

console.log(["z", "a", "ä", "ö"].sort(new Intl.Collator("sv").compare));   // ["a", "z", "ä", "ö"]
console.log(["z", "a", "ä", "ö"].sort(new Intl.Collator("de").compare));   // ["a", "ä", "ö", "z"]

Options

Numeric sorting. Natural order for names with numbers:

const files = ["file10", "file2", "file1"];

console.log([...files].sort());                                          // ["file1", "file10", "file2"]
console.log([...files].sort(new Intl.Collator("en", { numeric: true }).compare));   // ["file1", "file2", "file10"]

Sensitivity. What counts as “the same”?

sensitivity a vs A a vs á
"base" same same
"accent" same different
"case" different same
"variant" (default) different different
const base = new Intl.Collator("en", { sensitivity: "base" });

console.log(base.compare("résumé", "resume"));   // 0  (the same)
console.log(base.compare("a", "A"));             // 0

Case order and punctuation.

console.log(["b", "B", "a", "A"].sort(new Intl.Collator("en", { caseFirst: "upper" }).compare));   // ["A", "a", "B", "b"]
console.log(new Intl.Collator("en", { ignorePunctuation: true }).compare("a-b", "ab"));            // 0

compare(a, b) returns a negative number if a comes first, a positive number if b comes first, and 0 if they are equal, just like the sort function you already know.

With sensitivity: "base" you can find “café” when the user types “cafe” or “CAFE”:

const match = new Intl.Collator("en", { sensitivity: "base" });

const menu = ["café", "Cafe", "CAFÉ", "tea"];

console.log(menu.filter((item) => match.compare(item, "cafe") === 0));   // ["café", "Cafe", "CAFÉ"]

Intl.PluralRules: “1 item”, “2 items” in every language

In English there are two forms: one and many. Other languages have more (Russian has several, Arabic has six). PluralRules tells you which category a number belongs to, and you choose the word.

const rules = new Intl.PluralRules("en");

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

The categories are "zero", "one", "two", "few", "many" and "other". Each language uses only some of them:

console.log([0, 1, 2, 3, 11, 100].map((n) => new Intl.PluralRules("ar").select(n)));
// ["zero", "one", "two", "few", "many", "other"]    (Arabic uses all six)

console.log([1, 2, 5, 21, 22].map((n) => new Intl.PluralRules("ru").select(n)));
// ["one", "few", "many", "one", "few"]

console.log([0, 1, 2].map((n) => new Intl.PluralRules("hi").select(n)));
// ["one", "one", "other"]      (in Hindi, 0 counts as "one")

console.log([1, 2].map((n) => new Intl.PluralRules("ja").select(n)));
// ["other", "other"]           (Japanese has no plural forms)

A pluralize helper

function pluralize(count, forms, locale = "en") {
  const category = new Intl.PluralRules(locale).select(count);
  return count + " " + (forms[category] ?? forms.other);
}

const messageForms = { one: "message", other: "messages" };

console.log(pluralize(0, messageForms));   // "0 messages"
console.log(pluralize(1, messageForms));   // "1 message"
console.log(pluralize(2, messageForms));   // "2 messages"

const fileForms = { one: "файл", few: "файла", many: "файлов", other: "файла" };

console.log(pluralize(1, fileForms, "ru"));    // "1 файл"
console.log(pluralize(2, fileForms, "ru"));    // "2 файла"
console.log(pluralize(5, fileForms, "ru"));    // "5 файлов"
console.log(pluralize(21, fileForms, "ru"));   // "21 файл"

Because of this, count === 1 ? "item" : "items" is only correct for languages that work like English.

Ordinals: 1st, 2nd, 3rd, 4th

Add type: "ordinal":

const ordinal = new Intl.PluralRules("en", { type: "ordinal" });

const suffixes = { one: "st", two: "nd", few: "rd", other: "th" };

function withSuffix(n) {
  return n + suffixes[ordinal.select(n)];
}

console.log([1, 2, 3, 4, 11, 12, 21, 22, 23, 101, 111].map(withSuffix));
// ["1st", "2nd", "3rd", "4th", "11th", "12th", "21st", "22nd", "23rd", "101st", "111th"]

Notice 11th, 12th and 111th: the rules handle the exceptions that you would easily forget.

To see which categories a language uses: new Intl.PluralRules("en").resolvedOptions().pluralCategories.

Intl.ListFormat: “A, B, and C”

new Intl.ListFormat(locale, options).format(array)
const names = ["Riya", "Karan", "Aman"];

console.log(new Intl.ListFormat("en").format(["Riya"]));            // "Riya"
console.log(new Intl.ListFormat("en").format(["Riya", "Karan"]));   // "Riya and Karan"
console.log(new Intl.ListFormat("en").format(names));               // "Riya, Karan, and Aman"

The language decides the punctuation and the “and” word:

console.log(new Intl.ListFormat("en-GB").format(["A", "B", "C"]));   // "A, B and C"   (no comma before "and")
console.log(new Intl.ListFormat("de").format(["A", "B", "C"]));      // "A, B und C"
console.log(new Intl.ListFormat("es").format(["a", "b", "c"]));      // "a, b y c"
console.log(new Intl.ListFormat("hi").format(["राम", "श्याम", "सीता"]));   // "राम, श्याम, और सीता"
console.log(new Intl.ListFormat("ja").format(["A", "B", "C"]));      // "A、B、C"

Types and styles

const items = ["A", "B", "C"];

console.log(new Intl.ListFormat("en", { type: "conjunction" }).format(items));   // "A, B, and C"   ("and")
console.log(new Intl.ListFormat("en", { type: "disjunction" }).format(items));   // "A, B, or C"    ("or")
console.log(new Intl.ListFormat("en", { type: "unit" }).format(["5 ft", "2 in"])); // "5 ft, 2 in"    (no word)

console.log(new Intl.ListFormat("en", { style: "short" }).format(items));        // "A, B, & C"
console.log(new Intl.ListFormat("en", { style: "narrow", type: "unit" }).format(["5 ft", "2 in"]));   // "5 ft 2 in"

format accepts any iterable (see the iterators lesson), for example a Set:

console.log(new Intl.ListFormat("en").format(new Set(["x", "y"])));   // "x and y"

Bonus tools

These are not needed every day, but they are very handy. They are supported by modern browsers, so check the support table before using them in a project for older browsers.

Intl.DisplayNames: names of countries, languages and currencies

const regions = new Intl.DisplayNames("en", { type: "region" });
const languages = new Intl.DisplayNames("en", { type: "language" });
const currencies = new Intl.DisplayNames("en", { type: "currency" });

console.log(regions.of("IN"));           // "India"
console.log(languages.of("hi"));         // "Hindi"
console.log(languages.of("en-IN"));      // "English (India)"
console.log(currencies.of("INR"));       // "Indian Rupee"

console.log(new Intl.DisplayNames("hi", { type: "region" }).of("IN"));   // "भारत"

This is perfect for country and language dropdowns that show names in the user’s language.

Intl.Segmenter: count real characters and words

In the iterators lesson you saw that [..."A👍"] counts an emoji as one character. But some emojis are made of several code points (skin tones, families). A segmenter counts what a human sees:

const text = "A👍🏽👨‍👩‍👧";

console.log(text.length);                                                             // 13
console.log([...text].length);                                                        // 8
console.log([...new Intl.Segmenter("en", { granularity: "grapheme" }).segment(text)].length);   // 3  (A, thumbs up, family)

const words = new Intl.Segmenter("en", { granularity: "word" }).segment("Hello big world");
console.log([...words].filter((part) => part.isWordLike).map((part) => part.segment));   // ["Hello", "big", "world"]

Intl.Locale

const locale = new Intl.Locale("en-IN");

console.log(locale.language);                       // "en"
console.log(locale.region);                         // "IN"
console.log(new Intl.Locale("hi").maximize().toString());   // "hi-Deva-IN"  (likely script and region added)

Real-life use cases

1. A price list that changes with the user’s country

function createPriceFormatter(locale, currency) {
  const formatter = new Intl.NumberFormat(locale, { style: "currency", currency });
  return (amount) => formatter.format(amount);
}

const inINR = createPriceFormatter("en-IN", "INR");
const inUSD = createPriceFormatter("en-US", "USD");
const inEUR = createPriceFormatter("de-DE", "EUR");

console.log(inINR(1499));    // "₹1,499.00"
console.log(inUSD(18.5));    // "$18.50"
console.log(inEUR(17.25));   // "17,25 €"

2. Follower and view counts

const compact = new Intl.NumberFormat("en", { notation: "compact", maximumFractionDigits: 1 });

console.log(compact.format(999));        // "999"
console.log(compact.format(15300));      // "15.3K"
console.log(compact.format(2400000));    // "2.4M"

3. A social feed with “time ago”

Use the timeAgo(date) helper above on every post. Fresh posts show “3 minutes ago”, older ones “last week”, and the text works in any language, just by changing the locale.

4. An event time in the viewer’s own time zone

const eventStart = new Date("2026-11-05T15:00:00Z");   // stored as UTC

const forViewer = new Intl.DateTimeFormat(undefined, {
  dateStyle: "full",
  timeStyle: "short"
});

console.log(forViewer.format(eventStart));   // different for each visitor, in their language and time zone

5. A contact list sorted and searched correctly

const collator = new Intl.Collator("en", { sensitivity: "base", numeric: true });

const contacts = ["Émile", "Zoë", "ana", "Ana", "Åsa"];

console.log([...contacts].sort(collator.compare));                          // sorted like a dictionary
console.log(contacts.filter((name) => collator.compare(name, "emile") === 0));   // ["Émile"]

6. “You have 1 new message”

function notificationText(count, locale = "en") {
  const category = new Intl.PluralRules(locale).select(count);
  const forms = { one: "new message", other: "new messages" };

  return "You have " + new Intl.NumberFormat(locale).format(count) + " " + (forms[category] ?? forms.other);
}

console.log(notificationText(1));      // "You have 1 new message"
console.log(notificationText(1250));   // "You have 1,250 new messages"

7. A leaderboard with ordinals and lists

const ordinal = new Intl.PluralRules("en", { type: "ordinal" });
const suffixes = { one: "st", two: "nd", few: "rd", other: "th" };
const list = new Intl.ListFormat("en");

const winners = ["Riya", "Karan", "Aman"];

winners.forEach((name, index) => {
  const place = index + 1;
  console.log(place + suffixes[ordinal.select(place)] + " place: " + name);
});
// "1st place: Riya", "2nd place: Karan", "3rd place: Aman"

console.log("Congratulations to " + list.format(winners) + "!");   // "Congratulations to Riya, Karan, and Aman!"

8. Style the currency symbol with formatToParts

const money = new Intl.NumberFormat("en-IN", { style: "currency", currency: "INR" });

const html = money
  .formatToParts(1499)
  .map((part) => (part.type === "currency" ? "<small>" + part.value + "</small>" : part.value))
  .join("");

console.log(html);   // "<small>₹</small>1,499.00"

9. A language switcher that reuses formatters

const cache = new Map();

function getFormatters(locale) {
  if (!cache.has(locale)) {
    cache.set(locale, {
      number: new Intl.NumberFormat(locale),
      date: new Intl.DateTimeFormat(locale, { dateStyle: "long", timeZone: "UTC" }),
      list: new Intl.ListFormat(locale)
    });
  }
  return cache.get(locale);
}

const fmt = getFormatters("de-DE");

console.log(fmt.number.format(1234567.891));                  // "1.234.567,891"
console.log(fmt.date.format(new Date(Date.UTC(2026, 9, 10)))); // "10. Oktober 2026"
console.log(fmt.list.format(["A", "B", "C"]));                // "A, B und C"

The Map makes sure each locale’s formatters are created only once, which is good for speed (and connects to the caching ideas of the memory lesson).

Common mistakes

  • Building formats by hand ("₹" + price.toFixed(2), day + "/" + month). Use Intl.
  • Forgetting the currency when style is "currency". It throws a TypeError.
  • Using a wrong locale or currency code. A badly formed tag or code throws a RangeError. Check the spelling (en-IN, not en_IN).
  • Mixing dateStyle or timeStyle with month, hour and similar options. It throws a TypeError.
  • Passing an invalid date (new Date("x")). It throws a RangeError.
  • Using a percentage as 25.6 instead of 0.256.
  • Trying to parse formatted text back into a number or comparing formatted strings in code. Keep the real values, and format only for display.
  • Assuming identical output everywhere. Spaces (including narrow no-break spaces) and small details can differ between browsers and versions.
  • Leaving out the timeZone in tests and getting different results on different computers.
  • Using count === 1 ? "item" : "items" for all languages. Use PluralRules.
  • Sorting text with plain sort(). Use a Collator (or localeCompare).
  • Creating a new formatter inside a loop or on every render. Create it once and reuse it.
  • Storing money as floating-point numbers. Store whole numbers of paise or cents.
  • Forgetting that RelativeTimeFormat does not choose the unit. You calculate the number and the unit.
  • Translating text by concatenating pieces ("You have " + n + " " + word). Word order differs between languages. For real translations use a message library, and use Intl for the number, plural and list parts.

Practice

  1. Format 1234567.891 with en-US, en-IN, de-DE and fr-FR. Compare the results.
  2. Format 1499.5 as rupees, dollars and euros, each with the matching locale. Then format the rupee amount with the en-US locale. What changes?
  3. Forget the currency on purpose. Read the error. Then write a wrong currency code and read that error.
  4. Show 0.256 as a percent with no decimals, and with one decimal.
  5. Show 72 as km/h, 32 as degrees Celsius and 16 as liters (long form).
  6. Format 1500, 1234567 and 999 in compact notation. Then use compactDisplay: "long", and the en-IN locale.
  7. Use signDisplay: "always" to show +5 and -5. Use minimumIntegerDigits to show 7 as 007.
  8. Use formatToParts on a price and print the types of the parts.
  9. Create a Date with Date.UTC. Format it with dateStyle "full", "long", "medium" and "short", in en-US and en-IN.
  10. Format the same date in de-DE, fr-FR, hi-IN and ja-JP.
  11. Show the same moment in Asia/Kolkata, America/New_York and Asia/Tokyo, using timeZone.
  12. Mix dateStyle with month in one formatter and read the error.
  13. Use formatRange to print “Oct 10 – 15, 2026”.
  14. Print the visitor’s own time zone with resolvedOptions().timeZone.
  15. Use RelativeTimeFormat to print “yesterday”, “tomorrow”, “3 hours ago” and “in 2 weeks”. Do it again with numeric: "always".
  16. Write timeAgo(date) from memory, and test it with five dates. Try it with the hi and es locales.
  17. Sort ["Zoë", "Åsa", "Ana", "Émile", "Zack"] with plain sort(), with an English collator and with a Swedish collator.
  18. Sort ["file10", "file2", "file1"] with and without numeric: true.
  19. Write an accent-insensitive search that finds “café” when the user types “CAFE”.
  20. Write pluralize(count, forms, locale), and test it with English and Russian.
  21. Write withSuffix(n) that returns 1st, 2nd, 3rd, 4th, and check 11, 12, 13, 21, 101 and 111.
  22. Format a list of three names in en, en-GB, de and hi. Then make the “or” version.
  23. Use Intl.DisplayNames to print the names of five countries in English and in Hindi.
  24. Challenge: build a small shop page with a language dropdown (en-IN, en-US, de-DE, hi-IN). When the user changes it, the prices, date, stock text (“1 item left” / “5 items left”) and list of tags all update. Create the formatters only once per locale.
  25. Challenge: write formatDuration(seconds) that returns text like "2 hours, 5 minutes, and 9 seconds" using NumberFormat with the unit style and ListFormat.
  26. Challenge: build a countdown to a future date that shows "in 3 days" using RelativeTimeFormat, and updates every minute.

Recap

  • Intl is the built-in toolbox for internationalization: formatting for different languages and countries. You give it data and a locale (like "en-IN"), and it returns correctly formatted text.
  • A locale is a language, plus an optional region, such as en, en-US, hi-IN. Use undefined for the user’s default (navigator.language). A bad tag throws a RangeError.
  • Create a formatter once and reuse it. resolvedOptions() shows the final settings.
  • Intl.NumberFormat formats numbers: currency (with a required currency code), percent, unit, compact notation, decimals, significant digits, signDisplay, formatToParts and formatRange. It only formats, it does not parse. Store money as whole minor units.
  • Intl.DateTimeFormat formats dates and times: use dateStyle / timeStyle or the detailed options (never both), set timeZone, and use formatRange and formatToParts. Store dates as UTC, show them in the viewer’s zone.
  • Intl.RelativeTimeFormat writes “yesterday” and “in 3 hours”. You calculate the number (negative is the past) and the unit.
  • Intl.Collator sorts and compares text like a dictionary: language rules, numeric order, sensitivity (for accent and case-insensitive search).
  • Intl.PluralRules returns a category (one, few, many, other…) that you map to words, also for ordinals (1st, 2nd). English n === 1 logic does not work for every language.
  • Intl.ListFormat joins items as “A, B, and C”, or “A, B, or C”, with the right punctuation for each language.
  • Bonus tools: DisplayNames (country, language and currency names), Segmenter (real characters and words) and Locale.
  • Never compare or parse formatted text, and expect small differences between browsers.
  • Next you will learn debounce and throttle: how to stop fast events (typing, scrolling, resizing) from running your code too often.

If you want to revisit the basics, read the numbers and math lesson, the dates and time lesson, the array sorting lesson and the browser BOM lesson.

Frequently asked questions

What is the JavaScript Intl API?

Intl is a built-in object that formats numbers, dates, times, lists, plurals and text comparisons according to the rules of a language and region (a locale). It removes the need to write formatting code by hand for each country.

What is the difference between toLocaleString and Intl.NumberFormat?

They use the same engine, and give the same results. toLocaleString is a quick shortcut for one value. Intl.NumberFormat creates a reusable formatter, which is better and faster when you format many values, and it offers extra methods like formatToParts and formatRange.

How do I format a price in rupees or dollars?

Use new Intl.NumberFormat(“en-IN”, { style: “currency”, currency: “INR” }).format(1499). The locale controls the number style, and the currency code decides which money is shown. Change both to get other countries.

How do I show "3 hours ago" in JavaScript?

Use Intl.RelativeTimeFormat. Calculate how far the date is from now in a suitable unit, then call format(-3, “hour”). A negative number means the past. With numeric: “auto” you get words like “yesterday” when they exist.

Why should I use Intl.PluralRules instead of checking if the count is 1?

Many languages have more than two plural forms, and some count zero or fractions differently. PluralRules gives the right category for each language, so you can pick the right word. It also supports ordinals such as 1st, 2nd and 3rd.

How do I sort text with accents correctly?

Use Intl.Collator (or localeCompare) with the user’s locale, for example names.sort(new Intl.Collator(“en”).compare). Add { numeric: true } for natural number order, and { sensitivity: “base” } to ignore accents and case when comparing.

Does Intl translate text into other languages?

No. Intl formats numbers, dates, lists, plurals and sorting for a locale, and can give country, language and currency names. It does not translate your own sentences. For that you need translated text files and a translation library.

See also: Numbers and Math, Dates and Time, Iterators, JavaScript Cheat Sheet