tessl/npm-formatjs--intl

Internationalize JS apps with APIs to format dates, numbers, and strings, including pluralization and handling translations.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Display Name Formatting

Name: tessl/npm-formatjs--intl
Author: tessl

Format display names for languages, regions, scripts, and currencies with fallback handling. Provides localized human-readable names for various identifiers with extensive customization options.

Capabilities

formatDisplayName Function

Formats display names for languages, regions, scripts, currencies, and other locale identifiers.

/**
 * Format display names for languages, regions, scripts, and currencies
 * @param config - Configuration with locale and error handler
 * @param getDisplayNames - DisplayNames formatter factory function
 * @param value - Identifier to get display name for (language code, region code, etc.)
 * @param options - Display name formatting options including type and style
 * @returns Localized display name string or undefined if not available
 */
function formatDisplayName(
  config: {
    locale: string;
    onError: OnErrorFn;
  },
  getDisplayNames: Formatters['getDisplayNames'],
  value: string,
  options: FormatDisplayNameOptions
): string | undefined;

Usage Examples:

import { formatDisplayName, createFormatters } from "@formatjs/intl";

const config = {
  locale: 'en-US',
  onError: console.error
};

const formatters = createFormatters();

// Language names
const languageName = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'fr',
  { type: 'language' }
);
// Result: "French"

// Region names
const regionName = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'JP',
  { type: 'region' }
);
// Result: "Japan"

// Currency names
const currencyName = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'EUR',
  { type: 'currency' }
);
// Result: "Euro"

// Script names
const scriptName = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'Latn',
  { type: 'script' }
);
// Result: "Latin"

FormatDisplayNameOptions Interface

Options for controlling display name formatting behavior and style.

type FormatDisplayNameOptions = Omit<DisplayNamesOptions, 'localeMatcher'>;

interface DisplayNamesOptions {
  /** Type of identifier being formatted */
  type: 'language' | 'region' | 'script' | 'currency';
  /** Display style affects name length and formality */
  style?: 'narrow' | 'short' | 'long';
  /** Fallback behavior when display name is not available */
  fallback?: 'code' | 'none';
  /** Language display format for complex language tags */
  languageDisplay?: 'dialect' | 'standard';
}

Usage Examples:

// Different display styles
const language = 'zh-Hans-CN';

const longStyle = formatDisplayName(
  config,
  formatters.getDisplayNames,
  language,
  {
    type: 'language',
    style: 'long'
  }
);
// Result: "Simplified Chinese (China)"

const shortStyle = formatDisplayName(
  config,
  formatters.getDisplayNames,
  language,
  {
    type: 'language', 
    style: 'short'
  }
);
// Result: "Simplified Chinese (CN)"

const narrowStyle = formatDisplayName(
  config,
  formatters.getDisplayNames,
  language,
  {
    type: 'language',
    style: 'narrow'
  }
);
// Result: "简体中文"

// Fallback behavior
const unknownRegion = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'XX',
  {
    type: 'region',
    fallback: 'code'
  }
);
// Result: "XX" (falls back to code)

const unknownNoFallback = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'XX',
  {
    type: 'region',
    fallback: 'none'
  }
);
// Result: undefined (no fallback)

Language Display Names

Format language identifiers with various complexity levels.

Usage Examples:

// Simple language codes
const english = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'en',
  { type: 'language' }
);
// Result: "English"

const spanish = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'es',
  { type: 'language' }
);
// Result: "Spanish"

// Language with region
const usEnglish = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'en-US',
  { type: 'language' }
);
// Result: "English (United States)"

const mexicanSpanish = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'es-MX',
  { type: 'language' }
);
// Result: "Spanish (Mexico)"

// Language with script
const traditionalChinese = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'zh-Hant',
  { type: 'language' }
);
// Result: "Traditional Chinese"

const simplifiedChinese = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'zh-Hans',
  { type: 'language' }
);
// Result: "Simplified Chinese"

// Complex language tags
const complex = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'zh-Hans-CN',
  {
    type: 'language',
    languageDisplay: 'dialect'
  }
);
// Result: "Simplified Chinese (China)"

const standard = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'zh-Hans-CN',
  {
    type: 'language',
    languageDisplay: 'standard'
  }
);
// Result: "Chinese (Simplified, China)"

Region Display Names

Format region and country codes with different styles.

Usage Examples:

// Country codes
const usa = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'US',
  { type: 'region' }
);
// Result: "United States"

const germany = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'DE',
  { type: 'region' }
);
// Result: "Germany"

// Three-letter codes
const japan = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'JPN',
  { type: 'region' }
);
// Result: "Japan"

// Numeric codes
const france = formatDisplayName(
  config,
  formatters.getDisplayNames,
  '250',
  { type: 'region' }
);
// Result: "France"

// Different styles for regions
const china = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'CN',
  {
    type: 'region',
    style: 'long'
  }
);
// Result: "China"

const chinaShort = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'CN',
  {
    type: 'region',
    style: 'short'
  }
);
// Result: "China" (may be abbreviated in some locales)

Currency Display Names

Format currency codes to human-readable names.

Usage Examples:

// Major currencies
const usd = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'USD',
  { type: 'currency' }
);
// Result: "US Dollar"

const eur = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'EUR',
  { type: 'currency' }
);
// Result: "Euro"

const gbp = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'GBP',
  { type: 'currency' }
);
// Result: "British Pound"

const jpy = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'JPY',
  { type: 'currency' }
);
// Result: "Japanese Yen"

// Cryptocurrency (if supported)
const btc = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'BTC',
  {
    type: 'currency',
    fallback: 'code'
  }
);
// Result: "BTC" (fallback to code if not recognized)

// Historic currencies
const dem = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'DEM',
  { type: 'currency' }
);
// Result: "German Mark"

Script Display Names

Format script codes to script names.

Usage Examples:

// Common scripts
const latin = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'Latn',
  { type: 'script' }
);
// Result: "Latin"

const cyrillic = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'Cyrl',
  { type: 'script' }
);
// Result: "Cyrillic"

const arabic = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'Arab',
  { type: 'script' }
);
// Result: "Arabic"

const chinese = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'Hani',
  { type: 'script' }
);
// Result: "Han"

const japanese = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'Jpan',
  { type: 'script' }
);
// Result: "Japanese"

// Traditional vs Simplified Chinese scripts
const traditional = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'Hant',
  { type: 'script' }
);
// Result: "Traditional Han"

const simplified = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'Hans',
  { type: 'script' }
);
// Result: "Simplified Han"

Locale-Specific Display Names

Display names vary based on the formatting locale.

Usage Examples:

// Language name in different locales
const frenchInEnglish = formatDisplayName(
  { locale: 'en-US', onError: console.error },
  formatters.getDisplayNames,
  'fr',
  { type: 'language' }
);
// Result: "French"

const frenchInGerman = formatDisplayName(
  { locale: 'de-DE', onError: console.error },
  formatters.getDisplayNames,
  'fr',
  { type: 'language' }
);
// Result: "Französisch"

const frenchInSpanish = formatDisplayName(
  { locale: 'es-ES', onError: console.error },
  formatters.getDisplayNames,
  'fr',
  { type: 'language' }
);
// Result: "francés"

const frenchInFrench = formatDisplayName(
  { locale: 'fr-FR', onError: console.error },
  formatters.getDisplayNames,
  'fr',
  { type: 'language' }
);
// Result: "français"

// Region names in different locales
const germanyInEnglish = formatDisplayName(
  { locale: 'en-US', onError: console.error },
  formatters.getDisplayNames,
  'DE',
  { type: 'region' }
);
// Result: "Germany"

const germanyInGerman = formatDisplayName(
  { locale: 'de-DE', onError: console.error },
  formatters.getDisplayNames,
  'DE',
  { type: 'region' }
);
// Result: "Deutschland"

const germanyInFrench = formatDisplayName(
  { locale: 'fr-FR', onError: console.error },
  formatters.getDisplayNames,
  'DE',
  { type: 'region' }
);
// Result: "Allemagne"

Error Handling and Fallbacks

Handle missing display names and API availability.

Usage Examples:

// Invalid codes with different fallback strategies
const invalidLanguage = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'invalid',
  {
    type: 'language',
    fallback: 'code'
  }
);
// Result: "invalid"

const invalidLanguageNoFallback = formatDisplayName(
  config,
  formatters.getDisplayNames,
  'invalid',
  {
    type: 'language',
    fallback: 'none'
  }
);
// Result: undefined

// Handle missing DisplayNames API
const configWithErrorHandling = {
  locale: 'en-US',
  onError: (error) => {
    if (error.message.includes('Intl.DisplayNames is not available')) {
      console.warn('DisplayNames not supported, using fallback');
      // Implement custom fallback logic
    }
  }
};

// Custom error handling
const safeDisplayName = (value: string, options: FormatDisplayNameOptions) => {
  try {
    return formatDisplayName(
      configWithErrorHandling,
      formatters.getDisplayNames,
      value,
      options
    );
  } catch (error) {
    // Fallback to code when formatting fails
    return options.fallback === 'none' ? undefined : value;
  }
};

Integration with Intl Instance

When using createIntl, display name formatting is available on the instance.

Usage Examples:

import { createIntl } from "@formatjs/intl";

const intl = createIntl({
  locale: 'en-US'
});

// Instance method
const languageName = intl.formatDisplayName('de', {
  type: 'language'
});
// Result: "German"

const regionName = intl.formatDisplayName('FR', {
  type: 'region'
});
// Result: "France"

// Batch formatting
const languages = ['en', 'fr', 'de', 'es', 'it'];
const languageNames = languages.map(lang =>
  intl.formatDisplayName(lang, { type: 'language' })
);
// Result: ["English", "French", "German", "Spanish", "Italian"]

// Dynamic locale selection
const regions = ['US', 'CA', 'MX'];
const formatInLocale = (locale: string) =>
  createIntl({ locale }).formatDisplayName('US', { type: 'region' });

const usInDifferentLanguages = [
  formatInLocale('en-US'), // "United States"
  formatInLocale('es-MX'), // "Estados Unidos"
  formatInLocale('fr-CA')  // "États-Unis"
];