================
Translating CKAN
================

CKAN is used in many countries, and adding a new language to the web interface is a simple process.

CKAN uses the url to determine which language is used. An example would be ``/fr/dataset`` would be shown in french.  If CKAN is running under a directory then an example would be ``/root/fr/dataset``.  For custom paths check the :ref:`ckan.root_path` config option.

.. seealso::

   Developers, see :doc:`string-i18n` for how to mark strings for translation in
   CKAN code.

.. Note: Storing metadata field values in more than one language is a separate topic. This is achieved by storing the translations in extra fields. A custom dataset form and dataset display template are recommended. Ask the CKAN team for more information.

-------------------
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 the default language simply by setting the ``ckan.locale_default`` option in your CKAN config file, as described in :ref:`internationalisation-settings`. For example, to switch to German::

 ckan.locale_default=de

.. seealso::

   :ref:`internationalisation-settings`

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 or improving an existing translation
----------------------------------------------------------

If you want to add an entirely new language to CKAN or update an existing translation, you have two options.

* :ref:`i18n-transifex`. Creating or updating translation files using Transifex, the open source translation software. To add a language you need to request it from the Transifex dashboard: https://www.transifex.com/okfn/ckan/dashboard/ Alternatively to update an existing language you need to request to join the appropriate CKAN language team. If you don't hear back from the CKAN administrators, contact them via the ckan-dev list.
* :ref:`i18n-manual`. Creating translation files manually in your own branch.

.. note:: If you choose not to contribute your translation back via Transifex then you must ensure you make it public in another way, as per the requirements of CKAN's AGPL license.

.. _i18n-transifex:


Transifex setup
===============

Transifex, 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.com/okfn/ckan/content/

When leading up to a CKAN release, the strings are loaded onto Transifex and ckan-dev list is emailed to encourage translation work. When the release is done, the latest translations on Transifex are checked back into CKAN.


Transifex administration
------------------------

The Transifex workflow is described in the :doc:`release-process`


.. _i18n-manual:

Manual setup
============

.. note:: Please keep the CKAN core developers aware of new languages created in this way.

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``.

1. Preparation
--------------

This tutorial assumes you've got ckan installed as source in a virtualenv. Activate the virtualenv and cd to the ckan directory:

   .. parsed-literal::

       |activate|
       cd |virtualenv|/src/ckan

2. Install Babel
----------------

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

 pip install --upgrade Babel

3. Create a 'po' file for your language
---------------------------------------

Then create a translation file for your language (a po file) using the pot file (containing all the English strings)::

 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 <https://docs.pylonsproject.org/projects/pylons-webframework/en/latest/i18n.html#back-to-work>`_.

We recommend using a translation tool, such as `poedit <http://www.poedit.net/>`_, to check the syntax is correct. There are also extensions for editors such as emacs.

3. Commit the translation
-------------------------

When the po is complete, create a branch in your source, then commit it to your own fork of the CKAN repo::

 git add ckan/i18n/YOUR_LANGUAGE/LC_MESSAGES/ckan.po
 git commit -m '[i18n]: New language po added: YOUR_LANGUAGE' ckan/i18n/YOUR_LANGUAGE/LC_MESSAGES/ckan.po

NB it is not appropriate to do a Pull Request to the main ckan repo, since that takes its translations from Transifex.

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 to your CKAN server.

Once you have a compiled translation file, copy it to your host:

   .. parsed-literal::

       scp ckan.mo |virtualenv|/src/ckan/ckan/i18n/hu/LC_MESSAGES/ckan.mo

Adjust the path if you did not use the default location. This example is for language ``hu``.

6. Configure the language
-------------------------

Finally, once the mo file is in place, you can switch between the installed languages using the ``ckan.locale`` option in the CKAN config file, as described in :ref:`internationalisation-settings`.

------------------------------
Translations management policy
------------------------------

One of the aims of CKAN is to be accessible to the greatest number of users.
Translating the user interface to as many languages as possible plays a huge
part in this, and users are encouraged to contribute to the existing
translations or submit a new one. At the same time we need to ensure the
stability between CKAN releases, so the following guidelines apply when
managing translations:

* About 3 weeks before a CKAN release, CKAN is branched, and the English
  strings are frozen, and an announcement is made on ckan-dev to call for
  translation work. They are given 2 weeks to translate any new strings in this
  release.

* During this period, translation is done on a 'resource' on Transifex which is
  named to match the new CKAN version. It has been created as a copy of the
  next most recent resource, so any new languages create or other updates done
  on Transifex since the last release automatically go into the new release.
