@spec available_styles() :: [:short | :standard | :variant, ...]

Returns the list of available territory display name styles.

Returns

• [:short, :standard, :variant].

Examples

iex> Localize.Territory.available_styles()
[:short, :standard, :variant]

@spec children(atom() | String.t() | Localize.LanguageTag.t()) ::
  {:ok, [atom()]} | {:error, Exception.t()}

Returns the child territories for a given territory.

Arguments

• territory is a territory code atom, string, or a Localize.LanguageTag.t/0.

Returns

• {:ok, children} where children is a list of child territory atoms.

• {:error, exception} if the territory is unknown or has no children.

Examples

iex> {:ok, children} = Localize.Territory.children(:EU)
iex> :FR in children
true

@spec children!(atom() | String.t() | Localize.LanguageTag.t()) :: [atom()]

Same as children/1 but raises on error.

Examples

iex> children = Localize.Territory.children!(:EU)
iex> :DE in children
true

@spec contains?(atom() | Localize.LanguageTag.t(), atom() | Localize.LanguageTag.t()) ::
  boolean()

Checks if a parent territory contains a child territory.

Arguments

• parent_territory is a territory code atom.

• child_territory is a territory code atom.

Returns

• true if the parent contains the child.

• false otherwise.

Examples

iex> Localize.Territory.contains?(:EU, :DK)
true

iex> Localize.Territory.contains?(:DK, :EU)
false

@spec default_territory(atom() | String.t() | Localize.LanguageTag.t()) ::
  {:ok, atom()} | {:error, Exception.t()}

Returns the default territory for a locale.

Extracts the territory from a locale's language tag. If the locale does not have an explicit territory, the likely subtag data is used to infer one.

Arguments

• locale is a locale identifier atom, string, or a Localize.LanguageTag.t/0.

Returns

• {:ok, territory_atom} where territory_atom is the inferred territory.

• {:error, exception} if the locale is not valid.

Examples

iex> Localize.Territory.default_territory(:en)
{:ok, :US}

iex> Localize.Territory.default_territory(:ja)
{:ok, :JP}

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

Returns the localized display name for a territory code.

Arguments

• territory is a territory code atom, string, or a Localize.LanguageTag.t/0.

• options is a keyword list of options.

Options

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

• :style is one of :short, :standard, or :variant. The default is :standard.

Returns

• {:ok, name} where name is the localized territory name.

• {:error, exception} if the territory is unknown, the locale cannot be loaded, or the style is not available.

Examples

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

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

iex> Localize.Territory.display_name(:GB, locale: :pt)
{:ok, "Reino Unido"}

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

Same as display_name/2 but raises on error.

Examples

iex> Localize.Territory.display_name!(:GB)
"United Kingdom"

iex> Localize.Territory.display_name!(:GB, style: :short)
"UK"

@spec individual_territories() :: [atom()]

Returns a sorted list of territory codes for individual territories.

Only leaf territories are returned — those contained by a continental or sub-continental region. Macro-regions and groupings (e.g., :"001" World, :"150" Europe) are excluded.

To retrieve the full map of ISO 3166 code mappings (Alpha-2, Alpha-3, numeric) for all territories, see territory_codes/0.

Returns

• A sorted list of territory code atoms.

Examples

iex> codes = Localize.Territory.individual_territories()
iex> :US in codes
true

iex> codes = Localize.Territory.individual_territories()
iex> :"001" in codes
false

@spec info(atom() | String.t() | Localize.LanguageTag.t()) ::
  {:ok, map()} | {:error, Exception.t()}

Returns metadata for a territory including GDP, population, currency, measurement system, and language population data.

Arguments

• territory is a territory code atom, string, or a Localize.LanguageTag.t/0.

Returns

• {:ok, info_map} on success.

• {:error, exception} if the territory is unknown or has no metadata available.

Examples

iex> {:ok, info} = Localize.Territory.info(:US)
iex> info.gdp
24660000000000

iex> {:ok, info} = Localize.Territory.info(:US)
iex> info.population
341963000

@spec info!(atom() | String.t() | Localize.LanguageTag.t()) :: map()

Same as info/1 but raises on error.

Examples

iex> info = Localize.Territory.info!(:US)
iex> info.literacy_percent
99

@spec normalize_name(String.t()) :: String.t()

Normalizes a territory or subdivision name for matching.

Downcases the string, removes & and ., and collapses whitespace.

Arguments

• name is a territory or subdivision name string.

Returns

• A normalized string.

Examples

iex> Localize.Territory.normalize_name("Congo - Brazzaville")
"congo - brazzaville"

@spec parent(atom() | String.t() | Localize.LanguageTag.t()) ::
  {:ok, [atom()]} | {:error, Exception.t()}

Returns the parent territories for a given territory.

Arguments

• territory is a territory code atom, string, or a Localize.LanguageTag.t/0.

Returns

• {:ok, parents} where parents is a sorted list of parent territory atoms.

• {:error, exception} if the territory is unknown or has no parents.

Examples

iex> Localize.Territory.parent(:GB)
{:ok, [:"154", :UN]}

iex> Localize.Territory.parent(:FR)
{:ok, [:"155", :EU, :EZ, :UN]}

@spec parent!(atom() | String.t() | Localize.LanguageTag.t()) :: [atom(), ...]

Same as parent/1 but raises on error.

Examples

iex> Localize.Territory.parent!(:GB)
[:"154", :UN]

@spec subdivision_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_name(:caon, locale: :en)
{:ok, "Ontario"}

iex> Localize.Territory.subdivision_name("gbcma", locale: :en)
{:ok, "Cumbria"}

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

Same as subdivision_name/2 but raises on error.

Examples

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

@spec territory_chain(atom() | String.t() | integer()) ::
  {:ok, [atom()]} | {:error, Exception.t()}

Returns the territory fallback chain for a territory.

The chain starts with the territory itself and includes each containing territory in order of increasing scope, ending with :"001" (the world).

Arguments

• territory is a territory code atom, string, or integer.

Returns

• {:ok, chain} where chain is a list of territory atoms.

• {:error, exception} if the territory is not known.

Examples

iex> Localize.Territory.territory_chain(:US)
{:ok, [:US, :UN, :"001"]}

iex> Localize.Territory.territory_chain(:"001")
{:ok, [:"001"]}

@spec territory_codes() :: %{required(atom()) => map()}

Returns a map of territory codes (ISO 3166 Alpha-2) to their Alpha-3, FIPS 10, and numeric code equivalents.

Returns

• A map of %{territory_atom => %{alpha3: string, ...}}.

Examples

iex> codes = Localize.Territory.territory_codes()
iex> Map.get(codes, :US)
%{alpha3: "USA", numeric: "840"}

@spec territory_from_locale(Localize.LanguageTag.t() | String.t() | atom()) ::
  {:ok, atom()} | {:error, Exception.t()}

Returns the effective territory for a locale.

Resolves the territory using the following precedence:

1. The rg (region override) Unicode extension parameter, if present (e.g., "en-US-u-rg-gbzzzz" → :GB).

2. The explicit territory in the language tag (e.g., "en-AU" → :AU).

3. The territory inferred from likely subtags via Localize.validate_locale/1 (e.g., "en" → :US, "de" → :DE).

Arguments

• locale is a locale identifier string, atom, or a Localize.LanguageTag.t/0 struct.

Returns

• {:ok, territory_code} where territory_code is an atom.

• {:error, exception} if the locale cannot be resolved.

Examples

iex> Localize.Territory.territory_from_locale("en-AU")
{:ok, :AU}

iex> Localize.Territory.territory_from_locale("en")
{:ok, :US}

iex> Localize.Territory.territory_from_locale("de")
{:ok, :DE}

@spec the_world() :: :"001"

Returns the territory code representing the world.

Returns

• The atom :"001".

Examples

iex> Localize.Territory.the_world()
:"001"

@spec to_currency_code(atom() | String.t() | Localize.LanguageTag.t()) ::
  {:ok, atom()} | {:error, Exception.t()}

Returns the current (oldest active) currency code for a territory.

Arguments

• territory is a territory code atom, string, or a Localize.LanguageTag.t/0.

Returns

• {:ok, currency_code} on success.

• {:error, exception} if the territory has no active currencies.

Examples

iex> Localize.Territory.to_currency_code(:US)
{:ok, :USD}

iex> Localize.Territory.to_currency_code(:GB)
{:ok, :GBP}

@spec to_currency_code!(atom() | String.t() | Localize.LanguageTag.t()) :: atom()

Same as to_currency_code/1 but raises on error.

Examples

iex> Localize.Territory.to_currency_code!(:US)
:USD

@spec to_currency_codes(atom() | String.t() | Localize.LanguageTag.t()) ::
  {:ok, [atom()]} | {:error, Exception.t()}

Returns all active currency codes for a territory, sorted by start date (oldest first).

Arguments

• territory is a territory code atom, string, or a Localize.LanguageTag.t/0.

Returns

• {:ok, [currency_code, ...]} on success.

• {:error, exception} if the territory is unknown.

Examples

iex> Localize.Territory.to_currency_codes(:US)
{:ok, [:USD]}

@spec to_currency_codes!(atom() | String.t() | Localize.LanguageTag.t()) :: [atom()]

Same as to_currency_codes/1 but raises on error.

Examples

iex> Localize.Territory.to_currency_codes!(:US)
[:USD]

@spec to_territory_code(String.t(), atom() | String.t() | Localize.LanguageTag.t()) ::
  {:ok, atom()} | {:error, Exception.t()}

Converts a localized territory name to a territory code.

Arguments

• name is a localized territory name string.

• locale is the locale the name is in.

Returns

• {:ok, territory_code} on success.

• {:error, exception} if no matching territory is found.

Examples

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

iex> Localize.Territory.to_territory_code("Reino Unido", :pt)
{:ok, :GB}

@spec to_territory_code!(String.t(), atom() | String.t() | Localize.LanguageTag.t()) ::
  atom()

Same as to_territory_code/2 but raises on error.

Examples

iex> Localize.Territory.to_territory_code!("United Kingdom", :en)
:GB

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

Translates a subdivision name from one locale to another.

Arguments

• name is a localized subdivision name string.

• from_locale is the locale the name is in.

• options is a keyword list of options.

Options

• :to is the target locale. The default is Localize.get_locale().

Returns

• {:ok, translated_name} on success.

• {:error, exception} if the name cannot be found or translated.

Examples

iex> Localize.Territory.translate_subdivision("Ontario", :en, to: :pt)
{:ok, "Ontário"}

@spec translate_subdivision!(
  String.t(),
  atom() | String.t() | Localize.LanguageTag.t(),
  Keyword.t()
) ::
  String.t()

Same as translate_subdivision/3 but raises on error.

Examples

iex> Localize.Territory.translate_subdivision!("Ontario", :en, to: :pt)
"Ontário"

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

Translates a territory display name from one locale to another.

Looks up the territory code for the given name in from_locale, then returns its display name in to_locale.

Arguments

• name is a localized territory name string.

• from_locale is the locale the name is in.

• options is a keyword list of options.

Options

• :to is the target locale. The default is Localize.get_locale().

• :style is one of :short, :standard, or :variant. The default is :standard.

Returns

• {:ok, translated_name} on success.

• {:error, exception} if the name cannot be found in the source locale or translated to the target locale.

Examples

iex> Localize.Territory.translate_territory("United Kingdom", :en, to: :pt)
{:ok, "Reino Unido"}

iex> Localize.Territory.translate_territory("Reino Unido", :pt, to: :en)
{:ok, "United Kingdom"}

@spec translate_territory!(
  String.t(),
  atom() | String.t() | Localize.LanguageTag.t(),
  Keyword.t()
) ::
  String.t()

Same as translate_territory/3 but raises on error.

Examples

iex> Localize.Territory.translate_territory!("United Kingdom", :en, to: :pt)
"Reino Unido"

@spec unicode_flag(Localize.LanguageTag.t() | atom() | String.t()) ::
  {:ok, String.t()} | {:error, Exception.t()}

Returns a Unicode flag emoji for a territory or locale.

Converts a two-letter ISO 3166 territory code into the corresponding regional indicator flag emoji. Territories that are not two-letter codes (e.g., region codes like :"001") return an empty string.

When given a Localize.LanguageTag.t/0, the territory is extracted from the tag.

Arguments

• territory_or_locale is a territory code atom, string, or a Localize.LanguageTag.t/0.

Returns

• {:ok, flag_string} where flag_string is the Unicode flag emoji, or an empty string if the territory does not have a flag representation.

• {:error, exception} if the territory is not known.

Examples

iex> Localize.Territory.unicode_flag(:US)
{:ok, "🇺🇸"}

iex> Localize.Territory.unicode_flag(:GB)
{:ok, "🇬🇧"}

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

iex> {:ok, tag} = Localize.validate_locale(:en)
iex> Localize.Territory.unicode_flag(tag)
{:ok, "🇺🇸"}

@spec unicode_flag!(Localize.LanguageTag.t() | atom() | String.t()) :: String.t()

Same as unicode_flag/1 but raises on error.

Examples

iex> Localize.Territory.unicode_flag!(:US)
"🇺🇸"