= 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 (~boincam/pootle/update.sh) pulls modified templates from 
the BOINC repo and adds them to the Pootle database.

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

update.sh should perform the following functions for each supported pootle project (boinctrunk, setiweb):
1. Commit to VCS all existing changes to PO files. (pootle command: commit_to_vcs)
2. Update from VCS all templates for each project. (pootle command: update_from_vcs)
3. Apply template changes to all projects/languages. (pootle command: update_against_templates)
4. Compile all catalogs used by the client software into MO files. (Execute: boinc/locale/updatetrans.sh)
5. Commit to VCS all existing changes to MO files. (git command: commit)

All pootle operations are limited to just the boinc/locale directory structure.  Projects are expected to
have a similar structure.

'boinc/locale/updatetrans.sh' compiles BOINC-Manager.po, BOINC-Client.po, BOINC-Web.po, and BOINC-Setup.po if
the datestamps on the po and mo file are different.  After completing the compilation process it touches both
files.

== Post Translation Updates ==

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