Cotonti / Open Source PHP Content Management FrameworkContent Management Framework

Documentation / Extending Cotonti / Localizations / Maintaining Cotonti translations with Transifex

How Transifex can be used to translate Cotonti language files into more languages and to keep the locales up to date

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:

https://www.transifex.com/projects/p/cotonti/

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

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 http://python.org/download/. 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: https://github.com/trustmaster/cotlang. 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  https://www.transifex.com/projects/p/cotonti/

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:

https://raw.github.com/trustmaster/cotlang/master/tx.config

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

python cotlangtx.py ~/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 'cotlangfix.py' for it. It automates 95% of the fixes that need to be applied. Invoke it this way:

python cotlangfix.py 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(
	'Foo',
	'Bar'
);

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';

and

$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 'cotlangcp.py' 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 cotlangcp.py 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 cotlangcp.py 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 cotlangcp.py this way:

python cotlangcp.py ~/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 https://www.transifex.com/projects/p/cotonti/.

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 cotlangcp.py ~/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 cotlangcp.py tool:

python cotlangcp.py ~/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
cotlangcp.py # modify or copy updated files
tx push -t # push your updated translation

1. Fox  2013-03-14 18:27

Thanks: 0

На Русском можна??? Спасибо!!!

Total: 1, on page: 1

Only registered users can post new comments