= Translating BOINC =

The translation of BOINC involves several steps:

 * Generate "templates" (.pot files) containing translatable strings from the BOINC source code.
 * Import these templates into Pootle.
 * Volunteers translate the strings in Pootle.
 * Export the translations (*.po files) from Pootle to the BOINC Git repo
 * Deploy the new translations.

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

 ||= Component =||= directory =||= Template file =||= Command =||
 || BOINC web site || doc/ || BOINC-Web.pot || build_po.php ||
 || Project web site || html/user/ || BOINC-Project-Generic.pot || html/ops/build_po_boinc.php ||
 || Client || client/ || BOINC-Client.pot || build_po ||
 || Manager || clientgui/ || BOINC-Manager.pot || build_po ||
 || Mac installer || mac_installer/ || BOINC-Setup.pot || build_po ||
 || Android GUI || android/ || BOINC-Android.pot || a2po export -v ||

All template files are stored in '''locale/templates/''' in the BOINC repo.
The translations for language X are stored in '''locale/X/'''.

== Software releases ==

Translation activity takes place in trunk.
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 ==

If a faulty template file is committed to the BOINC repo and picked up by Pootle,
all existing translations will be lost.
Therefore manual validation is used.
The process is as follows:

 * Once a day, a script '''build_pos''' is run as a cron job.
    This script generates a template for each component,
    leaving the .pot file in the component directory.
    It then compares the .pot file with the one in '''locale/templates'''.
    If they differ (not counting comments) it sends an email to Rom and David.
 * On receiving this email, Rom and/or David examines the new template file.
    If it's valid, they move it to '''locale/templates''' and commit it.

== Translation ==

Twice daily a cron job pulls modified templates from the BOINC repo and adds them to the Pootle database.
DETAILS?

[http://docs.translatehouse.org/projects/pootle/en/stable-2.5.0/server/commands.html Pootle Commands]

Pootle takes care of the bulk of this with the following commands (pootle/update.sh):
{{{
/usr/bin/pootle commit_to_vcs --project boinctrunk
/usr/bin/pootle update_from_vcs --project boinctrunk
/usr/bin/pootle update_against_templates --project boinctrunk
/usr/bin/pootle refresh_stats --project boinctrunk
}}}

== Post Translation Updates ==

After all the latest updates have been committed the compiled PO files need to be updated.
The end of the pootle/update.sh file it executes boinc/locale/updatetrans.sh which handles compiling the PO files into MO files.
IS THIS AUTOMATED?

Converting the Android PO file back into the native Android localization system XML files involves executing:
{{{
a2po export -v
}}}

== 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 ===