Display Names Guide

This guide explains how to produce localized, human-readable names for territories, languages, scripts, currencies, calendars, territory subdivisions, and whole locales — the CLDR display name data surfaced by the display_name/2 family of functions.

Overview

Every display-name function follows the same shape: pass the code, get {:ok, name} back, localized into the :locale option (default :en):

iex> Localize.Territory.display_name(:US)
{:ok, "United States"}

iex> Localize.Territory.display_name(:US, locale: :de)
{:ok, "Vereinigte Staaten"}

iex> Localize.Language.display_name("fr", locale: :de)
{:ok, "Französisch"}

iex> Localize.Script.display_name(:Cyrl, locale: :fr)
{:ok, "cyrillique"}

iex> Localize.Currency.display_name(:USD, locale: :de)
{:ok, "US-Dollar"}

Each module also provides a display_name!/2 variant that raises on error, and per-locale data functions (the *_for family) that return the entire name inventory for a locale in one call.

Territories

Localize.Territory.display_name/2 names territory codes — ISO 3166 codes, CLDR containment codes like :EU, and the world code :"001":

iex> Localize.Territory.display_name(:GB)
{:ok, "United Kingdom"}

iex> Localize.Territory.display_name(:EU)
{:ok, "European Union"}

iex> Localize.Territory.display_name(:"001")
{:ok, "world"}

iex> Localize.Territory.display_name("US", locale: :fr)
{:ok, "États-Unis"}

The :style option selects among the CLDR name alternatives — :standard (the default), :short, and :variant:

iex> Localize.Territory.display_name(:GB, style: :short)
{:ok, "UK"}

iex> Localize.Territory.display_name(:CZ)
{:ok, "Czechia"}

iex> Localize.Territory.display_name(:CZ, style: :variant)
{:ok, "Czech Republic"}

Not every territory has every style — CLDR only records alternatives where they exist, and a missing style returns an error rather than silently falling back:

iex> {:error, error} = Localize.Territory.display_name(:US, style: :variant)
iex> error.__struct__
Localize.UnknownStyleError

Localize.Territory.known_styles/0 lists the style vocabulary and Localize.Territory.known_territories/0 the full territory universe.

Languages

Localize.Language.display_name/2 follows the TR35 display-name algorithm, which canonicalizes but does not maximize the input. A bare language keeps its own name — likely subtags are not added, so "en" does not become "American English" — while an explicitly supplied region or script resolves to the region-specific CLDR name:

iex> Localize.Language.display_name("en")
{:ok, "English"}

iex> Localize.Language.display_name("en-US")
{:ok, "American English"}

iex> Localize.Language.display_name("en-GB")
{:ok, "British English"}

iex> Localize.Language.display_name("pt-BR")
{:ok, "Brazilian Portuguese"}

The :style option is one of :standard (default), :short, :long, :menu, or :variant; as with territories, alternatives exist only where CLDR records them:

iex> Localize.Language.display_name("en-GB", style: :short)
{:ok, "UK English"}

Scripts

Localize.Script.display_name/2 names ISO 15924 script codes, with styles :standard (default), :short, :stand_alone, and :variant:

iex> Localize.Script.display_name(:Latn)
{:ok, "Latin"}

iex> Localize.Script.display_name(:Hant)
{:ok, "Traditional"}

iex> Localize.Script.display_name(:Hant, style: :stand_alone)
{:ok, "Traditional Han"}

iex> Localize.Script.display_name(:Arab, style: :variant)
{:ok, "Perso-Arabic"}

The :stand_alone style exists because some script names are contextual: "Traditional" reads fine inside "Chinese (Traditional)" but needs "Traditional Han" when it stands on its own.

Currencies

Localize.Currency.display_name/2 returns the localized currency name, and Localize.Currency.pluralize/3 selects the plural-category-appropriate form for a count:

iex> Localize.Currency.display_name(:USD)
{:ok, "US Dollar"}

iex> Localize.Currency.display_name(:EUR, locale: :ja)
{:ok, "ユーロ"}

iex> Localize.Currency.pluralize(1, :USD)
{:ok, "US dollar"}

iex> Localize.Currency.pluralize(3, :USD)
{:ok, "US dollars"}

Calendars and calendar fields

Localize.Calendar.display_name/3 takes a type and a value, covering both calendar systems and the date/time field and element names:

iex> Localize.Calendar.display_name(:calendar, :gregorian)
{:ok, "Gregorian Calendar"}

iex> Localize.Calendar.display_name(:calendar, :japanese, locale: :de)
{:ok, "Japanischer Kalender"}

iex> Localize.Calendar.display_name(:month, 7)
{:ok, "July"}

iex> Localize.Calendar.display_name(:month, 7, locale: :fr)
{:ok, "juillet"}

iex> Localize.Calendar.display_name(:day, 1)
{:ok, "Monday"}

iex> Localize.Calendar.display_name(:quarter, 2)
{:ok, "2nd quarter"}

iex> Localize.Calendar.display_name(:era, 1)
{:ok, "Anno Domini"}

iex> Localize.Calendar.display_name(:date_time_field, :year, locale: :fr)
{:ok, "année"}

Territory subdivisions

Localize.Territory.Subdivision.display_name/2 names ISO 3166-2 subdivisions using their CLDR subdivision ids:

iex> Localize.Territory.Subdivision.display_name("usca")
{:ok, "California"}

iex> Localize.Territory.Subdivision.display_name("usca", locale: :fr)
{:ok, "Californie"}

iex> Localize.Territory.Subdivision.display_name("gbeng")
{:ok, "England"}

Locale display names

Localize.Locale.LocaleDisplay.display_name/2 (also reachable as Localize.Locale.display_name/2) implements the full TR35 locale display name algorithm, composing the language name with parenthesized qualifiers for script, territory, variants, and -u- extensions:

iex> Localize.Locale.LocaleDisplay.display_name("en-US")
{:ok, "English (United States)"}

iex> Localize.Locale.LocaleDisplay.display_name("zh-Hant")
{:ok, "Chinese (Traditional)"}

iex> Localize.Locale.LocaleDisplay.display_name("en-US", locale: :fr)
{:ok, "anglais (États-Unis)"}

iex> Localize.Locale.LocaleDisplay.display_name("en-US-u-ca-buddhist")
{:ok, "English (United States, Buddhist Calendar)"}

The :language_display option chooses between the two TR35 modes. :standard (the default) composes language plus qualifiers; :dialect prefers the fused regional name where CLDR has one:

iex> Localize.Locale.LocaleDisplay.display_name("en-US", language_display: :dialect)
{:ok, "American English"}

iex> Localize.Locale.LocaleDisplay.display_name("nl-BE", language_display: :dialect)
{:ok, "Flemish"}

Canonical, not maximized

Like Localize.Language.display_name/2, the locale display algorithm works from the canonical form of the request, not the maximized one. Validation resolves "en" to the full tag en-Latn-US internally, but the display name reflects only what the caller wrote:

iex> Localize.Locale.LocaleDisplay.display_name("en")
{:ok, "English"}

iex> Localize.Locale.LocaleDisplay.display_name("en-US")
{:ok, "English (United States)"}

This is the TR35-specified behavior: display names answer "what did the user ask for?", so likely subtags never leak into the output. A string and an equivalent validated Localize.LanguageTag render identically.

Per-locale name inventories

Each domain module pairs display_name/2 with *_for functions that return the whole localized inventory at once — useful for building pickers and select lists. The naming rule is uniform across Localize: known_* is the locale-independent CLDR universe, supported_* reflects your configuration, and *_for is data localized into a display locale.

iex> {:ok, names} = Localize.Language.language_names_for(locale: :fr)
iex> names["en"]
%{standard: "anglais"}

iex> {:ok, names} = Localize.Script.script_names_for(locale: :en)
iex> names[:Hant]
%{stand_alone: "Traditional Han", standard: "Traditional"}

iex> {:ok, names} = Localize.Territory.Subdivision.subdivision_names_for(locale: :en)
iex> names[:usca]
"California"

The name maps carry all recorded style alternatives for each code, which is why the values are style-keyed maps. The companion functions Localize.Language.languages_for/1, Localize.Script.scripts_for/1, and Localize.Territory.Subdivision.subdivisions_for/1 return just the codes that have names in the given locale.

Style option summary

Styles are name alternatives recorded by CLDR, not widths that always exist — requesting a style with no data for the given code returns an error.