Internationalize CKAN

CKAN is used in many countries, and adding a new language is a simple process.

Supported Languages

CKAN already supports numerous languages. To check whether your language is supported, look in the source at ckan/i18n for translation files. Languages are named using two-letter ISO language codes (e.g. es, de).

If your language is present, you can switch language simply by setting the lang option in your CKAN config file, as described in Internationalisation Settings. For example, to switch to German:

lang=de

If your language is not supported yet, the remainder of this section section provides instructions on how to prepare a translation file and add it to CKAN.

Adding a New Language

If you want to add an entirely new language to CKAN, you have two options.

  • Manual Setup. Creating translation files manually.
  • Transifex Setup. Creating translation files using Transifex, the open source translation software.

Manual Setup

If you prefer not to use Transifex, you can create translation files manually.

All the English strings in CKAN are extracted into the ckan.pot file, which can be found in ckan/i18n.

Note

For information, the pot file was created with the babel command python setup.py extract_messages.

0. Install Babel

You need Python’s babel library (Debian package python-pybabel). Install it as follows with pip:

pip -E pyenv install babel

1. Create a ‘po’ File for Your Language

First, grab the CKAN i18n repository:

hg clone http://bitbucket.org/bboissin/ckan-i18n/

Then create a translation file for your language (a po file) using the pot file:

python setup.py init_catalog --locale YOUR_LANGUAGE

Replace YOUR_LANGUAGE with the two-letter ISO language code (e.g. es, de).

In future, when the pot file is updated, you can update the strings in your po file, while preserving your po edits, by doing:

python setup.py update_catalog --locale YOUR-LANGUAGE

2. Do the Translation

Edit the po file and translate the strings. For more information on how to do this, see the Pylons book.

We recommend using a translation tool, such as poedit, to check the syntax is correct. There are also extensions for editors such as emacs.

3. Commit the Translation

When the po is complete, commit it to the CKAN i18n repo:

hg add ckan/i18n/YOUR_LANGUAGE/LC_MESSAGES/ckan.po
hg ci -m '[i18n]: New language po added: YOUR_LANGUAGE' ckan/i18n/YOUR_LANGUAGE/LC_MESSAGES/ckan.po
hg push

Note

You need to be given credentials to do this - to request these, contact the ckan-discuss list.

4. Compile a Translation

Once you have created a translation (either with Transifex or manually) you can build the po file into a mo file, ready for deployment.

With either method of creating the po file, it should be found in the CKAN i18n repository: ckan/i18n/YOUR_LANGUAGE/LC_MESSAGES/ckan.po

In this repo, compile the po file like this:

python setup.py compile_catalog --locale YOUR_LANGUAGE

As before, replace YOUR_LANGUAGE with your language short code, e.g. es, de.

This will result in a binary ‘mo’ file of your translation at ckan/i18n/YOUR_LANGUAGE/LC_MESSAGES/ckan.mo.

5. (optional) Deploy the Translation

This section explains how to deploy your translation automatically to your host, if you are using a remote host.

It assumes a standard layout on the server (you may want to check before you upload!) and that you are deploying to hu.ckan.net for language hu.

Once you have a compiled translation file, for automated deployment to your host do:

fab config_0:hu.ckan.net upload_i18n:hu

See the config_0 options if more configuration is needed e.g. of host or location.

Alternatively, if you do not want to use fab, you can just scp:

scp ckan.mo /home/okfn/var/srvc/hu.ckan.net/pyenv/src/ckan/ckan/i18n/hu/LC_MESSAGES/ckan.mo

6. Configure the Language

Finally, once the mo file is in place, you can switch between the installed languages using the lang option in the CKAN config file, as described in Internationalisation Settings.

Transifex Setup

Transifxes, the open translation platform, provides a simple web interface for writing translations and is widely used for CKAN internationalization.

Using Transifex makes it easier to handle collaboration, with an online editor that makes the process more accessible.

Existing CKAN translation projects can be found at: https://www.transifex.net/projects/p/ckan/teams/

Updated translations are automatically pushed to https://bitbucket.org/bboissin/ckan-i18n and these can be compiled and placed on CKAN servers by the server administrators.

Transifex Administration

The Transifex workflow is as follows:

  • Install transifex command-line utilities
  • tx init in CKAN to connect to Transifex
  • Run python setup.py extract_messages on the CKAN source
  • Upload the local .pot file via command-line tx push
  • Get people to complete translations on Transifex
  • Pull locale .po files via tx pull
  • python setup.py compile_catalog
  • Commit and push po and mo files