Maintaining Cotonti translations with Transifex

#1. Introduction

Since v.0.9.13 Cotonti's language files are compatible with Transifex translation service and you can join our international translations teams there:

Please read Transifex Help Pages to get started with the service. In this document we will only cover some topics specific to Cotonti.

After registration as Transifex user you can join our translation team. You would be able to join for some language subteams or request for creation a new language pack. After you'll be approved as a translator you can use online web-interface of Trtansifex to translate files or download a pack of it to translate it offline with your preferred editor. 

Below you can read how to setup tools for proper «offline» translation.

#2. Setting up the client tools

You can edit everything online but as Cotonti has plenty of language files, in many cases it would be more comfortable to copy files on your disk and edit them with your favorite editor. For such a case Transifex has a console Client tool.

Python interpreter is requried to use the client tools. If you don't have one, get it from If you are using Windows, setting some shortcuts would be handy too.

Then you can install Transifex 'tx' tool as described in this section.

We also maintain a set of helper tools to manipulate language files easier in this repo: They are also written in Python and run in command line.

#3. Getting a working copy

Transifex works much like a git repository, so what you'd probably like to do first is to checkout yourself a working copy.

First, make a new folder, e.g. called 'cot-lang' and enter it in the command line:

cd cot-lang

Then initialize a Transifex repo in it:

tx init

After doing so, import repository configuration using this command:

tx set --auto-remote

To map Transifex translations to Cotonti langfiles correctly, open '.tx/config' file that the previous command created for you and replace all of its contents with the actual Cotonti configuration for Transifex:

Note for advanced users: contents of this file were generated by '' tool given current Cotonti source tree as an argument, e.g.:

python ~/htdocs/cotonti

Now you can pull all the existing langfiles to your working copy:

tx pull -a

Done, you now have a source tree with only language files in it.

#4. Making an existing locale compatible with Transifex

If you have an existing locale prior to 0.9.13, you should update it to be compatible with Transifex. There is a tool in cotlang package called '' for it. It automates 95% of the fixes that need to be applied. Invoke it this way:

python path/to/source

It will print the results on screen. It will also print some strings that should be fixed manually. Below are some common cases.

#4.1. Multiline entries

Transifex does not support strings that have line breaks in them. So you will have to merge them into a single line. To include line breaks though, you need to make sure the strings is in double quotes and then you can replace line breaks with \n. Also when changing from single quotes to double quotes, the '$' character needs to be escaped, so it becomes '\$'. For example,

$L['multiline_example'] = 'Here is
some %1$s entry
with multiple lines';

should become

$L['multiline_example'] = "Here is\nsome %1\$s entry\nwith multiple lines";

#4.2. Arrays of options

You might also come across a few cases when values for some configuration option are localized like this:

$L['cfg_array_params'] = array(

or like this:

$L['cfg_array2_params'] = array(
	'foo' => 'Foo',
	'bar' => 'Bar'

They should become just a simple string too. So arrays are glued with ',' and associative arrays are glued this way: 'key1: value1, key2: value2'. So above examples become

$L['cfg_array_params'] = 'Foo, Bar';


$L['cfg_array2_params'] = 'foo: Foo, bar: Bar';

#5. Loading an existing locale to Transifex

Before uploading files for a new locale, make sure this locale is already registered and listed with Cotonti project on Transifex. If it's not, log into Transifex and request adding a new language to Cotonti. We will accept your request and create a new locale shortly.

There's a tool in the cotlang set called '' which simplifies copying language files here and there a lot. It copies just the language files and keeps the directory structure. You can use it to copy all language files from one folder to another:

python path/to/source path/to/destination

or you can even tell it to copy only language files for a specific locale, e.g. 'nl':

python path/to/source path/to/destination -l nl

So, if you have an existing localization e.g. for the 'nl' locale in path '~/htdocs/cotonti' and you want to copy it to '~/cot-lang' repo, you can do it using this way:

python ~/htdocs/cotonti ~/cot-lang -l nl

Now that you have copied new translation files, you can add and push them to the Transifex server:

tx push -t -l nl

Replace 'nl' in the above examples with your locale code.

At this point your locale should be already on server and you should see it filled in

#6. Updating locale files

Language files get updated from times to times. There may be new strings to be translated and some strings may be removed if they are not needed anymore. With Transifex you can monitor all these changes online and find strings to be translated. The online editing is pretty self-explaining and it has some advanced tools like Translation Memory and Automatic Translation via Google. But you might also want to keep your local copy of all locales up2date and use your favorite editor to translate files. No problem, let's use command line tools for it.

It is always good to pull fresh files from server before doing any changes:

tx pull

To pull everything, including new files, run this instead:

tx pull -a

Then you can edit files directly in the current source tree. Or you can copy updated files for your locale from other location, e.g.:

python ~/htdocs/cotonti ~/cot-lang -l nl

This command copies 'nl' locale files from ~/htdocs/cotonti folder to ~/cot-lang folder, assuming that ~/cot-lang is your Transifex repo copy and ~/htdocs/cotonti is where you keep the latest langfiles for 'nl' locale.

And vice versa, you can copy the latest files from the Transifex repo to your Cotonti site using the same tool:

python ~/cot-lang ~/htdocs/cotonti -l nl

When you are done with translating a portion of files in the Transifex repo copy, you can push your changes to the server:

tx push -t -l nl

Replace 'nl' with your locale code.

#7. Tips and tricks

Pull before you push

This rule comes from git, but tx is not git so you need to be more careful. Normally you should do it in this order:

tx pull -a # get a fresh copy # modify or copy updated files
tx push -t # push your updated translation

No comments yet
Only registered users can post new comments