Translating a Module (i18n internationalization)

So you have a module, and you want to give it more reach.

Here's how:

1. Create message files

Workbench's develop-module is designed to generate "message files" for you.

Assuming you have your module, helloworld/, checked out in a directory adjacent to cjworkbench/:

1. In one terminal, cd cjworkbench && bin/dev develop-module helloworld. This will start watching for code changes.
2. Create a directory, helloworld/locale/. develop-module should notice this new directory and write files into it.
3. Add the locale/ directory to the Git repository. Commit and push.

You will now have:

• helloworld/locale/templates/messages.pot: a file that lets Gettext-compatible translation software add new languages.
• helloworld/locale/en/messages.po: English translations.
• helloworld/locale/{locale_id}/messages.po (for each supported locale): Placeholders for other languages.

There will be messages added for all the translatable parts of your module's .yaml specification: the module's name, description and parameters.

Do not modify the Enlish translations: develop-module will always overwrite them. You may use Gettext-compatible software to translate the other languages' messages.po files.

Don't worry about missing translations: they won't cause any crash, and user behavior won't change now that messages.pot exists. Workbench will fall back to the English message when a non-English message is missing. (All non-English messages are missing at this stage.)

2. Translate in Pontoon

You can use any Gettext-compatible software to edit messages.po files. At Workbench, we help our users translate using Pontoon.

Module setup

Here's how we set up a module like helloworld (after the commit in the "Create message files" section is pushed):

1. git branch -c pontoon && git push -u origin pontoon
2. Browse to https://workbenchdata-i18n.herokuapp.com/admin/projects/ for the "Add project" form
3. Enter name=helloworld, slug=helloworld (same slug as in the module spec)
4. Move "English" (en) to the "Read-only" section. Move Greek to the Localizable section. (Alternatively: "Copy locales from another project" and choose calculate.)
5. Enter repository: [email protected]:CJWorkbench/helloworld.git
6. Enter branch: pontoon
7. Enter download prefix: `https://raw.githubusercontent.com/CJWorkbench/helloworld/locale/{locale_code}
8. "Save Project"
9. "Sync"

Now you should see helloworld in the list of projects at https://workbenchdata-i18n.herokuapp.com/admin/

Translator workflow

A translator using Pontoon will:

1. Log in to https://workbenchdata-i18n.herokuapp.com/projects/
2. Click helloworld
3. Click a language
4. Click messages.po
5. Use Pontoon's interface to save messages

Every few minutes, Pontoon will (pull and then) push a commit to the pontoon branch of helloworld.

Developer workflow

A developer responds to Pontoon's branch by:

1. Browse to https://github.com/CJWorkbench/helloworld
2. Notice GitHub suggests comparing the pontoon branch
3. Create and merge a pull request. DO NOT delete the pontoon branch.
4. Re-import the module in a dev environment, then staging, then production.