====== Collaborative translation ======

===== Who is this guide for =====

  * Anyone willing to collaborate in the translation of the Datahub's module (CKAN project).
  * Anyone willing to collaborate translating or extending ODM's Taxonomy
  * Administrators of the system responsible for uploading updated translations

===== What this guide teaches =====

  * How to join ODM's Taxonomy and CKAN's translation project on Transifex
  * How to suggest the translation to languages that are not supported yet
  * How to undertake the translation tasks
  * How to upload updated translations into CKAN

===== Things to know in forehand =====

==== What is Transifex ====

[[http://www.transifex.com/|Transifex]] is a web-based translation platform, also known as [[https://en.wikipedia.org/wiki/Globalization_Management_System|Globalization Management System (GMS)]]. It targets technical projects with frequently updated content, such as software, documentation and websites and encourages the automation of the localization workflow by integrating with the tools used by developers.

Transifex is offered as a software as a service and features both commercial plans and free accounts for open source projects.

===== Localising Data Hub's user interface =====

==== Current Status ====

The Data Hub module has been built using CKAN as base technology. CKAN already offers support for several international languages but lacks support on some of those we need on the ODM project. The current table shows the percentage of localised strings in the current version of CKAN (2.2.1) which is used for the Data Hub module.

^ Language      ^ % Done       ^ 
| English    | 100%      | 
| Khmer    | 100%      | 
| Vietnamese    | 100%      | 
| Thai    | 99%      | 
| Burmese    | 0%      | 
| Lao    | 0%      | 

In order to encourage a collaborative effort for the localisation of the different strings of the user interface, the CKAN project is using Transifex [www.transifex.com], a platform which allows projects to expose the list of strings to be translated on each release and give translators and collaborators the possibility to help on the localisation process for each of the languages.

==== Using Transifex for localising ODM's CKAN instance ====

=== Step 1: Join the translation project ===

Access the CKAN project on Transifex here: https://www.transifex.com/projects/p/ckan/ A list with the current status for the different languages and the recent activity on the translation process will be shown. There is also a button labeled “Help translating CKAN” which should be clicked in order to participate in the translation of the project.

{{ ::diagram1-join_the_translation_group.png?direct&600 |}}

For simplicity, one user for each of the languages/countries has been already registered in order to start translating words. The username for each country are:

  * Cambodia: odmcambodia
  * Thailand: odmthailand
  * Laos: odmlaos
  * Vietnam: odmvietnam
  * Myanmar: odmmyanmar

Please, ask one of [[collaborating_organizations|ODM's Admins]] for login access. However, it is also possible to register on Transifex and collaborate with your own credentials.

Once logged in, more detailed information about the current status of the translation of the project will be presented.

=== Step 2: Request the inclusion of a new language ===

<WRAP center round tip 90%>
Requests for Lao and Thai languages have been already approved by the coordinators team, so this step is not needed. Only in case of adding a new language should be considered.
</WRAP>

By clicking the “Request language” button, it is possible to request the team's coordinator to begin the translation of a language not available till now. In case it is necessary to include a new language, a request should be made. After this request is reviewed, the language will be available for translation.
{{ ::diagram3-request_new_language.png?direct&300 |}}

=== Step 3: Join the Team for translating a particular Language ===

In order to start localising strings for an already available language another request has to be sent to the project's coordinator. After clicking the desired language, the detail screen will be presented, showing the different versions for that specific Language. Here, the translator has to request permission by clicking the “Join the team” button. After permission is given, it is possible to start translating strings.

<WRAP center round info 90%>
Alex Corbi (alex@open-steps.org) is coordinator for the Thai, Lao, Burmese and Khmer groups. After requesting to join the respective team, the translation staff should notify Alex Corbi per email in order to make the approval process as quick as possible.
</WRAP>

{{ ::diagram4-join_a_team.png?direct&600 |}} 

=== Step 4: Start localising strings for a particular Language & Version ===

Once approved as a team member and in order to start localising strings, the translator must first select the Version of CKAN that he/she wants to translate for. We will be using CKAN 2.2 (the latest stable release by now). After selecting it, following dialog will appear:

{{ ::diagram5-translate_now.png?direct&600 |}}

=== Handling placeholders ===

While localising strings, translators will find characters such as %s or {0}. These elements are placeholders for dynamic loaded texts and should be respected. That means that if the original string contains it, the translated string should contain it as well. Position of the placeholders within the phrase might change though. 

{{ ::diagram6-placeholders.png?direct&600 |}}

<WRAP center round info 90%>
**Localising ODM's Data Hub means also collaborating with CKAN.**
All the strings translated by the ODM Staff using Transifex will then be merged and made available for further versions of CKAN.
</WRAP>

=== Step 5: Check error in translated file ===

Please do this before upload to repository

Download file .po to your local machine, using tool here http://poedit.net/ to check error on your .po file translate.

Or Use <code>paster --plugin=ckan check-po-files ckan.po</code> command to search for errors

===== Localising ODM's CKAN Theme =====

Within the scope of the project, a theme (ckan extension) has been developed in order to extend the functionalities and look-and-feel of the User Interface provided by CKAN. Through this process, new text strings have been inserted and therefore need to be translated. 

For that, a project on Transifex has been created under https://www.transifex.com/projects/p/ckanext-odm_theme/ . The different languages in which the taxonomy should be translated to have been already created and the same translator users assigned to the CKAN project have been added to them.

Please, refer to https://github.com/OpenDevelopmentMekong/odm-internal/odm-localization for further utilities, code and .po/.mo files.

===== Uploading updated translations into CKAN =====

  * Download the .po file from transifex
  * Update the file on our clone of ckan (https://github.com/OpenDevelopmentMekong/ckan)
  * Update odm-internal github repository (so the latest copy of the translation is there) 
  * Upload new .po to CKAN i18n folder on live instance.
  * In the live instance, compile catalog to generate .mo files:

<code>python setup.py compile_catalog</code> 

NOTE: Remember to run that command within the python virtual environment.

===== Localising ODM's taxonomy =====

The process for translating the values composing ODM's Taxonomy is analog to the one specified above. For that, a project on Transifex has been created under https://www.transifex.com/projects/p/odm-taxonomy/ . The different languages in which the taxonomy should be translated to have been already created and the same translator users assigned to the CKAN project have been added to them.

Please, refer to https://wiki.opendevelopmentmekong.net/migrating_from_previous_system#importing_translation_terms_for_odm_s_taxonomy and https://github.com/OpenDevelopmentMekong/odm-internal for instructions on how to load the taxonomy translations into CKAN and further utilities, code and .po/.mo files.

==== Current Status ====

The following table reflects the current status of the translation for ODM's Taxonomy.

^ Language      ^ % Done       ^ 
| English    | 100%      | 
| Thai    | 100%      | 
| Khmer    | 100%      | 
| Vietnamese    | 100%      | 
| Burmese    | 0%      | 
| Lao    | 0%      | 

==== Taxonomy's Translations visualization tool ====

A tool for comparing the translation of the different elements of the taxonomy is been mantained in the [[https://github.com/OpenDevelopmentMekong/OpenDevelopmentMekong.github.io|OpenDevelopmentMekong.github.io repository on Github (PRIVATE)]]. It is accessible at http://opendevelopmentmekong.github.io/.

{{ ::taxonomy_viewer.png?direct&600 |}}

===== Localizing Multisite front-end =====

==== Wordpress Multiple Site is using mqTranslate plugin for the frond-end localization. ====

To localize the Multisite Front-end, there are two ways to do it:
1. Using the language code tags:
<!--:en-->English Texts<!--:--> <!--:kh-->Khmer<!--:--> or <!--:vi-->Vietnamese<!--:-->
 
2. Using po and mo file to localize the specify strings. These translation files place in /wp-content/languages. https://github.com/OpenDevelopmentMekong/odm-frontend/tree/master/wp-content/languages

=== How to Localize the Themes for ODI ===
GetText is a a text translation utility that Wordpress localization is based on it. To customize the child theme, I would like to recommend to wrap it in the GetText echo call _e() in the php, so GetText will be able to return the translation for this string. eg. <h3><?php _e('Hello', 'opendev'); ?></h3>

We can also use the language code tags like below, however, I **don't recommend** to do use them in coding. 
<!--:en-->Hello<!--:--> <!--:kh-->សួរស្តី<!--:-->

However, the languages tags, will be needed to use in the option page of "Open Development" which is under the Appearance for Introduction Boxes and Legal disclaimer. 

{{:open-dev-option.jpg|}}


The .po file is created to contains all the strings to translate, and upload to the Transifex for localization. After the translation, the .po file need to generate to .mo file and upload it in wp-content/language directory. The name of po/mo file must following the language code of mqTranslate plugin.

For example: the language code of English is en_US, so the name of translation file is en_US.po/mo.
The strings that translated will be displayed automatically based on language selected.  

{{:header-menu.jpg|}}

=== Translating the strings ===
Transifex is using for localising ODM's front-end. For that, a project "ODM Frontend Theme" has been created on Transifex under https://www.transifex.com/projects/p/odm-frontend-theme/. The different languages in which the ODM Theme should be translated by created team who assigned to the CKAN project.

=== Translating the WordPress Taxonomy === 
The Taxonomy in WordPress is managed under the WordPress CATEGORY. To translate the taxonomy of each website on WordPress, please click Category on the left hand menu, and then click Edit any taxonomy terms to translate and update it by pressing the Update button. Tags WordPress are also required to manually translate by Editors.  
 
{{:translate-taxonomy-wp.jpg|}}