What is this about?

Recently I’ve set up a continuous integration system for the coala project [0] that allows coala to be translated by anyone via the Zanata web UI [1] [2] while keeping translation strings up to date automatically.

This blog post explains how such a system can be set up to help everyone keeping focused on coding and not on pushing and pulling translations.

Prerequisites

I’m assuming that you already use travis-ci (or some other system) for continuous integration. If you are not doing this, you can set it up easily on your own. It can be done with a simple configuration file like this [3].

I’m also assuming you have a script that pulls the translation strings our of your sources and generates a POT file out of it. If you don’t use gettext you can probably do the whole process analogous.

Getting your Hands Dirty

Setting up a Zanata Account

1. Register on zanata.org
2. Create a zanata project for your project. Choose the right name as projects are currently neither renamable nor deletable.
3. Create a version in your project which you want to use.

Configuring Travis

Now this is the hard part. As you might have guessed, we only want to upload our new translation strings if the build succeeds on the master branch. So here’s what we’re doing in our .travis.yml:

after_success:
 - sh .misc/.success.sh

And in .misc/.success.sh we’re doing:

if [ "$TRAVIS_BRANCH" = "master" ] ; then
 cd .misc
 sh .install.zanata.sh
 zanata-cli-3.6.0/bin/zanata-cli -B push --key $ZANATA_API --username sils --url https://translate.zanata.org/zanata/
fi

This will ensure that only on master, only on success and only on travis the pushing will be done.

So for that to work we obviously need a few things:

1. The ZANATA_API environment variable. This is a key that gives the script the permissions so we want to keep that private. You can add that key in the travis web UI so it will be present and kept private. Simple, right? You can get this key from the Zanata web UI easily.
2. Replace sils by your username.
3. We obviously need this magic .install.zanata.sh script that installs the zanata-cli binary.

So let’s look at the .misc/.install.zhanata.sh:

if [ ! -f ./zanata-cli-3.6.0/bin/zanata-cli ] ; then
 echo Downloading zanata client...
 wget http://search.maven.org/remotecontent?filepath=org/zanata/zanata-cli/3.6.0/zanata-cli-3.6.0-dist.zip -O dist.zip -o /dev/null
 echo Unpacking zanata client...
 unzip dist.zip > /dev/null
 rm dist.zip
fi

This is very simple. Download, extract, use.

So we’re almost finished. We need one magic thing to get that whole thing up and running: the zanata.xml file which the zanata-cli binary will automatically use to determine which project and which version to choose. You can download the readily prepared configuration from the Zanata web UI through creating on the version you want to usee and then using the “…” button and click on “Download config file”.

Now we have that file, we’ll be able to user zanata-cli to push and pull translations and templates. So far so good we still haven’t generated our translations yet. For this we can add a simple hook to the zanata.xml:

<hooks>
 <hook command="push">
 <before>./generate_pot.sh</before>
 </hook>
</hooks>

This will executes the generate_pot.sh script before each push and thus gets the latest translation strings out of your code. (You’re responsible to do that for your case.)

Last thing – promised – we need to add the translation and template locations to the zanata.xml. As we located this in our example in a .misc folder to hide this stuff from the usual developer who doesn’t care about this we defined the paths as follows:

<src-dir>../locale</src-dir>
<trans-dir>../locale</trans-dir>

Voila! Here you can look at the result at one of our builds: [4]

You’re ready to go and don’t need to worry about getting your translations up to Zanata anymore. As a thank you for reading this far I have a little bonus for you: with this script [5] you can get a generated commit that updates all your translations in your repository at once. Just execute it before each release and you’re ready to go!

[0] https://github.com/coala-analyzer/coala/
[1] http://zanata.org/
[2] http://wordpress.schuirmann.eu/2015/06/call-for-translators-coala/
[3] https://github.com/coala-analyzer/coala/blob/d72eee4d9a14efd602844464335409c2635d7e18/.travis.yml
[4] https://travis-ci.org/coala-analyzer/coala/jobs/66224762#L1093
[5] https://github.com/coala-analyzer/coala/blob/d72eee4d9a14efd602844464335409c2635d7e18/.misc/pull_zanata.sh