= The BOINC translation system=

The translation of BOINC involves several steps:

 * Generate "templates" (.pot files) containing translatable strings from the BOINC source code.
 * Commit updated template(s) and upload to Transifex.
 * Volunteers translate the strings on Transifex.
 * Updated translations are downloaded to the BOINC Git repo on !GitHub.
 * Deploy the new translations.

BOINC is divided into the following components, each with its own template file:

 ||= Component =||= directory =||= Template file =||= Language files =||
 || BOINC web site || doc/ || locale/templates/BOINC-Web.pot || locale/<lang>/BOINC-Web.po ||
 || Project web site || html/user/ || locale/templates/BOINC-Project-Generic.pot || html/languages/translations/<lang>.po ||
 || Drupal web site || drupal/ || locale/templates/BOINC-Drupal.pot || imported directly from transifex into Drupal DB ||
 || Client || client/ || locale/templates/BOINC-Client.pot || locale/<lang>/BOINC-Client.po ||
 || Manager || clientgui/ || locale/templates/BOINC-Manager.pot || locale/<lang>/BOINC-Manager.po ||
 || Mac installer || mac_installer/ || locale/templates/BOINC-Setup.pot || locale/<lang>/BOINC-Setup.po ||
 || Android GUI || android/ || android/BOINC/res/values/strings.xml || android/BOINC/res/values-<lang>/strings.xml ||

In order to update templates or translations one needs to have write permissions in the BOINC github repository and be a maintainer on the BOINC Transifex project. The tools '''xgettext, tx, pofilter and pocompile''' (Debian packages: sqlite3, gettext, transifex-client, translate-toolkit) need to be installed to do the updates.
The transifex client needs to be configured with credentials of your transifex account in order to use it (see: https://docs.transifex.com/client/client-configuration#-transifexrc).
Android uses different language codes for regional languages so there is an additional mapping configured in '''.tx/config'''.

== Software releases ==

Translation activity takes place in master.
When a release branch (client or server) is created,
its translations are the contents of '''locale/''' at that point.
If translations change after that,
or new translatable strings are added to the branch,
we'll need to back-port changes to the .po files.

== Template generation ==

New templates are needed if translatable strings change in source code. The script '''locale/update_templates.sh''' generates the templates (except Drupal and Android) and prepares them for commit. See script output for further manual steps. Transifex has a Translation Memory so pushing a faulty template does not remove existing translations. Just push a fixed template and translations will be recovered.

Templates for Android and Drupal need to be committed and pushed to Transifex (use '''tx push -s''') separately.

Projects can create templates for their project specific website using '''html/ops/build_po.php''' and send it to Transifex for translation too. There needs to be project Transifex project first so contact the PMC first.

== Translation ==

New translations need to be downloaded from Transifex and committed into the BOINC Github repository using '''locale/update_translations.sh'''. Translations are only downloaded if they are at least 97% complete and already present in the repository. New translations need to be downloaded using '''tx pull -a'''.

'''Note:''' Transifex uses the timestamp of .po files to determine if new ones need to be downloaded. Since git updates timestamps when switching branches it may be necessary to force the download of translations ('''tx -f''') in order to get the newest ones.

This workflow currently does not delete outdated translation files from the git repository! 

== Deployment ==

=== The BOINC web site ===

The BOINC web code expects translation files to be in ../languages/translations/.
On the BOINC web server, this directory contains symbolic links from X.po
to '''../../locale/X/BOINC-Web.po'''.

'When we add a new language, we need to add a new symbolic link.'

Deploying new translations requires running the script
'''doc/update_translations.php''',
which converts the .po files to a PHP translation array.
This is done from cron.

=== Project web sites ===

There is currently no detailed workflow how to deploy project specific translations. But one needs to adapt '''.tx/config''' and '''locale/update_translations.sh''' accordingly to download project-specific translations to '''html/languages/project_specific_translations/''' and compile them together using '''html/ops/update_translations.php'''.

The Drupal website contains an admin function to directly download translations from Transifex (for Drupal generic and project-specific parts).