View Source Internationalization

Note: This page is being updated for OSS release. Please be patient.

Sometimes antikythera gears want to show translated messages to users. For this purpose antikythera comes with Elixir's gettext package. Documentation for gettext package is available here.

Gettext itself is one of GNU projects, and used in many other languages.

Preparing translations

  • To use gettext you must define YourGear.Gettext.
    • Antikythera's gear generator script automatically sets up YourGear.Gettext.
  • Translation files are located in priv/gettext/${locale}/LC_MESSAGES/${domain}.po.
    • ${locale} is a locale such as en, jp, etc. Default locale is en.
    • ${domain} is the domain that can be used with dgettext and defaults to default.

Workflow using Gettext mix tasks and macros

  • You can also use mix gettext.extract and mix gettext.merge to manage translation files.
  • As written in Gettext's README, the basic workflow will be as follows:
    1. Put gettext/1,2, dgettext/2,3 or other translation macro calls in your sources code.
    2. Run $ mix gettext.extract. All messages will be extracted into template files (priv/gettext/*.pot).
      • This is basically an Elixir-equivalent of GNU's xgettext.
    3. Run $ mix gettext.merge priv/gettext/ --locale <locale>. Template files will be merged into translation files.
      • Similarly, this corresponds to GNU's msginit or msgmerge.
      • If the task is run for the first time, translation files will be generated from the template files.
    4. Add translations in translation files.
  • Notice that you need to put macro calls in your code to use these features.
    • In other words, messages appearing in translation function calls (e.g. Gettext.gettext(YourGear.Gettext, "Some message")), cannot be extracted by the gettext.extract task.
  • And importantly, messages passed to macro calls must be compile-time strings.
    • You must use function calls to translate messages that dynamically change on runtime.
  • Consider these trade-offs before deciding whether you use this extract-and-edit workflow, or just manually manage translation files.

Setting locale for each web request

  • First you have to determine where to receive locale information from your users. Popular options are:

    • URL path: /some/site/ja/hello.html
    • query parameter: /some/site/hello.html?locale=ja

  • Auto-generated YourGear.Gettext module comes with put_locale/1, which is a convenient wrapper around Gettext.put_locale/2. Invoke put_locale/1 within your controller action as follows (here in the case of query parameter):

    YourGear.Gettext.put_locale(conn.request.query_params["locale"] || "ja")

    The specified locale is stored within the process's process dictionary and will be used in later *gettext calls.