Internationalizing a plugin
===========================

This document explains to the plugin developer how to convert the
strings of the plugin meant to be displayed in the UI to translatable
strings. It also explains how to extract these strings to a PO
template, reusable later on by translators.

We assume the developer uses Linux and has a basic understanding of
the classic shell commands.

i18n package preparation
------------------------

Go in your plugin directory and create an empty i18n python package:

::

  cd elisa-plugins/elisa/plugins/myplugin
  mkdir i18n
  touch i18n/__init__.py

This package will contain:

- the .pot file
- the .po and .mo files of each translation of the plugin

Edit your setup.py file, in the setup() function, update (or add) the
package_data parameter like shown below:

::

  setup(name='elisa-plugin-myplugin',
        ...
        package_data={'elisa.plugins.myplugin.i18n':
                      ['*.po', '*.pot'],
                     },
        ...)

Hence, the plugin tarball will contain the .po files supplied by the
translators and the .pot template.


Initial generation of the elisa-plugin-myplugin.pot file
--------------------------------------------------------

Go in your plugin directory and create the i18n/messages.pot file:

cd elisa-plugins/elisa/plugins/myplugin

Using Babel ::

  Check that you have the setup.cfg file similar to the one in
  elisa/plugins/skeleton/basic and that you have updated it with
  your plugin name and run

  PYTHONPATH=../../../../elisa-core python setup.py pot_update

Using PyGettext ::

  pygettext -v -p i18n -d elisa-plugin-myplugin `find . -name "*.py"`

Using GNU gettext ::

  xgettext --language=python --default-domain=elisa-plugin-myplugin \
           --output=i18n/elisa-plugin-myplugin.pot `find -name "*.py"`

That's it! Translators can now reuse the elisa-plugin-myplugin.pot template to
start new translations of the plugin. See the
elisa-core/docs/localisation.txt document about that.

Every time the developer adds/updates translatable strings in their
code, the .pot template should be updated, at least.


Easy translation using Launchpad's Rosetta_
-------------------------------------------

Launchpad has a great tool to allow translations of your own project called
Rosetta_. If you followed the above instructions and have a project registered
on Launchpad you can easily set it up for translations and automatic imports
from Bazaar branches. Rosetta will then pick up all changes to translation
templates and you'll only need download new translations and commit them to
your branch from time to time.

.. _Rosetta: http://translations.launchpad.net/