# messengyr v0.0.1 Messengyr.Web.Gettext

A module providing Internationalization with a gettext-based API.

By using Gettext, your module gains a set of macros for translations, for example:

    import Messengyr.Web.Gettext

    # Simple translation
    gettext "Here is the string to translate"

    # Plural translation
    ngettext "Here is the string to translate",
             "Here are the strings to translate",
             3

    # Domain-based translation
    dgettext "errors", "Here is the error message to translate"

See the Gettext Docs for detailed usage.

# Summary

## Functions

dgettext(domain, msgid, bindings \\ Macro.escape(%{}))
dgettext_noop(domain, msgid)
dngettext(domain, msgid, msgid_plural, n, bindings \\ Macro.escape(%{}))
dngettext_noop(domain, msgid, msgid_plural)
gettext(msgid, bindings \\ Macro.escape(%{}))
gettext_noop(msgid)
handle_missing_bindings(exception, incomplete)

Default handling for missing bindings

lgettext(locale, domain, msgid, bindings)
lngettext(locale, domain, msgid, msgid_plural, n, bindings)
ngettext(msgid, msgid_plural, n, bindings \\ Macro.escape(%{}))
ngettext_noop(msgid, msgid_plural)

# Functions

dgettext(domain, msgid, bindings \\ Macro.escape(%{})) (macro)
dgettext_noop(domain, msgid) (macro)
dngettext(domain, msgid, msgid_plural, n, bindings \\ Macro.escape(%{})) (macro)
dngettext_noop(domain, msgid, msgid_plural) (macro)
gettext(msgid, bindings \\ Macro.escape(%{})) (macro)
gettext_noop(msgid) (macro)
handle_missing_bindings(exception, incomplete)

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 `c: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

Callback implementation for `Gettext.Backend.handle_missing_bindings/2`.

lgettext(locale, domain, msgid, bindings)
lngettext(locale, domain, msgid, msgid_plural, n, bindings)
ngettext(msgid, msgid_plural, n, bindings \\ Macro.escape(%{})) (macro)
ngettext_noop(msgid, msgid_plural) (macro)