JavaScript Intl API Guide

The Intl API provides language-sensitive formatting and comparison. Here's how to use it.

Number Formatting#

// Basic number formatting
const formatter = new Intl.NumberFormat('en-US');
console.log(formatter.format(1234567.89)); // '1,234,567.89'

// Different locales
console.log(new Intl.NumberFormat('de-DE').format(1234567.89)); // '1.234.567,89'
console.log(new Intl.NumberFormat('fr-FR').format(1234567.89)); // '1 234 567,89'
console.log(new Intl.NumberFormat('ja-JP').format(1234567.89)); // '1,234,567.89'

// Currency formatting
const currency = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
});
console.log(currency.format(1234.56)); // '$1,234.56'

const euro = new Intl.NumberFormat('de-DE', {
  style: 'currency',
  currency: 'EUR',
});
console.log(euro.format(1234.56)); // '1.234,56 €'

// Compact notation
const compact = new Intl.NumberFormat('en-US', {
  notation: 'compact',
  compactDisplay: 'short',
});
console.log(compact.format(1234567)); // '1.2M'

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

Percentage and Units#

// Percentage
const percent = new Intl.NumberFormat('en-US', {
  style: 'percent',
  minimumFractionDigits: 1,
});
console.log(percent.format(0.1234)); // '12.3%'

// Units
const speed = new Intl.NumberFormat('en-US', {
  style: 'unit',
  unit: 'kilometer-per-hour',
});
console.log(speed.format(100)); // '100 km/h'

const temp = new Intl.NumberFormat('en-US', {
  style: 'unit',
  unit: 'celsius',
});
console.log(temp.format(25)); // '25°C'

const bytes = new Intl.NumberFormat('en-US', {
  style: 'unit',
  unit: 'megabyte',
});
console.log(bytes.format(512)); // '512 MB'

// Available units: acre, bit, byte, celsius, centimeter, day, degree,
// fahrenheit, fluid-ounce, foot, gallon, gigabit, gigabyte, gram, hectare,
// hour, inch, kilobit, kilobyte, kilogram, kilometer, liter, megabit,
// megabyte, meter, mile, mile-scandinavian, milliliter, millimeter,
// millisecond, minute, month, ounce, percent, petabyte, pound, second,
// stone, terabit, terabyte, week, yard, year

Date and Time Formatting#

const date = new Date('2024-03-15T14:30:00');

// Basic formatting
const dateFormatter = new Intl.DateTimeFormat('en-US');
console.log(dateFormatter.format(date)); // '3/15/2024'

// Different locales
console.log(new Intl.DateTimeFormat('de-DE').format(date)); // '15.3.2024'
console.log(new Intl.DateTimeFormat('ja-JP').format(date)); // '2024/3/15'

// Full date and time
const full = new Intl.DateTimeFormat('en-US', {
  dateStyle: 'full',
  timeStyle: 'long',
});
console.log(full.format(date));
// 'Friday, March 15, 2024 at 2:30:00 PM GMT-4'

// Custom options
const custom = new Intl.DateTimeFormat('en-US', {
  weekday: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  hour: '2-digit',
  minute: '2-digit',
});
console.log(custom.format(date));
// 'Friday, March 15, 2024, 02:30 PM'

// Time only
const time = new Intl.DateTimeFormat('en-US', {
  hour: 'numeric',
  minute: '2-digit',
  hour12: true,
});
console.log(time.format(date)); // '2:30 PM'

// Range formatting
const start = new Date('2024-03-15');
const end = new Date('2024-03-20');
const range = new Intl.DateTimeFormat('en-US', {
  month: 'short',
  day: 'numeric',
});
console.log(range.formatRange(start, end)); // 'Mar 15 – 20'

Relative Time#

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

console.log(rtf.format(-1, 'day'));     // 'yesterday'
console.log(rtf.format(1, 'day'));      // 'tomorrow'
console.log(rtf.format(-3, 'day'));     // '3 days ago'
console.log(rtf.format(2, 'week'));     // 'in 2 weeks'
console.log(rtf.format(-1, 'month'));   // 'last month'
console.log(rtf.format(1, 'year'));     // 'next year'

// Always show numbers
const rtfNumeric = new Intl.RelativeTimeFormat('en', { numeric: 'always' });
console.log(rtfNumeric.format(-1, 'day')); // '1 day ago'
console.log(rtfNumeric.format(1, 'day'));  // 'in 1 day'

// Different styles
const rtfShort = new Intl.RelativeTimeFormat('en', { style: 'short' });
console.log(rtfShort.format(-3, 'month')); // '3 mo. ago'

const rtfNarrow = new Intl.RelativeTimeFormat('en', { style: 'narrow' });
console.log(rtfNarrow.format(-3, 'month')); // '3mo ago'

// Helper function
function getRelativeTime(date) {
  const now = new Date();
  const diff = date - now;
  const seconds = Math.round(diff / 1000);
  const minutes = Math.round(seconds / 60);
  const hours = Math.round(minutes / 60);
  const days = Math.round(hours / 24);
  const weeks = Math.round(days / 7);
  const months = Math.round(days / 30);
  const years = Math.round(days / 365);

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

  if (Math.abs(seconds) < 60) return rtf.format(seconds, 'second');
  if (Math.abs(minutes) < 60) return rtf.format(minutes, 'minute');
  if (Math.abs(hours) < 24) return rtf.format(hours, 'hour');
  if (Math.abs(days) < 7) return rtf.format(days, 'day');
  if (Math.abs(weeks) < 4) return rtf.format(weeks, 'week');
  if (Math.abs(months) < 12) return rtf.format(months, 'month');
  return rtf.format(years, 'year');
}

List Formatting#

const list = new Intl.ListFormat('en', {
  style: 'long',
  type: 'conjunction',
});
console.log(list.format(['Apple', 'Banana', 'Orange']));
// 'Apple, Banana, and Orange'

const disjunction = new Intl.ListFormat('en', {
  style: 'long',
  type: 'disjunction',
});
console.log(disjunction.format(['Red', 'Green', 'Blue']));
// 'Red, Green, or Blue'

const unit = new Intl.ListFormat('en', {
  style: 'narrow',
  type: 'unit',
});
console.log(unit.format(['5 feet', '10 inches']));
// '5 feet 10 inches'

// Different locales
const germanList = new Intl.ListFormat('de', {
  style: 'long',
  type: 'conjunction',
});
console.log(germanList.format(['Äpfel', 'Bananen', 'Orangen']));
// 'Äpfel, Bananen und Orangen'

Plural Rules#

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

console.log(pr.select(0));  // 'other'
console.log(pr.select(1));  // 'one'
console.log(pr.select(2));  // 'other'

// Use for pluralization
function pluralize(count, singular, plural) {
  const pr = new Intl.PluralRules('en');
  return pr.select(count) === 'one' ? singular : plural;
}

console.log(`3 ${pluralize(3, 'item', 'items')}`); // '3 items'
console.log(`1 ${pluralize(1, 'item', 'items')}`); // '1 item'

// Ordinal numbers
const ordinal = new Intl.PluralRules('en', { type: 'ordinal' });

function getOrdinalSuffix(n) {
  const suffixes = {
    one: 'st',
    two: 'nd',
    few: 'rd',
    other: 'th',
  };
  return n + suffixes[ordinal.select(n)];
}

console.log(getOrdinalSuffix(1));  // '1st'
console.log(getOrdinalSuffix(2));  // '2nd'
console.log(getOrdinalSuffix(3));  // '3rd'
console.log(getOrdinalSuffix(4));  // '4th'
console.log(getOrdinalSuffix(21)); // '21st'

Collation (Sorting)#

// Locale-aware sorting
const names = ['Ängström', 'Zulu', 'Apple', 'Öresund'];

// Default sort (may not be locale-aware)
console.log([...names].sort());
// ['Apple', 'Zulu', 'Ängström', 'Öresund']

// Swedish sorting
const collator = new Intl.Collator('sv');
console.log([...names].sort(collator.compare));
// ['Apple', 'Zulu', 'Ängström', 'Öresund']
// (In Swedish, Ä and Ö come after Z)

// Case-insensitive
const insensitive = new Intl.Collator('en', { sensitivity: 'base' });
console.log(insensitive.compare('a', 'A')); // 0 (equal)
console.log(insensitive.compare('a', 'b')); // -1 (a < b)

// Natural sorting (numbers)
const files = ['file1', 'file10', 'file2', 'file21'];
const natural = new Intl.Collator('en', { numeric: true });
console.log([...files].sort(natural.compare));
// ['file1', 'file2', 'file10', 'file21']

Display Names#

// Language names
const langNames = new Intl.DisplayNames(['en'], { type: 'language' });
console.log(langNames.of('en'));    // 'English'
console.log(langNames.of('de'));    // 'German'
console.log(langNames.of('ja'));    // 'Japanese'

// Region names
const regionNames = new Intl.DisplayNames(['en'], { type: 'region' });
console.log(regionNames.of('US')); // 'United States'
console.log(regionNames.of('DE')); // 'Germany'
console.log(regionNames.of('JP')); // 'Japan'

// Currency names
const currencyNames = new Intl.DisplayNames(['en'], { type: 'currency' });
console.log(currencyNames.of('USD')); // 'US Dollar'
console.log(currencyNames.of('EUR')); // 'Euro'
console.log(currencyNames.of('JPY')); // 'Japanese Yen'

// Script names
const scriptNames = new Intl.DisplayNames(['en'], { type: 'script' });
console.log(scriptNames.of('Latn')); // 'Latin'
console.log(scriptNames.of('Cyrl')); // 'Cyrillic'

// In different languages
const germanDisplay = new Intl.DisplayNames(['de'], { type: 'language' });
console.log(germanDisplay.of('en')); // 'Englisch'
console.log(germanDisplay.of('de')); // 'Deutsch'

Segmenter#

// Word segmentation
const wordSegmenter = new Intl.Segmenter('en', { granularity: 'word' });
const words = [...wordSegmenter.segment('Hello, world!')];
console.log(words.map(s => s.segment));
// ['Hello', ',', ' ', 'world', '!']

// Sentence segmentation
const sentenceSegmenter = new Intl.Segmenter('en', { granularity: 'sentence' });
const text = 'Hello! How are you? I am fine.';
const sentences = [...sentenceSegmenter.segment(text)];
console.log(sentences.map(s => s.segment));
// ['Hello! ', 'How are you? ', 'I am fine.']

// Grapheme segmentation (useful for emojis)
const graphemeSegmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
const emoji = '👨‍👩‍👧‍👦';
const graphemes = [...graphemeSegmenter.segment(emoji)];
console.log(graphemes.length); // 1 (single family emoji)
console.log(emoji.length);      // 11 (code units)

Best Practices#

Usage:
✓ Cache formatters for reuse
✓ Handle missing locale gracefully
✓ Use formatToParts for custom rendering
✓ Test with multiple locales

Performance:
✓ Create formatters once, reuse
✓ Use appropriate precision
✓ Avoid creating in loops
✓ Consider memoization

Fallbacks:
✓ Provide default locale
✓ Handle unsupported features
✓ Test browser compatibility
✓ Use polyfills if needed

The Intl API provides comprehensive internationalization support. Use it for numbers, dates, lists, and sorting. Cache formatter instances for performance and test with various locales to ensure proper display across regions.