@callback handle_missing_bindings(Gettext.MissingBindingsError.t(), binary()) ::
  binary() | no_return()

Default handling for missing bindings.

This function is called when there are missing bindings in a message. It takes a Gettext.MissingBindingsError struct and the message with the wrong bindings left as is with the %{} syntax.

For example, if something like this is called:

gettext("Hello %{name}, your favorite color is %{color}", name: "Jane", color: "blue")

and our it/LC_MESSAGES/default.po looks like this:

msgid "Hello %{name}, your favorite color is %{color}"
msgstr "Ciao %{name}, il tuo colore preferito è %{colour}" # (typo)

then Gettext will call:

MyApp.Gettext.handle_missing_bindings(exception, "Ciao Jane, il tuo colore preferito è %{colour}")

where exception is a struct that looks like this:

%Gettext.MissingBindingsError{
  backend: MyApp.Gettext,
  domain: "default",
  locale: "it",
  msgid: "Ciao %{name}, il tuo colore preferito è %{colour}",
  bindings: [:colour],
}

The return value of the handle_missing_bindings/2 callback is used as the translated string that the message macros and functions return.

The default implementation for this function uses Logger.error/1 to warn about the missing binding and returns the translated message with the incomplete bindings.

This function can be overridden. For example, to raise when there are missing bindings:

def handle_missing_bindings(exception, _incomplete) do
  raise exception
end

@callback handle_missing_plural_translation(
  Gettext.locale(),
  domain :: String.t(),
  msgctxt :: String.t(),
  msgid :: String.t(),
  msgid_plural :: String.t(),
  n :: non_neg_integer(),
  bindings :: map()
) ::
  {:ok, String.t()}
  | {:default, String.t()}
  | {:missing_bindings, String.t(), [atom()]}

Default handling for plural messages with a missing message.

Same as handle_missing_translation/5, but for plural messages. In this case, n is the number used for pluralizing the translated string.

Earlier versions of this library provided a callback without msgctxt. Users implementing that callback will still get the same results, but they are encouraged to switch to the new 7-argument version.

@callback handle_missing_translation(
  Gettext.locale(),
  domain :: String.t(),
  msgctxt :: String.t(),
  msgid :: String.t(),
  bindings :: map()
) ::
  {:ok, String.t()}
  | {:default, String.t()}
  | {:missing_bindings, String.t(), [atom()]}

Default handling for messages with a missing message.

When a Gettext function/macro is called with a string to translate into a locale but that locale doesn't provide a message for that string, this callback is invoked. msgid is the string that Gettext tried to translate.

This function should return {:ok, translated} if a message can be fetched or constructed for the given string. If you cannot find a message, it should return {:default, translated}, where the translated string defaults to the interpolated msgid. You can, however, customize the default to, for example, pick the message from the default locale. The important is to return :default instead of :ok whenever the result does not quite match the requested locale.

Earlier versions of this library provided a callback without msgctxt. Users implementing that callback will still get the same results, but they are encouraged to switch to the new 5-argument version.

@callback lgettext(
  Gettext.locale(),
  domain :: String.t(),
  msgctxt :: String.t() | nil,
  msgid :: String.t(),
  bindings :: map()
) ::
  {:ok, String.t()}
  | {:default, String.t()}
  | {:missing_bindings, String.t(), [atom()]}

Translates a message.

See Gettext.gettext/3 for more information.

@callback lngettext(
  Gettext.locale(),
  domain :: String.t(),
  msgctxt :: String.t() | nil,
  msgid :: String.t(),
  msgid_plural :: String.t(),
  n :: non_neg_integer(),
  bindings :: map()
) ::
  {:ok, String.t()}
  | {:default, String.t()}
  | {:missing_bindings, String.t(), [atom()]}

Translates a plural message.

See Gettext.ngettext/5 for more information.