Gettext

Messages are stored in Portable Object (.po) files. These files must follow a specific directory structure: priv/gettext/LOCALE/LC_MESSAGES/DOMAIN.po.

• LOCALE: The language/region code (e.g., pt_BR).
• DOMAIN: The translation domain. If you use the standard gettext or ngettext macros, the domain is default.

Example path for pt_BR default messages: priv/gettext/pt_BR/LC_MESSAGES/default.po.

Gettext provides Mix tasks to automate the workflow of extracting strings from source code and updating translation files.

Extract messages

Scan your source code for gettext calls and sync them to .pot template files in priv/gettext:

mix gettext.extract

Merge templates into locales

Merge the extracted .pot templates into your existing .po locale files:

Merge into all locales:

mix gettext.merge priv/gettext

Merge into one specific locale:

mix gettext.merge priv/gettext --locale en

Extract and merge in one step:

mix gettext.extract --merge

Add :gettext to your mix.exs dependencies to include the Gettext internationalization system in your Elixir project.

defp deps do
  [
    {:gettext, ">= 0.0.0"}
  ]
end

Gettext provides a family of macros (gettext/2, ngettext/4, etc.) that allow you to translate strings in your code while enabling the mix gettext.extract tool to automatically find and pull these strings into your .pot files.

To use these macros, you must first set up a Gettext backend in your module using use Gettext, backend: MyApp.Gettext. Once the backend is defined, the standard macros are automatically imported and will use that backend by default.

defmodule MyApp.Gettext do
  use Gettext, otp_app: :my_app
end

defmodule MyApp.Controller do
  use MyApp.Gettext

  def index(conn, _params) do
    gettext("Hello, world!")
  end
end

To create a custom Gettext backend, you must use Gettext.Backend within a module. You are required to provide the otp_app option. This module generates the necessary callbacks required by the Gettext.Backend behaviour.

Note on usage pattern: Since version v0.26.0, the workflow is split:

1. Define the backend using use Gettext.Backend, otp_app: :your_app.
2. Use the functions in that backend by calling use Gettext, backend: YourApp.Gettext in your application modules.

defmodule MyApp.Gettext do
  use Gettext.Backend, otp_app: :my_app
end

To use Gettext, you must first define a backend module by using Gettext.Backend. The otp_app option should point to your application's atom name.

defmodule MyApp.Gettext do
  use Gettext.Backend, otp_app: :my_app
end

By using Gettext in your module and passing your backend, you gain access to several translation macros:

• gettext(string): Translates a simple string.
• ngettext(singular, plural, n): Handles pluralization based on the integer n.
• dgettext(domain, string): Translates a string using a specific domain (e.g., for error messages).

use Gettext, backend: MyApp.Gettext

# Simple message
gettext("Here is one string to translate")

# Plural message
number_of_apples = 4
ngettext("The apple is ripe", "The apples are ripe", number_of_apples)

# Domain-based message
dgettext("errors", "Here is an error message to translate")

Gettext macros require msgid, msgid_plural, domain, and msgctxt to be strings (or expand to strings) at compile-time to allow for successful extraction.

If you need to perform dynamic lookups (where the message key is a variable determined at runtime), do not use the macros. Instead, use the functions in the Gettext module directly:

# Correct way for dynamic lookup:
string = "hello world"
Gettext.gettext(MyApp.Gettext, string)

If you are in a module that does not have a Gettext backend defined via use Gettext, or if you need to use a specific backend explicitly, you can use the _with_backend variants of the macros. These require you to pass the backend module as the first argument. Note that you must require Gettext.Macros to use them.

defmodule MyApp.Controller do
  require Gettext.Macros

  def index(conn, _params) do
    Gettext.Macros.gettext_with_backend(MyApp.Gettext, "Hello, world!")
  end
end

You can attach comments to the next Gettext macro call using gettext_comment/1. These comments will appear in your .pot files prefixed with #., providing context for translators.

gettext_comment("The next message is awesome")
gettext_comment("Another comment for the next message")
gettext("The awesome message")