
Localising a plugin
===================

This example explains how to make a new translation for the existing
plugin 'elisa-plugin-myplugin'. The language we want to translate into
is French 'fr_FR'. We assume the plugin has already been i18n-ized and
has an i18n directory already.

There are currently 2 ways to translate a plugin:

- using Babel_ and gettext
- using only the gettext tools suite


Using Babel
-----------

Create a new po file
++++++++++++++++++++

Go in the plugin directory and initialize a new catalog for the
locale:

::

  $ cd elisa-plugins/elisa/plugins/myplugin
  $ PYTHONPATH=../../../../elisa-core/ python setup.py init_catalog --locale fr_FR

This will create a i18n/fr_FR/LC_MESSAGES/elisa-plugin-myplugin.po
file. You can use a tool like gstranslator_ to translate the strings
inside, or do it manually.

Compile the po file to a mo file
++++++++++++++++++++++++++++++++

Go in the plugin directory and compile the catalog previously created
for the fr_FR locale:

::

  $ cd elisa-plugins/elisa/plugins/myplugin
  $ PYTHONPATH=../../../../elisa-core/ python setup.py po_compile --locale fr_FR

If the --locale argument is not supplied, Babel will compile all the
.po files it will be able to find in the current directory.

Update the po file
++++++++++++++++++

If the Plugin developers add new strings to translate in their code,
it is their responsability to update the po template file, usually
located in i18n/messages.pot.

If the po template file has been updated, the po files needs to be
updated too, so that the translator is able to translated the added
strings:

::

  $ cd elisa-plugins/elisa/plugins/myplugin
  $ PYTHONPATH=../../../../elisa-core/ python setup.py update_catalog --locale fr_FR


If the --locale argument is not supplied, Babel will update all the
.po files it will be able to find in the current directory.

Once new strings have been translated, the po file can be compiled to
a mo file as described in the `Compile the po file to a mo file`_
section.

With gettext only
-----------------


Starting your translation file
++++++++++++++++++++++++++++++

Go into i18n and do this to start a new translation file for
french (fra):

::

  $ cd elisa-plugins/elisa/plugins/myplugin
  $ mkdir -p i18n/fr_FR/LC_MESSAGES
  $ msginit --input i18n/messages.pot --locale fr_FR -o i18n/fr_FR/LC_MESSAGES/elisa-plugin-myplugin.po

Now edit the elisa-plugin-myplugin.po file that was created. Don't
forget to edit the charset, normally change it to UTF-8.


Then you can use nice tools such as `gtranslator`_ to edit the updated
po file.


Compile the po file to a mo file
++++++++++++++++++++++++++++++++

Go in the plugin directory and compile the catalog previously created
for the fr_FR locale. This is a cross-platform procedure. 

::

  $ cd elisa-plugins/elisa/plugins/myplugin
  $ PYTHONPATH=../../../../elisa-core/ python setup.py -v build_po

If you are on Windows platform, the PYTHONPATH needs to be set like
this, we still suppose you are in the plugin directory:

::

  $ cd elisa-plugins\elisa\plugins\myplugin
  $ set PYTHONPATH=%PYTHONPATH%;..\..\..\..\elisa-core
  $ python setup.py -v build_po

The -v option has the effect to display on the console output what
files are compiled during the process.

.. _Babel: http://babel.edgewall.org
.. _gtranslator: http://gtranslator.sourceforge.net/
