@spec canonical_message(String.t(), Keyword.t()) ::
  {:ok, String.t()} | {:error, String.t()}

Formats a message into a canonical form.

This allows for messages to be compared directly, or using jaro_distance/3.

Arguments

• message is an MF2 message in binary form.

• options is a keyword list of options. The default is [].

Options

• :trim determines if the message is trimmed of whitespace before formatting. The default is true.

Returns

• {:ok, canonical_message} as a string.

• {:error, reason} on parse error.

Examples

iex> Localize.Message.canonical_message("{{Hello {$name}!}}")
{:ok, "{{Hello {$name}!}}"}

@spec canonical_message!(String.t(), Keyword.t()) :: String.t() | no_return()

Formats a message into a canonical form or raises if the message cannot be parsed.

Arguments

• message is an MF2 message in binary form.

• options is a keyword list of options. See canonical_message/2.

Returns

• The canonical message as a string.

Examples

iex> Localize.Message.canonical_message!("{{Hello {$name}!}}")
"{{Hello {$name}!}}"

@spec format(String.t(), bindings(), options()) ::
  {:ok, String.t()} | {:error, Exception.t()}

Format an MF2 message into a string.

The ICU MessageFormat 2 uses message patterns with variable-element placeholders enclosed in {curly braces}. The argument syntax can include formatting details via annotation functions.

Arguments

• message is an MF2 message string.

• bindings is a map or keyword list of arguments that are used to replace placeholders in the message.

• options is a keyword list of options.

Options

• :locale is any valid locale name or a t:Localize.LanguageTag struct.

• :trim determines if the message is trimmed of whitespace before formatting. The default is false.

• :backend determines which formatting engine to use. Accepts :nif or :elixir. When set to :nif, the ICU NIF is used if available, otherwise falls back to the pure-Elixir interpreter. The default is :elixir.

• :functions is a map of %{String.t() => module()} that registers custom MF2 formatting functions for this call. Each module must implement the Localize.Message.Function behaviour. Per-call functions take precedence over application-level functions registered via config :localize, :mf2_functions. See Localize.Message.Function for details.

Returns

• {:ok, formatted_message} on success.

• {:error, exception} where exception is a Localize.BindError for unbound variables or a Localize.FormatError for formatting failures.

Examples

iex> Localize.Message.format("{{Hello {$name}!}}", %{"name" => "World"})
{:ok, "Hello World!"}

@spec format!(String.t(), bindings(), options()) :: String.t() | no_return()

Formats a message and returns the result or raises on error.

Same as format/3 but returns the formatted string directly or raises an exception.

Arguments

• message is an MF2 message string.

• bindings is a map or keyword list of arguments.

• options is a keyword list of options. See format/3.

Returns

• The formatted string.

Examples

iex> Localize.Message.format!("{{Hello {$name}!}}", %{"name" => "World"})
"Hello World!"

@spec format_to_iolist(String.t(), bindings(), options()) ::
  {:ok, list(), list(), list()}
  | {:error, list(), list(), list()}
  | {:error, String.t()}
  | {:format_error, String.t()}

Format an MF2 message into an iolist.

Arguments

• message is an MF2 message string.

• bindings is a map or keyword list of arguments that are used to replace placeholders in the message.

• options is a keyword list of options.

Options

• :locale is any valid locale name or a language tag struct.

• :trim determines if the message is trimmed of whitespace before formatting. The default is false.

Returns

• {:ok, iolist, bound, unbound} on success.

• {:error, iolist, bound, unbound} when bindings are missing.

• {:format_error, reason} on format error.

Examples

iex> Localize.Message.format_to_iolist("{{Hello {$name}!}}", %{"name" => "World"})
{:ok, ["Hello ", "World", "!"], ["name"], []}

@spec jaro_distance(String.t(), String.t(), Keyword.t()) ::
  {:ok, float()} | {:error, String.t()}

Returns the Jaro distance between two messages.

This allows for fuzzy matching of messages which can be helpful when a message string is changed but the semantics remain the same.

Arguments

• message1 is an MF2 message in binary form.

• message2 is an MF2 message in binary form.

• options is a keyword list of options. The default is [].

Options

• :trim determines if the message is trimmed of whitespace before formatting. The default is false.

Returns

• {:ok, distance} where distance is a float between 0.0 and 1.0.

• {:error, reason} on parse error.

Examples

iex> Localize.Message.jaro_distance("{{Hello}}", "{{Hello}}")
{:ok, 1.0}

@spec jaro_distance!(String.t(), String.t(), Keyword.t()) :: float() | no_return()

Returns the Jaro distance between two messages or raises.

Same as jaro_distance/3 but returns the distance directly.

Arguments

• message1 is an MF2 message in binary form.

• message2 is an MF2 message in binary form.

• options is a keyword list of options.

Returns

• A float distance between 0.0 and 1.0.

Examples

iex> Localize.Message.jaro_distance!("{{Hello}}", "{{Hello}}")
1.0