JS Intl API Guide

Finding Locales & Time Zones

To use the `Intl` API effectively, you need to provide valid BCP 47 language tags for locales and IANA identifiers for time zones. Here are some resources to find them.

Finding BCP 47 Language Tags

Finding Time Zone Identifiers

console.log(Intl.supportedValuesOf('timeZone'));
                        

Intl.DateTimeFormat

Formats dates and times in a locale-sensitive way. This is one of the most powerful and commonly used features of the Intl API.

Experiment below with various locales and formatting options to see how the output changes.

Intl.NumberFormat

Formats numbers, currencies, and units.

Notice how decimal separators, grouping, and currency symbols change based on the selected locale and options.

Intl.Collator

Provides language-sensitive string comparison for sorting. Default JavaScript `sort()` uses Unicode code points, which is often incorrect for alphabetical sorting in many languages.

Select a locale to see how the list re-sorts correctly.

Intl.PluralRules

Determines which plural category a number belongs to in a given language. English has "one" and "other", but other languages like Polish or Arabic have more complex rules.

This is essential for correct translations in applications that support multiple languages.

Intl.RelativeTimeFormat

Formats a time difference in a human-readable way, like "in 3 weeks" or "2 months ago".

The `numeric: 'auto'` option allows for friendly terms like "yesterday" or "tomorrow".

Intl.ListFormat

Formats a list of strings with locale-appropriate connectors.

This handles things like the Oxford comma in English correctly.

Intl.DisplayNames

Provides translated names for languages, regions, scripts, or currencies.

For example, it can tell you that "de" is "German" in English or "allemand" in French.

Intl.Segmenter

Provides locale-sensitive text segmentation.

It can correctly split a string into graphemes (what users perceive as characters), words, or sentences, which is far more reliable than `string.split()`.

Intl.Locale

A constructor to parse and manipulate BCP 47 locale identifier strings.

It allows you to programmatically access parts of a locale string like the language, region, or script.

The Future: Interaction with Temporal API

The Temporal API is a new, modern date/time API for JavaScript, currently at Stage 3 in the TC39 process. It is designed to be a superior replacement for the old `Date` object.

Temporal objects can be passed directly to `Intl.DateTimeFormat` instances, creating a clean, robust way to work with dates and times.

Example: ZonedDateTime Formatting

Format a specific moment in time (a date, time, and timezone) for a user in a specific locale.

// This conceptual code requires the Temporal polyfill to run.

// 1. Create an immutable Temporal object.
const zonedDateTime = Temporal.ZonedDateTime.from({
  year: 2025,
  month: 8,
  day: 29,
  timeZone: 'America/Los_Angeles',
});

// 2. Format it using Intl.DateTimeFormat.
const formatter = new Intl.DateTimeFormat('de-DE', {
  dateStyle: 'full',
  timeStyle: 'long',
  timeZone: 'America/Los_Angeles',
});

// Note: In browsers without native Temporal support, we must convert
// to a legacy Date object before formatting.
const legacyDate = new Date(zonedDateTime.toInstant().epochMilliseconds);

// The formatted output will be similar to:
// "Freitag, 29. August 2025 um 00:00:00 PDT"
console.log(formatter.format(legacyDate));
                        

Example: PlainDate Formatting

Format a calendar date that has no time or timezone information, like a birthday.

// This conceptual code requires the Temporal polyfill to run.

// 1. Create a date object without time or timezone.
const plainDate = Temporal.PlainDate.from({
  year: 1776,
  month: 7,
  day: 4,
});

// 2. Format it using Intl.DateTimeFormat.
const formatter = new Intl.DateTimeFormat('en-US', {
  dateStyle: 'long',
  timeZone: 'UTC', // Required for consistent output
});

// Note: In browsers without native Temporal support, we must convert
// to a legacy Date object before formatting.
const legacyDate = new Date(Date.UTC(plainDate.year, plainDate.month - 1, plainDate.day));

// The formatted output will be:
// "July 4, 1776"
console.log(formatter.format(legacyDate));