Maintaining OpenMRS Module Translations via Transifex

Transifex (www.transifex.com) is a utility that OpenMRS uses to facilitate the community translation of messages.properties codes.

Adding a Module To Transifex

First post a message in https://talk.openmrs.org/c/dev/translation saying that you want to add your module to the OpenMRS Transifex account, and with a pointer to where the code lives. The translation manager will approve this request and create the resource for you in our Transifex project.

The translation manager will do this:

1. Within the OpenMRS project in Transifex, create a new resource (click on "Resource" -> "Add New Resource")
2. Choose the the Upload File option and upload the messages.properties file for your module (file format is Java properties file - Unicode). Click Create Resource.
3. Change the resource and slug name to something intelligent (they default to "messages.properties", but you should set something like name="Radiology module" and slug="radiology-module").
4. Set up Transifex to automatically update the messages.properties file from github nightly:
   1. Click on the "Auto Update Resources" button from the resources view (up one level from where you are if you just created a resource)
   2. Add the URL of the messages.properties file on Git Hub (e.g. https://github.com/openmrs/openmrs-module-htmlformentry/blob/master/api/src/main/resources/messages.properties)

Then as the module owner you should take the following steps:

1. Configure the module to be updateable via the Transifex command-line client:

   1. Install the Transifex client and set up the .transifexrc configuration file (see the docs)
      

   2. Create a new directory .tx  in the top-level module directory with a single file named "config" with the following content (replace htmlformentry-module with the slug you chose for your module in step #3):
      [main]
      host = https://www.transifex.com/

      [OpenMRS.htmlformentry-module]

      file_filter = api/src/main/resources/messages_<lang>.properties
      source_file = api/src/main/resources/messages.properties
      source_lang = en
      
      Note: for more info on the tx config file see http://docs.transifex.com/client/config/

2. Add this new file and directory to git and push it up.
3. If you have any existing translations for the module, push these translations up to Transifex via executing the following Transifex client command at the command line: "tx push -tf" 

Setting up Automatic Translation Updates

The Bamboo Commit Translations to GitHub job automatically downloads translation updates from Transifex, commits them, and pushes the changes to GitHub. To make it do that for a new repository, add the repository to "Repositories" and create a new "stage." The script it runs is in openmrs-contrib-bamboo.

Adding a New Language to a Module

Note that if you add a new language to a module and do a "tx pull" it should pull in any translations and create the new messages_*.properties file.  Note that a line must also be added to the module's config.xml file so that the new messages_*properties file is referenced in the messages section and mapped to the appropriate locale.

Gotchas

One very important point–if you update a messages_*.properties file manually (ie, any of the translation files, but not the main messages.properties) you need to make sure to push these changes up to Transifex ("tx push -tf") or next time you import from Transifex, the translations added manually will be overwritten.