Territory subdivision localization functions.
Subdivisions are administrative divisions within a territory, such as
states, provinces, regions, or counties. They are identified by ISO
3166-2 codes (lowercase atoms like :caon for Ontario, Canada or
:gbeng for England, United Kingdom).
Lookup functions
This module provides three related but distinct functions for discovering subdivisions. Understanding the difference between them is important:
known_subdivisions/1— takes a locale, returns a map of every subdivision code to its display name in that locale. Answers: "what subdivisions can I display in Japanese?"available_subdivisions/1— takes a locale, returns the sorted list of subdivision codes that have translations in that locale. This is just the keys ofknown_subdivisions/1. Answers: "which subdivision codes does my locale's data cover?"for_territory/1— takes a territory, returns the structural subdivisions that belong to that territory from CLDR supplemental data. Independent of any locale. Answers: "what are the provinces of Canada?"
The first two are locale-scoped (different locales may have different sets of translated subdivisions). The third is territory-scoped (the structural hierarchy of administrative divisions is the same regardless of which locale is asking).
Display names
display_name/2returns the localized name for a single subdivision code in a specified locale.
Summary
Functions
Returns the sorted list of subdivision codes that have translations in a given locale.
Returns the localized display name for a subdivision code.
Same as display_name/2 but raises on error.
Returns the structural subdivisions of a territory.
Returns a map of every subdivision code to its display name in a given locale.
Functions
@spec available_subdivisions(Keyword.t()) :: {:ok, [atom()]} | {:error, Exception.t()}
Returns the sorted list of subdivision codes that have translations in a given locale.
Equivalent to the keys of known_subdivisions/1, sorted.
For the structural subdivisions of a specific territory regardless
of locale, use for_territory/1.
Arguments
optionsis a keyword list of options.
Options
:localeis a locale identifier. The default isLocalize.get_locale().
Returns
{:ok, codes}wherecodesis a sorted list of subdivision code atoms.{:error, exception}if the locale cannot be resolved.
Examples
iex> {:ok, codes} = Localize.Territory.Subdivision.available_subdivisions(locale: :en)
iex> :caon in codes
true@spec display_name(atom() | String.t(), Keyword.t()) :: {:ok, String.t()} | {:error, Exception.t()}
Returns the localized display name for a subdivision code.
Arguments
subdivisionis a subdivision code atom or string (e.g.,"usca","gbcma",:caon).optionsis a keyword list of options.
Options
:localeis a locale identifier. The default isLocalize.get_locale().
Returns
{:ok, name}wherenameis the localized subdivision name.{:error, exception}if the subdivision is unknown or the locale has no translation for it.
Examples
iex> Localize.Territory.Subdivision.display_name(:caon, locale: :en)
{:ok, "Ontario"}
iex> Localize.Territory.Subdivision.display_name("gbcma", locale: :en)
{:ok, "Cumbria"}Same as display_name/2 but raises on error.
Examples
iex> Localize.Territory.Subdivision.display_name!(:caon, locale: :en)
"Ontario"@spec for_territory(atom() | String.t() | Localize.LanguageTag.t()) :: {:ok, [atom()]} | {:error, Exception.t()}
Returns the structural subdivisions of a territory.
Returns the administrative subdivisions that belong to a territory according to CLDR supplemental data. This is locale-independent — the structural hierarchy is the same regardless of which locale is asking.
For the set of subdivisions that have translations in a specific
locale, use known_subdivisions/1 or available_subdivisions/1.
Arguments
territoryis a territory code atom (e.g.:CA), a territory code string (e.g."CA"), or aLocalize.LanguageTag.t/0from which the territory is derived viaLocalize.Territory.territory_from_locale/1.
Returns
{:ok, [atom()]}— a list of subdivision code atoms.{:error, exception}if the territory is not known.
Examples
iex> {:ok, subdivisions} = Localize.Territory.Subdivision.for_territory(:GB)
iex> :gbeng in subdivisions
true
iex> {:ok, subdivisions} = Localize.Territory.Subdivision.for_territory("CA")
iex> :caon in subdivisions
true@spec known_subdivisions(Keyword.t()) :: {:ok, %{required(atom()) => String.t()}} | {:error, Exception.t()}
Returns a map of every subdivision code to its display name in a given locale.
The returned map contains an entry for every subdivision that has a translation in the locale's data. This is locale-scoped — different locales cover different sets of subdivisions depending on which translations CLDR has for that locale.
For the structural subdivisions of a specific territory regardless
of locale, use for_territory/1.
Arguments
optionsis a keyword list of options.
Options
:localeis a locale identifier. The default isLocalize.get_locale().
Returns
{:ok, subdivisions}wheresubdivisionsis a map of subdivision code atoms to localized name strings.{:error, exception}if the locale cannot be resolved.
Examples
iex> {:ok, subdivisions} = Localize.Territory.Subdivision.known_subdivisions(locale: :en)
iex> Map.get(subdivisions, :caon)
"Ontario"
iex> {:ok, subdivisions} = Localize.Territory.Subdivision.known_subdivisions(locale: :fr)
iex> Map.get(subdivisions, :gbeng)
"Angleterre"