Mojibake.LanguageTag (Mojibake v0.8.0)

Copy Markdown View Source

BCP 47 language tags, such as "en-US", "sr-Latn-RS", or "de-CH-1996".

parse/1 checks the syntax of a tag strictly and splits it into its subtags, with the case conventions of BCP 47 applied: lowercase language, titlecase script, uppercase region. It does not check the subtags against the IANA registry, so "qq-Zzzz" parses.

to_string/1 formats a parsed tag back:

iex> {:ok, tag} = Mojibake.LanguageTag.parse("SR-latn-rs")
iex> to_string(tag)
"sr-Latn-RS"

The :locale option of Mojibake.upcase/2 and the other casing functions takes a tag; only its language matters there, and matched_locale says which locale Mojibake recognizes.

Summary

Types

t()

A parsed language tag

Functions

Parse a BCP 47 language tag. Returns {:error, %Mojibake.Error{reason: :invalid_locale}} if it is not well-formed.

Like parse/1, but raises Mojibake.Error.

Format a parsed tag.

Return true if tag is a well-formed BCP 47 language tag.

Types

t()

@type t() :: %Mojibake.LanguageTag{
  extensions: [String.t()],
  extlang: String.t() | nil,
  grandfathered: String.t() | nil,
  language: String.t() | nil,
  matched_locale: String.t() | nil,
  private_use: [String.t()],
  region: String.t() | nil,
  script: String.t() | nil,
  variants: [String.t()]
}

A parsed language tag:

  • language - the language subtag, such as "sr"
  • extlang - extended language subtags, such as "yue" in "zh-yue"
  • script - an ISO 15924 script code, such as "Latn"
  • region - an ISO 3166-1 or UN M.49 region code, such as "RS" or "419"
  • variants - variant subtags, such as ["rozaj", "biske"]
  • extensions - extensions, each with its singleton, such as ["u-ca-buddhist"]
  • private_use - the private-use subtags after "x", such as ["foo"]
  • grandfathered - a whole irregular or grandfathered tag, such as "i-klingon"; the other fields are then empty
  • matched_locale - the ISO 639-1 code of the casing locale Mojibake recognizes in the tag, such as "tr", or nil

Absent subtags are nil or [].

Functions

parse(tag)

@spec parse(String.t()) :: {:ok, t()} | {:error, Mojibake.Error.t()}

Parse a BCP 47 language tag. Returns {:error, %Mojibake.Error{reason: :invalid_locale}} if it is not well-formed.

Examples

iex> Mojibake.LanguageTag.parse("sl-Latn-IT-rozaj-u-ca-buddhist-x-foo")
{:ok,
 %Mojibake.LanguageTag{
   language: "sl",
   script: "Latn",
   region: "IT",
   variants: ["rozaj"],
   extensions: ["u-ca-buddhist"],
   private_use: ["foo"],
   matched_locale: "sl"
 }}

iex> Mojibake.LanguageTag.parse("en--US")
{:error, %Mojibake.Error{reason: :invalid_locale}}

parse!(tag)

@spec parse!(String.t()) :: t()

Like parse/1, but raises Mojibake.Error.

Examples

iex> Mojibake.LanguageTag.parse!("tr-TR").matched_locale
"tr"

to_string(tag)

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

Format a parsed tag.

Examples

iex> Mojibake.LanguageTag.to_string(%Mojibake.LanguageTag{language: "pt", region: "BR"})
"pt-BR"

valid?(tag)

@spec valid?(String.t()) :: boolean()

Return true if tag is a well-formed BCP 47 language tag.

Examples

iex> Mojibake.LanguageTag.valid?("zh-Hant-TW")
true

iex> Mojibake.LanguageTag.valid?("en_US")
false