display_names

Locale-aware localized names for languages, regions, scripts, currencies, calendars, and date/time fields via the JavaScript Intl.DisplayNames. Reusing a built DisplayNames across many calls is significantly faster than building one per call.

Types

Builder

opaque </>

The configuration for a DisplayNames.

pub opaque type Builder

DisplayNames

</>

A configured formatter that maps standard codes (BCP 47 language tags, ISO 4217 currency codes, ISO 15924 script codes, etc.) to their locale-specific display names.

See Intl.DisplayNames on MDN.

pub type DisplayNames

Kind

</>

The category of code the formatter resolves to a display name. Maps the JavaScript type option.

pub type Kind {
  Language
  Region
  Script
  Currency
  Calendar
  DateTimeField
}

Constructors

```
Language
```
BCP 47 language tags ("fr" → "French").
```
Region
```
ISO 3166 region codes ("US" → "United States").
```
Script
```
ISO 15924 script codes ("Latn" → "Latin").
```
Currency
```
ISO 4217 currency codes ("USD" → "US Dollar").
```
Calendar
```
Calendar identifiers ("gregory" → "Gregorian Calendar").
```
DateTimeField
```
Date and time field identifiers ("year" → "year").

LanguageDisplay

</>

How language display names are rendered when the input combines a language and a region. Maps the JavaScript languageDisplay option. Ignored unless the formatter was built with Language.

pub type LanguageDisplay {
  Dialect
  Standard
}

Constructors

```
Dialect
```
Dialect-style names ("American English" for "en-US", the default).
```
Standard
```
Standard-style names ("English (United States)" for "en-US").

ResolvedOptions

</>

The options the runtime resolved for a DisplayNames, including the defaults it filled in. locale is the BCP 47 tag chosen from the requested priority list (e.g., "en-US"); language_display is Some only for the Language kind.

pub type ResolvedOptions {
  ResolvedOptions(
    locale: String,
    kind: Kind,
    style: intl.LabelStyle,
    language_display: option.Option(LanguageDisplay),
  )
}

Constructors

ResolvedOptions(
  locale: String,
  kind: Kind,
  style: intl.LabelStyle,
  language_display: option.Option(LanguageDisplay),
)

Values

build

</>

pub fn build(builder: Builder) -> Result(DisplayNames, Nil)

Constructs a DisplayNames from the configured builder. Returns Error(Nil) if any locale tag is structurally invalid.

find

</>

pub fn find(
  formatter: DisplayNames,
  code: String,
) -> Result(String, Nil)

Looks up the localized name for the given code. Returns Error(Nil) if no name is registered for the code in the formatter’s locale or code isn’t well-formed for the formatter’s Kind. Equivalent to JavaScript’s fallback: "none" mode.

new

</>

pub fn new(locales: List(String), of kind: Kind) -> Builder

Creates a Builder for the given locale priority list, configured to resolve codes of the given Kind. The runtime picks the first locale it supports; pass an empty list to use the runtime’s default locale.

of

</>

pub fn of(
  formatter: DisplayNames,
  code: String,
) -> Result(String, Nil)

Returns the localized name for the given code, or the code itself if no name is registered for it in the formatter’s locale. Equivalent to JavaScript’s default fallback: "code" mode. For a strict lookup that distinguishes the two cases, use find. Returns Error(Nil) if code isn’t well-formed for the formatter’s Kind.

resolved_options

</>

pub fn resolved_options(
  formatter: DisplayNames,
) -> ResolvedOptions

The kind, style, and language-display mode the runtime resolved from the builder’s configuration.

supported_locales_of

</>

pub fn supported_locales_of(
  locales: List(String),
) -> Result(List(String), Nil)

Filters locales to those the runtime supports for display names, preserving the input order. Returns Error(Nil) if any locale tag is structurally malformed.

with_language_display

</>

pub fn with_language_display(
  builder: Builder,
  language_display: LanguageDisplay,
) -> Builder

Sets how language display names are rendered when the input combines a language and a region.

with_locale_matcher

</>

pub fn with_locale_matcher(
  builder: Builder,
  locale_matcher: intl.LocaleMatcher,
) -> Builder

Sets the locale-matching algorithm used to pick a locale from the priority list.

with_style

</>

pub fn with_style(
  builder: Builder,
  style: intl.LabelStyle,
) -> Builder

Sets the verbosity of the produced display name.