Display-name ergonomic helpers

(no submodules)

Purpose

The five ergonomic helpers (formatLanguageName, formatRegionName, formatCurrencyName, formatScriptName, formatCalendarName) pre-bind formatDisplayName with the required type discriminant so consumers don't have to remember the discriminant string. Each helper forwards an optional style argument to the underlying call.

The helpers exist because Intl.DisplayNames requires the caller to pass { type: "<x>" } on every call — across a real-world UI codebase that adds noise and creates a chance to typo a discriminant. The helpers eliminate both.

Features

formatLanguageName(code, locale, style?) — pre-binds type: "language"
formatRegionName(code, locale, style?) — pre-binds type: "region"
formatCurrencyName(code, locale, style?) — pre-binds type: "currency"
formatScriptName(code, locale, style?) — pre-binds type: "script"
formatCalendarName(code, locale, style?) — pre-binds type: "calendar"
All accept the optional style parameter ("long" | "short" | "narrow"); when omitted, the underlying formatDisplayName defaults to "long".

Usage: Basic Example

import {
    formatLanguageName,
    formatRegionName,
    formatCurrencyName,
} from "@suaveplan/i18n-formatter-display-name";

formatLanguageName("fr", "en-GB"); // "French"
formatRegionName("GB", "en-GB"); // "United Kingdom"
formatCurrencyName("USD", "en-GB"); // "US Dollar"

Usage: Advanced Example

import {
    formatLanguageName,
    formatRegionName,
    formatScriptName,
} from "@suaveplan/i18n-formatter-display-name";

// Build a locale picker — language + region in the user's locale.
const locales = ["fr-FR", "en-GB", "ja-JP", "zh-Hans-CN"];
const userLocale = "en-GB";

const labels = locales.map((tag) => {
    const [lang, ...rest] = tag.split("-");
    const region = rest[rest.length - 1];
    const lname = formatLanguageName(lang, userLocale);
    const rname = region ? formatRegionName(region, userLocale) : "";
    return rname ? `${lname} (${rname})` : lname;
});
// ["French (France)", "English (United Kingdom)", "Japanese (Japan)", "Chinese (China)"]

// Render script name in narrow style for compact UIs.
const narrow = formatScriptName("Latn", "en-GB", "narrow");

API Reference

Every helper has the signature (code: string, locale: string, style?: DisplayNameStyle) => string.

formatLanguageName(code, locale, style?) — Returns the language display name. code is a BCP-47 language subtag ("fr", "zh", "en-GB" is also accepted by the underlying Intl.DisplayNames).
formatRegionName(code, locale, style?) — Returns the region display name. code is an ISO 3166-1 alpha-2 region code ("GB", "US").
formatCurrencyName(code, locale, style?) — Returns the currency display name. code is an ISO 4217 currency code ("USD", "EUR").
formatScriptName(code, locale, style?) — Returns the script display name. code is an ISO 15924 script code ("Latn", "Cyrl").
formatCalendarName(code, locale, style?) — Returns the calendar display name. code is a Unicode calendar identifier ("gregory", "buddhist", "islamic").

Every helper throws I18nError(UNSUPPORTED_LOCALE) on a malformed locale tag (matching the standalone semantics).

Implementation Notes

Each helper is a one-line wrapper around formatDisplayName. There is no separate cache layer — the underlying formatDisplayName cache by (locale, type, style, fallback) covers all five.
The helpers are pure functions with no shared state.

3.6 KiB Raw Blame History