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':
                      ['*/LC_MESSAGES/*.po', '*.pot'],
                     },
        ...)

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


Initial generation of the messages.pot file
-------------------------------------------

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

::

  cd elisa-plugins/elisa/plugins/myplugin
  pygettext -v -p i18n `find . -name "*.py"`

That's it! Translators can now reuse the messages.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.
