
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' (only use xx_YY locale notation if YY is not uppercase xx).
We assume the plugin has already been i18n-ized and has an i18n directory already.

There are currently 3 ways to translate a plugin:

- using Launchpad's Rosetta_
- using Babel_ and gettext
- using only the gettext tools suite 


Using Launchpad's Rosetta_
-------------------------

This is the recommended approach as it greatly simplifies the whole process.
All core Moovida plugins are handled in Rosetta. To start translating,
simply log in to Rosetta_, set your languages in your profile,
select the plugin you want to translate and that's it! We'll pick up new
translations as soon as possible.


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 \
    --output i18n/fr.po --locale fr

This will create a i18n/fr.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 locale:

::

  $ cd elisa-plugins/elisa/plugins/myplugin
  $ mkdir -p i18n/fr/LC_MESSAGES
  $ PYTHONPATH=../../../../elisa-core/ python setup.py po_compile \
    --input i18n/fr.po --locale 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/elisa-plugin-myplugin.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 \
    --output i18n/fr.po --locale 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
  $ msginit --input i18n/elisa-plugin-myplugin.pot \
    --locale fr -o i18n/fr.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 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/
.. _Rosetta: http://translations.launchpad.net/elisa/1.0