Getatrex

Getatrex is a Gettext automatic translator written in Elixir. It translates *.po files generated by Gettext in your Elixir/Phoenix project (compatible with modern Phoenix/Gettext releases).

Features

• Automatically translates Gettext *.po files (singular + plural)
• Preserves PO metadata (comments, flags, references, context)
• Protects placeholders like %{name} and {{name}}
• Auto-detects HTML strings and uses HTML-aware translation
• Simple integration with Elixir/Phoenix projects
• Utilizes Google Cloud Translation API for translations

Demo

Watch a demonstration of Getatrex in action:

Installation

Add Getatrex as a dependency

To install Getatrex, add it to your list of dependencies in mix.exs:

def deps do
  [{:getatrex, "~> 0.2", only: :dev, runtime: false}]
end

This will also install goth, which is required for Google Cloud Translation.

Configure Google Cloud credentials

To use the Google Cloud Translation API you need Google credentials (service account JSON or Application Default Credentials). If you don't have one, create it in the Google Cloud Console.

Download the JSON file with your credentials and store it somewhere safe (avoid including it in your source control).

Then choose one of the options below:

Option A: configure Goth in config/config.exs:

# Google credentials
config :goth, json: "path/to/goth_credentials.json" |> File.read!

Replace path/to/goth_credentials.json with the actual path to your credentials file.

Option B: set an env var pointing to the JSON file:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/goth_credentials.json

Getatrex uses Goth's default credential discovery, so either option works.

Usage

Quick start (new locale)

1. Follow the Gettext workflow in your app (extract + merge). For example:

$ mix gettext.extract
$ mix gettext.merge priv/gettext

2. Generate a new locale, e.g. Spanish:

$ mix gettext.merge priv/gettext --locale es

3. IMPORTANT: commit the new locale so you can easily review/revert:

$ git commit -a -m 'adding new Spanish locale'

4. Run Getatrex:

$ mix getatrex es

Getatrex will generate translated_default.po next to your original:

priv/gettext/es/LC_MESSAGES/default.po
priv/gettext/es/LC_MESSAGES/translated_default.po

Open the translated file, review it, and replace the original default.po when you're happy.

Translating other domains (errors.po, custom domains)

By default, Getatrex translates default.po. To translate other domains:

$ mix getatrex es --domain errors
$ mix getatrex es --domain default --domain errors

You can also pass a comma-separated list:

$ mix getatrex es --domain default,errors

Updating existing locales

If you already have a locale and new strings were added:

1. Merge updated POT files:

$ mix gettext.extract
$ mix gettext.merge priv/gettext --locale es

2. Run Getatrex again for that locale:

$ mix getatrex es

Only empty msgstr entries are translated. Existing translations are preserved.

Configuration

You can tune the translation request options in config/config.exs:

config :getatrex, google_translate: [
  format: :auto, # :auto | :text | :html
  model: "nmt"   # optional, if your Google project supports it
]

Notes and tips

• Placeholders like %{name} and {{name}} are protected from translation.
• HTML tags in strings trigger HTML-aware translation automatically.
• If a locale file is missing, Getatrex prints instructions to generate it.

Troubleshooting

• Missing required configuration for Goth / auth errors:
  • Ensure your credentials are set via config :goth, json: ... or GOOGLE_APPLICATION_CREDENTIALS=/path/to/creds.json.
  • Verify the Translation API is enabled in your Google Cloud project.
• Permission denied from the API:
  • Make sure the service account has Cloud Translation API User permissions.
• unknown locale errors:
  • Ensure the locale folder exists under priv/gettext/<locale>/LC_MESSAGES.

Example

Before (default.po):

msgid "Hello %{name}"
msgstr ""

Run:

$ mix getatrex es

After (translated_default.po):

msgid "Hello %{name}"
msgstr "Hola %{name}"

Roadmap

1. Automatically write translations to the original default.po file, eliminating the need for a copy-paste step.