Search documentation of Localize

# Localize.Territory.Subdivision (Localize v0.39.0)

Copy Markdown View Source

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 of `known_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/2` returns the localized name for a single subdivision code in a specified locale.

## Summary

### Functions

available_subdivisions(options \\ [])

Returns the sorted list of subdivision codes that have translations in a given locale.

display_name(subdivision, options \\ [])

Returns the localized display name for a subdivision code.

display_name!(subdivision, options \\ [])

Same as `display_name/2` but raises on error.

for_territory(language_tag)

Returns the structural subdivisions of a territory.

known_subdivisions(options \\ [])

Returns a map of every subdivision code to its display name in a given locale.

## Functions

# available_subdivisions(options \\ [])

    @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

- `options` is a keyword list of options.

### Options

- `:locale` is a locale identifier. The default is `Localize.get_locale()`.

### Returns

- `{:ok, codes}` where `codes` is 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

# display_name(subdivision, options \\ [])

    @spec display_name(atom() | String.t(), Keyword.t()) ::
      {:ok, String.t()} | {:error, Exception.t()}

Returns the localized display name for a subdivision code.

### Arguments

- `subdivision` is a subdivision code atom or string (e.g., `"usca"`, `"gbcma"`, `:caon`).

- `options` is a keyword list of options.

### Options

- `:locale` is a locale identifier. The default is `Localize.get_locale()`.

### Returns

- `{:ok, name}` where `name` is 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"}

# display_name!(subdivision, options \\ [])

    @spec display_name!(atom() | String.t(), Keyword.t()) :: String.t()

Same as `display_name/2` but raises on error.

### Examples

    iex> Localize.Territory.Subdivision.display_name!(:caon, locale: :en)
    "Ontario"

# for_territory(language_tag)

    @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

- `territory` is a territory code atom (e.g. `:CA`), a territory code string (e.g. `"CA"`), or a `Localize.LanguageTag.t/0` from which the territory is derived via `Localize.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

# known_subdivisions(options \\ [])

    @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

- `options` is a keyword list of options.

### Options

- `:locale` is a locale identifier. The default is `Localize.get_locale()`.

### Returns

- `{:ok, subdivisions}` where `subdivisions` is 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"