Translation

We're using Transifex for managing translations. You'll need a Transifex account in the Cadasta organisation to be able to push and pull translation files. Ask Ian to set you up!

Transifex credentials

Transifex picks up login credentials for pushing translation sources from a ~/.transifexrc file. This is obviously a bit of a pain inside the development VM, because in this case ~ is /home/vagrant, which doesn't have anything much useful in it. What I've done to make this work is to make a symbolic link from ~/.transifexrc to /vagrant/.transifexrc. In order to use this, you need to do the following:

1. Set up your Transifex account on the Transifex website.

2. Create a ~/.transifexrc file on your host machine with the following contents:

[https://www.transifex.com]
hostname = https://www.transifex.com
password = <your-transifex-password>
token =
username = <your-transifex-username>

3. COPY your ~/.transifexrc to the top-level directory of your working copy of the cadasta-platform repository. (You don't need to worry about exposing your Transifex login credentials this way by accidentally pushing your .transifexrc to GitHub: I've set Git up to ignore the Transifex credentials file.)

Once you've done this, the tx Transifex client should work inside the VM. All the commands described below are to be run inside the development VM!

Extracting and pushing translation sources

To extract translation strings from the source, go to the cadasta-platform/cadasta directory and do:

./manage.py makemessages -l en -e py,txt,html,js -s
./manage.py makemessages -l en -d djangojs

This extracts the message strings from the Python source into messages files for the default English locale (the message sources end up in cadasta/config/locale/en/LC_MESSAGES/django.po and cadasta/config/locale/en/LC_MESSAGES/djangojs.po if you ever need to check them). Note that there are two sets of messages: the "main" message set which is used for translations in Django templates and Python source code and the (much smaller) "javascript" message set which is used in the few cases where strings need to be translated directly in Javascript.

To upload message sources to Transifex for translation, in the same directory do

tx push -s

This pushes translation sources to the cadasta-platform.main and cadasta-platform.javascript resources on Transifex.

Once you've done this, any new strings for translation will appear in the Transifex UI and you can start translating.

Downloading translations and compiling

Once you have new translations to be downloaded from Transifex, go to the cadasta-platform/cadasta directory and do

tx pull -af

This pulls translations for all the locales known by Transifex for the project. Once you've done this, the message catalogue files need to be compiled for use by Django by, in the same directory, doing

./manage.py compilemessages

This will create a set of .po and .mo files in the /cadasta/config/locale folder that will need to be included in a PR.

Adding a new language

To add a new language for translations, simply add the language to the "Cadasta platform" project on the Transifex website. The next time that you pull translations using tx pull -af, a message catalogue file for the new language will be downloaded from the Transifex site.

(To make the new language appear in the drop-down language selection menu, you'll also need to add it to the LANGUAGES array in the default Django settings.)