A polyfill for Intl.DisplayNames.

ECMA-402 Spec Compliance#

This package implements Intl.DisplayNames. See the conformance report for tested coverage and known limitations.

Specification Details#

• TC39 Proposal: Intl.DisplayNames
• Stage: Stage 4 (Finalized)

✅ Implemented Features#

Core Methods#

• of(code) - Returns the localized display name for a code
• resolvedOptions() - Returns resolved formatting options
• supportedLocalesOf(locales) - Returns supported locales

Display Name Types#

All 6 code types are supported:

• 'language' - Language display names (e.g., "en" → "English")
• 'region' - Region/country display names (e.g., "US" → "United States")
• 'script' - Script display names (e.g., "Latn" → "Latin")
• 'currency' - Currency display names (e.g., "USD" → "US Dollar")
• 'calendar' - Calendar display names (e.g., "gregory" → "Gregorian Calendar")
• 'dateTimeField' - Date/time field names (e.g., "hour" → "Hour")

Display Styles#

• 'long' (default) - Full display name (e.g., "United States")
• 'short' - Abbreviated display name (e.g., "US")
• 'narrow' - Most compact form (e.g., "U")

Language Display Options#

For type: 'language', the languageDisplay option controls dialect formatting:

• 'dialect' (default) - Show dialect (e.g., "Canadian French")
• 'standard' - Show standard form (e.g., "French")

Example Usage#

Global import#

import '@formatjs/intl-displaynames/polyfill.js'

// Language names
const languageNames = new Intl.DisplayNames(['en'], {type: 'language'})
languageNames.of('en') // "English"
languageNames.of('fr') // "French"
languageNames.of('zh') // "Chinese"

// Region names
const regionNames = new Intl.DisplayNames(['en'], {type: 'region'})
regionNames.of('US') // "United States"
regionNames.of('GB') // "United Kingdom"
regionNames.of('JP') // "Japan"

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

// Script names
const scriptNames = new Intl.DisplayNames(['en'], {type: 'script'})
scriptNames.of('Latn') // "Latin"
scriptNames.of('Arab') // "Arabic"
scriptNames.of('Hans') // "Simplified Chinese"

// Calendar names
const calendarNames = new Intl.DisplayNames(['en'], {type: 'calendar'})
calendarNames.of('gregory') // "Gregorian Calendar"
calendarNames.of('islamic') // "Islamic Calendar"

// Date/time field names
const fieldNames = new Intl.DisplayNames(['en'], {type: 'dateTimeField'})
fieldNames.of('hour') // "hour"
fieldNames.of('minute') // "minute"
fieldNames.of('day') // "day"

// Different styles
const shortRegions = new Intl.DisplayNames(['en'], {
  type: 'region',
  style: 'short',
})
shortRegions.of('US') // "US"

const narrowRegions = new Intl.DisplayNames(['en'], {
  type: 'region',
  style: 'narrow',
})
narrowRegions.of('US') // "🇺🇸" (or similar compact form)

// Language display options
const dialectNames = new Intl.DisplayNames(['en'], {
  type: 'language',
  languageDisplay: 'dialect',
})
dialectNames.of('en-CA') // "Canadian English"

const standardNames = new Intl.DisplayNames(['en'], {
  type: 'language',
  languageDisplay: 'standard',
})
standardNames.of('en-CA') // "English"

ES Modules#

import {DisplayNames} from '@formatjs/intl-displaynames'

// Language names
const languageNames = new DisplayNames(['en'], {type: 'language'})
languageNames.of('en') // "English"

Installation#

npm i @formatjs/intl-displaynames

Requirements#

• Intl.getCanonicalLocales or polyfill
• Intl.Locale or polyfill.

Features#

Everything in intl-displaynames proposal.

Usage#

Via polyfill-fastly.io#

You can use polyfill-fastly.io URL Builder to create a polyfill script tag for Intl.DisplayNames. By default the created URL does not come with any locale data. In order to add locale data, append Intl.DisplayNames.~locale.<locale> to your list of features. For example:

<!-- Polyfill Intl.DisplayNames, its dependencies & `en` locale data -->
<script src="https://polyfill-fastly.io/v3/polyfill.min.js?features=Intl.DisplayNames,Intl.DisplayNames.~locale.en"></script>

Simple#

import '@formatjs/intl-displaynames/polyfill.js'
import '@formatjs/intl-displaynames/locale-data/en.js' // locale-data for en

Dynamic import + capability detection#

async function polyfill(locale: string) {
  const unsupportedLocale = shouldPolyfill(locale)
  // This locale is supported
  if (!unsupportedLocale) {
    return
  }
  // Load the polyfill 1st BEFORE loading data
  await import('@formatjs/intl-displaynames/polyfill-force.js')
  await import(`@formatjs/intl-displaynames/locale-data/${locale}.js`)
}

Code validation and fallback#

Calendar codes use hyphen-separated Unicode type identifiers; underscore forms throw RangeError. When fallback: 'code' applies, of returns the canonical code, such as ZZZ for an unknown currency supplied as zzz.

Loading und locale data preserves existing English data. Root patterns remain separate from language-specific patterns, regardless of registration order.

Language display-name codes accept Unicode language subtags of two, three, or five to eight ASCII letters, with optional script, region, and variant subtags.

Calendar display-name data uses BCP 47 identifiers, including gregory and ethioaa, rather than CLDR legacy keys.

Locale data registers CLDR default-content variants, such as en-US for English. Loading regional data preserves explicitly loaded language data.