gettext v0.13.1 Gettext.Backend behaviour

Behaviour that defines the macros that a Gettext backend has to implement.

These macros are documented in great detail in the documentation for the Gettext module.

Summary

Callbacks

Same as dgettext(domain, msgid, %{})

Translates the given msgid in the given domain

Marks the given translation for extraction and returns it unchanged

Same as dngettext(domain, msgid, msgid_plural, n, %{})

Translates the given plural translation (msgid + msgid_plural) in the given domain

Marks the given translation for extraction and returns {msgid, msgid_plural}

Same as gettext(msgid, %{})

Same as dgettext("default", msgid, %{})

Same as dgettext_noop("default", msgid)

Default handling for missing bindings

Same as ngettext(msgid, msgid_plural, n, %{})

Same as dngettext("default", msgid, msgid_plural, n, bindings)

Same as dngettext_noop("default", msgid, mgsid_plural)

Callbacks

dgettext(domain, msgid)
dgettext({line :: Macro.Env.line, env :: Macro.Env.t}, domain :: Macro.t, msgid :: String.t) :: Macro.t

Same as dgettext(domain, msgid, %{}).

See also Gettext.dgettext/4.

dgettext(domain, msgid, bindings)
dgettext({line :: Macro.Env.line, env :: Macro.Env.t}, domain :: Macro.t, msgid :: String.t, bindings :: Macro.t) :: Macro.t

Translates the given msgid in the given domain.

bindings is a map of bindings to support interpolation.

See also Gettext.dgettext/4.

dgettext_noop(domain, msgid)
dgettext_noop({line :: Macro.Env.line, env :: Macro.Env.t}, domain :: String.t, msgid :: String.t) :: Macro.t

Marks the given translation for extraction and returns it unchanged.

This macro can be used to mark a translation for extraction when mix gettext.extract is run. The return value is the given string, so that this macro can be used seamlessly in place of the string to extract.

Examples

MyApp.Gettext.dgettext_noop("errors", "Error found!")
#=> "Error found!"
dngettext(domain, msgid, msgid_plural, n)
dngettext({line :: Macro.Env.line, env :: Macro.Env.t}, domain :: Macro.t, msgid :: String.t, msgid_plural :: String.t, n :: Macro.t) :: Macro.t

Same as dngettext(domain, msgid, msgid_plural, n, %{}).

See also Gettext.dngettext/6.

dngettext(domain, msgid, msgid_plural, n, bindings)
dngettext({line :: Macro.Env.line, env :: Macro.Env.t}, domain :: Macro.t, msgid :: String.t, msgid_plural :: String.t, n :: Macro.t, bindings :: Macro.t) :: Macro.t

Translates the given plural translation (msgid + msgid_plural) in the given domain.

n is an integer used to determine how to pluralize the translation. bindings is a map of bindings to support interpolation.

See also Gettext.dngettext/6.

dngettext_noop(domain, msgid, msgid_plural)
dngettext_noop({line :: Macro.Env.line, env :: Macro.Env.t}, domain :: Macro.t, msgid :: String.t, msgid_plural :: String.t) :: Macro.t

Marks the given translation for extraction and returns {msgid, msgid_plural}.

This macro can be used to mark a translation for extraction when mix gettext.extract is run. The return value of this macro is {msgid, msgid_plural}.

Examples

my_fun = fn {msgid, msgid_plural} ->
  # do something with msgid and msgid_plural
end

my_fun.(MyApp.Gettext.dngettext_noop("errors", "One error", "%{count} errors"))
gettext(msgid)
gettext({line :: Macro.Env.line, env :: Macro.Env.t}, msgid :: String.t) :: Macro.t

Same as gettext(msgid, %{}).

See also Gettext.gettext/3.

gettext(msgid, bindings)
gettext({line :: Macro.Env.line, env :: Macro.Env.t}, msgid :: String.t, bindings :: Macro.t) :: Macro.t

Same as dgettext("default", msgid, %{}).

See also Gettext.gettext/3.

gettext_noop(msgid)
gettext_noop({line :: Macro.Env.line, env :: Macro.Env.t}, msgid :: String.t) :: Macro.t

Same as dgettext_noop("default", msgid).

handle_missing_bindings(arg0, binary)
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 translation. It takes a Gettext.MissingBindingsError struct and the translation with the wrong bindings left as is with the %{} syntax.

For example, if something like this is called:

MyApp.Gettext.gettext("Hello %{name}, welcome to %{country}", name: "Jane", country: "Italy")

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

msgid "Hello %{name}, welcome to %{country}"
msgstr "Ciao %{name}, benvenuto in %{cowntry}" # (typo)

then Gettext will call:

MyApp.Gettext.handle_missing_bindings(exception, "Ciao Jane, benvenuto in %{cowntry}")

where exception is a struct that looks like this:

%Gettext.MissingBindingsError{
  backend: MyApp.Gettext,
  domain: "default",
  locale: "it",
  msgid: "Hello %{name}, welcome to %{country}",
  bindings: [:country],
}

The return value of the handle_missing_bindings/2 callback is used as the translated string that the translation 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
ngettext(msgid, msgid_plural, n)
ngettext({line :: Macro.Env.line, env :: Macro.Env.t}, msgid :: String.t, msgid_plural :: String.t, n :: Macro.t) :: Macro.t

Same as ngettext(msgid, msgid_plural, n, %{}).

See also Gettext.ngettext/5.

ngettext(msgid, msgid_plural, n, bindings)
ngettext({line :: Macro.Env.line, env :: Macro.Env.t}, msgid :: String.t, msgid_plural :: String.t, n :: Macro.t, bindings :: Macro.t) :: Macro.t

Same as dngettext("default", msgid, msgid_plural, n, bindings).

See also Gettext.ngettext/5.

ngettext_noop(msgid, msgid_plural)
ngettext_noop({line :: Macro.Env.line, env :: Macro.Env.t}, msgid :: String.t, msgid_plural :: String.t) :: Macro.t

Same as dngettext_noop("default", msgid, mgsid_plural).