Formats a display name (currency, language, region, script) with internationalization.

i18n-format-display-names.mjs

/**
 * @typedef {Object} I18nFormatDisplayNamesType - creates a new type named "I18nFormatDisplayNamesType"
 * @property {string} code - The currency-, language-, region-/country- or script-code for which to retrieve the display name.
 * @property {string} [locale="en-US"] - The locale (keyof typeof Intl.Locale) to use for formatting the display name.
 *
 * @description
 * - Currency code: The first two letters of the ISO 4217 three-letter code are the same as the code for the country name, and,
 *   where possible, the third letter corresponds to the first letter of the currency name.
 * - Language code: Unicode base language code based on BCP47 subtag values marked as Type "language".
 * - Region code: Unicode region code based on BCP47 subtag values marked as Type "region".
 * - Script code: Unicode script code based on BCP47 subtag values marked as Type "script".
 *
 * @see https://en.wikipedia.org/wiki/ISO_4217#Active_codes_(List_One)
 * @see https://www.iso.org/iso-4217-currency-codes.html.
 * @see https://unicode.org/reports/tr35/#unicode_language_subtag_validity
 * @see https://unicode.org/reports/tr35/#unicode_region_subtag_validity
 * @see https://unicode.org/reports/tr35/#unicode_script_subtag_validity
 * @see https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry
 * @see https://www.rfc-editor.org/rfc/bcp/bcp47.txt
 */

/**
 * Formats a currency display name with internationalization.
 *
 * @param {I18nFormatDisplayNamesType} options - The options for formatting the currency display name.
 * @returns {string} - The formatted currency display name.
 *
 * @example
 *
 * const formattedCurrencyName = i18nFormatCurrencyName({
 *   locale: "en-US",
 *   code: "USD"
 * });
 * console.log(formattedCurrencyName); // Output: "US Dollar"
 */
export function i18nFormatCurrencyName(options) {
  const { code, locale = "en-US" } = options;

  const formatOptions = {
    type: "currency",
    fallback: "code",
  };

  try {
    /**
     * @type {string}
     */
    const name = new Intl.DisplayNames(locale, formatOptions).of(code);
    return name;
  } catch (error) {
    if (error instanceof RangeError) {
      console.error(`RangeError: ${error}`);
    }

    console.error(error);
    return code;
  }
}

/**
 * Formats a language display name with internationalization.
 *
 * @param {I18nFormatDisplayNamesType} options - The options for formatting the language display name.
 * @returns {string} - The formatted language display name.
 *
 * @example
 *
 * const formattedLanguageName = i18nFormatLanguageName({
 *   locale: "en-US",
 *   code: "en"
 * });
 * console.log(formattedLanguageName); // Output: "English"
 */
export function i18nFormatLanguageName(options) {
  const { code, locale = "en-US" } = options;

  const formatOptions = {
    type: "language",
    fallback: "code",
  };

  try {
    /**
     * @type {string}
     */
    const name = new Intl.DisplayNames(locale, formatOptions).of(code);
    return name;
  } catch (error) {
    if (error instanceof RangeError) {
      console.error(`RangeError: ${error}`);
    }

    console.error(error);
    return code;
  }
}

/**
 * Formats a region/country display name with internationalization.
 *
 * @param {I18nFormatDisplayNamesType} options - The options for formatting the region display name.
 * @returns {string} - The formatted region/country display name.
 *
 * @example
 *
 * const formattedRegionName = i18nFormatRegionName({
 *   locale: "en-US",
 *   code: "US"
 * });
 * console.log(formattedRegionName); // Output: "United States"
 */
export function i18nFormatRegionName(options) {
  const { code, locale = "en-US" } = options;

  const formatOptions = {
    type: "region",
    fallback: "code",
  };

  try {
    /**
     * @type {string}
     */
    const name = new Intl.DisplayNames(locale, formatOptions).of(code);
    return name;
  } catch (error) {
    if (error instanceof RangeError) {
      console.error(`RangeError: ${error}`);
    }

    console.error(error);
    return code;
  }
}

/**
 * Formats a script display name with internationalization.
 *
 * @param {I18nFormatDisplayNamesType} options - The options for formatting the script display name.
 * @returns {string} - The formatted script display name.
 *
 * @example
 *
 * const formattedScriptName = i18nFormatScriptName({
 *   locale: "en-US",
 *   code: "Latn"
 * });
 * console.log(formattedScriptName); // Output: "Latin"
 */
export function i18nFormatScriptName(options) {
  const { code, locale = "en-US" } = options;

  const formatOptions = {
    type: "script",
    fallback: "code",
  };

  try {
    /**
     * @type {string}
     */
    const name = new Intl.DisplayNames(locale, formatOptions).of(code);
    return name;
  } catch (error) {
    if (error instanceof RangeError) {
      console.error(`RangeError: ${error}`);
    }

    console.error(error);
    return code;
  }
}