How to Contribute Translations to OpenTrials

There are three kinds of text that need translation in an OpenTrials Web site:

1. Text provided by end-users as part of their clinical trials submissions. This is translated by the end-users themselves, using the Web site end-user interface, and those translations provided are usually displayed side-by-side (for an example, see: http://www.ensaiosclinicos.gov.br/rg/RBR-74rr6s/). These translations are stored in the relational database, along with all user provided data.

2. Text provided by Web site administrators, including content such as news and FAQ items, but also terms of use, controlled vocabularies (eg. intervention code), and labels and help text linked to individual clinical trial registration form fields. These are also stored in the relational database and are edited by site administrators using the Django Admin interface, which is user friendly but requires a super user login to the OpenTrials instance at a special URL, such as http://opentrials.bvsalud.org/admin/ or http://www.ensaiosclinicos.gov.br/admin/. Default content for these translations are provided as database fixtures for loading when a new OpenTrials instance is deployed.

3. Text provided by the OpenTrials developer team, including all text displayed on the site user interface, such as page and table headings, menu and button labels, etc., except those that are provided by the Web site administrators. These translations are part of the standard OpenTrials software distribution and are stored in special files included with the software download. The files use the .po and .mo extension (for example, the Spanish translation is at opentrials/locale/es/LC_MESSAGES. A simple text editor can be used to edit the .po files, but these have to be compiled by developers into .mo files using special Django i18n (internationalization) tools. The .po and .mo formats are part of the gettext software translation system used by Django and many other Open Source projects.

Most Open Source software is translated only using method 3 above. But, due to the complexity of the subject matter (clinical trial registration), it was decided during development that it would be useful if the administrators in charge of a registry (such as REBEC) could easily change the labels and help text linked to the clinical trial submission form fields, based on feedback gathered in the submission review process. While this solution provides the necessary agility to improve and clarify the labels and help texts that guide the submissions, it does mean that it is not always obvious whether a particular string that appears in the user interface should be translated using the Django admin interface (method 2) or by editing a .po file (method 3).

Translating administrator provided text

The screenshots below show how an administrator uses the Django admin interface to translate some of the texts.

Main page of the Django admin interface, showing several apps and tables

In OpenTrials, the Assistance app is used to edit field level help texts and labels, as well as the FAQ

Django admin interface showing the list of tables of a specific application, called Vocabulary

The Vocabulary app is for translating the controlled vocabularies used in several clinical trial registration fields, such as intervention code, sponsoring institution types, country codes etc. The screen shows the values of one particular table, called Institution types. For all controlled vocabularies in OpenTrials, the default language is English, and that is what is shown in the first column of the table. The translation completed column shows a green icon when all translations required by this Open Trials instance have been provided. The list of translations required by a specific Open Trials instance is a configuration setting in the settings.py file at the root of the instance. The last column lists the translations that are missing in the specific vocabulary item.

Django admin interface showing the editing form of a single Vocabulary record

The top half of the screen shows the English version of the fields. The bottom half shows the Portuguese and Spanish translations. The language options available for translation are determined by a configuration setting in the settings.py file at the root of the instance.

Translating software messages

OpenTrials is build using : Django framework, which supports text internationalization(aka : i18n). But, how does i18n work?

All text which will be translated by our application must be tagged as translatable. After marking texts as translatable, Django’s translation machinery uses the standard gettext module that comes with Python to create some translations catalogs. Those catalogs has the original text and a space where de translator (a person, human) will place the translated text. For each translation language is created a catalog (as you can see here [3], in a Brazilian portuguese catalog).

Originally, just after created, a translation catalog have the original text (tagged by msgid) followed by a translation space (tagged by msgstr), just like the example below (line 80 from : .po file):

#: custom/ecgovbr/templates/base.html:40 custom/ecgovbr/templates/base.html:80
#: registration/forms.py:35 templates/base.html:45 templates/base.html.py:85
msgid "Username"
msgstr ""

The translator who will complete the catalog inserting its translation:

#: custom/ecgovbr/templates/base.html:40 custom/ecgovbr/templates/base.html:80
#: registration/forms.py:35 templates/base.html:45 templates/base.html.py:85
msgid "Username"
msgstr "Usuário"

For helping the translator, there are some software that organize the catalogs http://www.poedit.net/, http://translate.sourceforge.net/wiki/.

How can I get the catalogs ?

To collaborate in translations, you must first get the OpenTrials translations catalog. If you have a development version of OpenTrials, you can step forward. But, if you don't have a devellopment copy from OpenTrials, you can do ONE of the following options:

• Get an full source from OpenTrials projetc following the [HowToInstall]
• Get just the catalogs, forwarding the steps below (assumed you have Subversion installed in your machine):

svn co http://svn.reddes.bvsalud.org/clinical-trials/trunk/opentrials/locale

Now I have the catalogs, but how can I insert new translations?

Your catalog folder must be like this:

.
|-- es
|   `-- LC_MESSAGES
|       |-- django.mo
|       `-- django.po
`-- pt_BR
    `-- LC_MESSAGES
        |-- django.mo
        `-- django.po

You have both es (Spanish) and pt_BR (Brazilian portuguese) folders. In each folder there are two files: .mo and .po. The .po file is where you will do the translations. The other one, the .mo file, is this catalog after to be compiled (it is not really necessary for us in this moment).

You can now put the translations text editing the .mo file in your favorite text editor (like VIM, Gedit or Notepad) and save it, ou use an translator manager as Poedit[4], which can be installed by you packages manager (if you use Linux).

After to do the translations

After you finished the translation, you must commit (the act of sending your code to the repository) the .po files. If you have no habits to use subversion, to commit an single modified file you can follow as the example below (assuming you are in locale folder):

#committing th spanish catalog
svn commit es/LC_MESSAGES/django.po -m "your message here"

After the -m flag you put your comments, for example, saying what translations you did.