JavaScript Intl.DisplayNames API Explained

The Intl.DisplayNames object is a built-in JavaScript API that enables developers to obtain localized names for languages, regions, scripts, currencies, calendar types, and date-time fields directly from the runtime environment. By leveraging the Unicode Common Locale Data Repository (CLDR) embedded within modern browsers and Node.js, it eliminates the need to bundle large translation dictionaries for standard internationalization terms, significantly reducing bundle size while ensuring culturally accurate translations.

Understanding the Syntax

To create localized display names, instantiate an Intl.DisplayNames object by passing a locale identifier (or an array of locales) and a mandatory options object specifying the type of display name you require.

const displayNames = new Intl.DisplayNames(locales, options);

The primary method on the instance is of(), which accepts an ISO code or identifier string and returns the translated name.

Configuration Options

• type (Required): Defines the category of the identifier. Accepted values include 'language', 'region', 'script', 'currency', 'calendar', and 'dateTimeField'.
• style (Optional): Specifies the length of the output. Options are 'long' (default), 'short', and 'narrow'.
• fallback (Optional): Determines behavior when a translation is unavailable. Options are 'code' (default, returns the input code) or 'none' (returns undefined).
• languageDisplay (Optional): Used with type: 'language' to determine phrasing style. Options are 'dialect' (e.g., “American English”) or 'standard' (e.g., “English (United States)”).

Localizing Language Names

To translate language codes (ISO 639 standard) into human-readable labels, set the type property to 'language'.

// Display names in English
const enLanguages = new Intl.DisplayNames(['en'], { type: 'language' });
console.log(enLanguages.of('fr')); // "French"
console.log(enLanguages.of('de')); // "German"
console.log(enLanguages.of('zh-Hans')); // "Simplified Chinese"

// Display names in French
const frLanguages = new Intl.DisplayNames(['fr'], { type: 'language' });
console.log(frLanguages.of('en')); // "anglais"
console.log(frLanguages.of('es')); // "espagnol"
console.log(frLanguages.of('ja')); // "japonais"

You can also control the formatting nuance using languageDisplay:

const standardDisplay = new Intl.DisplayNames(['en'], { type: 'language', languageDisplay: 'standard' });
const dialectDisplay = new Intl.DisplayNames(['en'], { type: 'language', languageDisplay: 'dialect' });

console.log(standardDisplay.of('en-US')); // "English (United States)"
console.log(dialectDisplay.of('en-US'));  // "American English"

Localizing Region Names

To translate country or territory codes (ISO 3166-1 alpha-2 or UN M.49 numerical codes), set the type property to 'region'.

// Display region names in English
const enRegions = new Intl.DisplayNames(['en'], { type: 'region' });
console.log(enRegions.of('US')); // "United States"
console.log(enRegions.of('JP')); // "Japan"
console.log(enRegions.of('419')); // "Latin America"

// Display region names in Spanish
const esRegions = new Intl.DisplayNames(['es'], { type: 'region' });
console.log(esRegions.of('US')); // "Estados Unidos"
console.log(esRegions.of('DE')); // "Alemania"
console.log(esRegions.of('EG')); // "Egipto"

You can adjust the verbosity of country names using the style option:

const longNames = new Intl.DisplayNames(['en'], { type: 'region', style: 'long' });
const shortNames = new Intl.DisplayNames(['en'], { type: 'region', style: 'short' });

console.log(longNames.of('US'));  // "United States"
console.log(shortNames.of('US')); // "US"

Key Advantages

1. Zero Bundle Overhead: Localized strings are fetched from the underlying JavaScript runtime, removing thousands of lines of static JSON translation mappings.
2. Standard Compliance: The API follows official ISO standards for language codes (BCP 47), country codes (ISO 3166), and currency codes (ISO 4217).
3. Locale Fallback Handling: If a preferred regional dialect is missing, the engine automatically falls back to parent languages according to CLDR rules.