Locale-aware number formatting (currency, percent, units).
All Browsers
Intl.Collator
Locale-aware string comparison and sorting.
All Browsers
Intl.PluralRules
Locale-aware pluralization rules.
All Modern Browsers
Intl.RelativeTimeFormat
Locale-aware relative time formatting ("2 days ago").
All Modern Browsers
Intl.ListFormat
Locale-aware list formatting ("A, B, and C").
All Modern Browsers
Intl.DisplayNames
Locale-aware display names for languages, regions, scripts.
All Modern Browsers
Intl.Locale
Locale identifier parsing and manipulation.
All Modern Browsers
Common Method
Description
Intl.getCanonicalLocales(locales)
Returns canonical locale identifiers.
Intl.supportedValuesOf(key)
Returns supported values for key: "calendar", "currency", "timeZone", etc.
Example: Check supported locales and values
// Get canonical locale identifiersconst locales = Intl.getCanonicalLocales(["EN-us", "en-GB", "ja-JP"]);console.log("Canonical locales:", locales);// Output: ["en-US", "en-GB", "ja-JP"]// Check supported currenciesif (Intl.supportedValuesOf) { const currencies = Intl.supportedValuesOf("currency"); console.log("Supported currencies:", currencies.slice(0, 10)); // Output: ["AED", "AFN", "ALL", "AMD", "ANG", ...] // Check if specific currency is supported const hasEUR = currencies.includes("EUR"); console.log("EUR supported:", hasEUR); // Get all time zones const timeZones = Intl.supportedValuesOf("timeZone"); console.log("Time zones count:", timeZones.length); console.log("Sample time zones:", timeZones.slice(0, 5)); // Output: ["Africa/Abidjan", "Africa/Accra", ...] // Get all calendars const calendars = Intl.supportedValuesOf("calendar"); console.log("Supported calendars:", calendars); // Output: ["buddhist", "chinese", "gregory", "hebrew", "indian", ...] // Get all numbering systems const numberingSystems = Intl.supportedValuesOf("numberingSystem"); console.log("Numbering systems:", numberingSystems.slice(0, 10)); // Output: ["arab", "arabext", "bali", "beng", ...]}// Detect user's localeconst userLocale = navigator.language || navigator.userLanguage;console.log("User locale:", userLocale);// Output: "en-US" (or user's system locale)// Get all preferred localesconst userLocales = navigator.languages;console.log("User locales:", userLocales);// Output: ["en-US", "en", "es"]
Note: Intl object provides locale-aware formatting and parsing for dates, numbers, strings, and more. Uses Unicode CLDR data. Always specify locale or use user's locale from navigator.language. All formatters accept locale and options.
2. Intl.DateTimeFormat for Date Localization
Option
Values
Description
dateStyle
"full", "long", "medium", "short"
Predefined date format style. Cannot combine with individual date/time options.
timeStyle
"full", "long", "medium", "short"
Predefined time format style.
year
"numeric", "2-digit"
Year representation.
month
"numeric", "2-digit", "long", "short", "narrow"
Month representation.
day
"numeric", "2-digit"
Day representation.
weekday
"long", "short", "narrow"
Weekday representation.
hour
"numeric", "2-digit"
Hour representation.
minute
"numeric", "2-digit"
Minute representation.
second
"numeric", "2-digit"
Second representation.
timeZone
IANA time zone name
Time zone: "America/New_York", "Europe/London", "UTC", etc.
hour12
true, false
Use 12-hour or 24-hour time.
Example: Format dates in different locales
const date = new Date("2024-03-15T14:30:00");// Basic formatting with dateStyle and timeStyleconst formatterUS = new Intl.DateTimeFormat("en-US", { "dateStyle": "full", "timeStyle": "long"});console.log("en-US:", formatterUS.format(date));// Output: "Friday, March 15, 2024 at 2:30:00 PM"const formatterFR = new Intl.DateTimeFormat("fr-FR", { "dateStyle": "full", "timeStyle": "long"});console.log("fr-FR:", formatterFR.format(date));// Output: "vendredi 15 mars 2024 à 14:30:00"const formatterJA = new Intl.DateTimeFormat("ja-JP", { "dateStyle": "full", "timeStyle": "long"});console.log("ja-JP:", formatterJA.format(date));// Output: "2024年3月15日金曜日 14:30:00"// Custom formattingconst customFormatter = new Intl.DateTimeFormat("en-US", { "year": "numeric", "month": "long", "day": "numeric", "weekday": "long", "hour": "numeric", "minute": "2-digit", "hour12": true});console.log("Custom:", customFormatter.format(date));// Output: "Friday, March 15, 2024, 2:30 PM"// Different stylesconst styles = ["full", "long", "medium", "short"];styles.forEach(style => { const formatter = new Intl.DateTimeFormat("en-US", { "dateStyle": style }); console.log(`${style}:`, formatter.format(date));});// Output:// full: Friday, March 15, 2024// long: March 15, 2024// medium: Mar 15, 2024// short: 3/15/24
Example: Time zones and formatting parts
const date = new Date("2024-03-15T14:30:00Z");// Format in different time zonesconst timeZones = [ "America/New_York", "Europe/London", "Asia/Tokyo", "Australia/Sydney"];timeZones.forEach(timeZone => { const formatter = new Intl.DateTimeFormat("en-US", { "timeZone": timeZone, "dateStyle": "medium", "timeStyle": "long", "timeZoneName": "short" }); console.log(`${timeZone}:`, formatter.format(date));});// Output:// America/New_York: Mar 15, 2024, 10:30:00 AM EDT// Europe/London: Mar 15, 2024, 2:30:00 PM GMT// Asia/Tokyo: Mar 15, 2024, 11:30:00 PM JST// Australia/Sydney: Mar 16, 2024, 1:30:00 AM AEDT// Get formatted parts for custom renderingconst formatter = new Intl.DateTimeFormat("en-US", { "year": "numeric", "month": "long", "day": "numeric", "hour": "numeric", "minute": "2-digit"});const parts = formatter.formatToParts(date);console.log("Parts:", parts);// Output: [// { type: "month", value: "March" },// { type: "literal", value: " " },// { type: "day", value: "15" },// { type: "literal", value: ", " },// { type: "year", value: "2024" },// ...// ]// Build custom format from partsconst customFormat = parts.map(part => { if (part.type === "month") return `<strong>${part.value}</strong>`; if (part.type === "day") return `<span class="day">${part.value}</span>`; return part.value;}).join("");console.log("Custom HTML:", customFormat);// Format rangeconst startDate = new Date("2024-03-15");const endDate = new Date("2024-03-20");const range = formatter.formatRange(startDate, endDate);console.log("Range:", range);// Output: "March 15 – 20, 2024"
Note: Intl.DateTimeFormat provides locale-aware date/time formatting. Use dateStyle/timeStyle for quick formatting or individual options for custom formats. formatToParts() returns parts for custom rendering. formatRange() formats date ranges intelligently.
3. Intl.NumberFormat for Number Localization
Option
Values
Description
style
"decimal", "currency", "percent", "unit"
Number formatting style.
currency
ISO 4217 currency code
Currency: "USD", "EUR", "JPY", etc. Required if style is "currency".
currencyDisplay
"symbol", "code", "name", "narrowSymbol"
How to display currency.
unit
Unit identifier
Unit: "kilometer", "celsius", "byte", etc. Required if style is "unit".
Note: Intl.NumberFormat handles numbers, currency, percentages, and units. Use style option to choose format type. Compact notation great for large numbers. formatToParts() available for custom rendering. Automatically handles locale-specific grouping and decimals.
Note: Intl.Collator provides locale-aware string comparison for sorting and searching. Use compare method with Array.sort(). Set numeric: true for natural sorting of numbers in strings. Different sensitivity levels for search scenarios.
Note: Intl.PluralRules provides locale-specific plural categories. Different languages have different plural rules (English has 2, Russian has 4, Arabic has 6). Use select() to get category, then map to appropriate message. Use "ordinal" type for 1st, 2nd, 3rd formatting.
6. Intl.Locale for Language Tag Parsing
Property
Description
locale.language
Language subtag (e.g., "en", "fr", "zh").
locale.region
Region subtag (e.g., "US", "GB", "CN").
locale.script
Script subtag (e.g., "Latn", "Cyrl", "Hans").
locale.baseName
Base locale without extensions (e.g., "en-US").
locale.calendar
Calendar system (e.g., "gregory", "buddhist", "chinese").
locale.numberingSystem
Numbering system (e.g., "latn", "arab", "hanidec").
Example: Locale-specific calendar and numbering systems
// Use locale with different calendarconst gregorianLocale = new Intl.Locale("en-US", { "calendar": "gregory"});const buddhistLocale = new Intl.Locale("th-TH", { "calendar": "buddhist"});const date = new Date("2024-03-15");const gregorianFormatter = new Intl.DateTimeFormat(gregorianLocale, { "year": "numeric", "month": "long", "day": "numeric"});console.log("Gregorian:", gregorianFormatter.format(date));// Output: "March 15, 2024"const buddhistFormatter = new Intl.DateTimeFormat(buddhistLocale, { "year": "numeric", "month": "long", "day": "numeric"});console.log("Buddhist:", buddhistFormatter.format(date));// Output: "15 มีนาคม 2567" (year 2567 in Buddhist calendar)// Different numbering systemsconst arabicLocale = new Intl.Locale("ar-EG", { "numberingSystem": "arab"});const westernArabicLocale = new Intl.Locale("ar-EG", { "numberingSystem": "latn"});const number = 12345;const arabicFormatter = new Intl.NumberFormat(arabicLocale);console.log("Arabic digits:", arabicFormatter.format(number));// Output: "١٢٬٣٤٥"const latinFormatter = new Intl.NumberFormat(westernArabicLocale);console.log("Latin digits:", latinFormatter.format(number));// Output: "12,345"// Get locale infoconsole.log("\nLocale info:");console.log("Calendars:", Intl.supportedValuesOf("calendar"));console.log("Numbering systems:", Intl.supportedValuesOf("numberingSystem"));
Note: Intl.Locale parses and manipulates BCP 47 language tags. Use to extract language, region, script, and extensions. maximize() adds likely subtags, minimize() removes redundant ones. Can specify calendar, numbering system, hour cycle in locale.
Warning: Locale strings must be valid BCP 47 tags - invalid tags throw errors. Not all calendar/numbering systems supported in all browsers. Use Intl.supportedValuesOf() to check available values. maximize() and minimize() have limited browser support - check before using.
Internationalization and Formatting Best Practices
Always use Intl APIs for locale-sensitive formatting - don't build your own
Get user's locale from navigator.language or navigator.languages
Use Intl.supportedValuesOf() to check available currencies, time zones, etc.
DateTimeFormat: Use dateStyle/timeStyle for quick formatting
NumberFormat: Always specify currency with style: "currency"
Use compact notation for large numbers in UI (1.2B instead of 1,234,567,890)
Collator: Enable numeric: true for natural sorting of filenames
PluralRules: Build locale-aware pluralization - languages have different rules
Cache Intl formatters - creating formatters is expensive
Use formatToParts() when you need fine-grained control over rendering
Test with multiple locales - especially RTL languages (ar, he)
Consider time zones - use IANA time zone identifiers
Provide fallback locale if user's locale not supported