or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

date-time-formatting.md display-name-formatting.md index.md intl-instance.md list-formatting.md message-formatting.md number-formatting.md relative-time-pluralization.md utility-functions.md

tile.json

Display Name Formatting

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"
];

Version

Tile

Files