We have a plugin with user facing pages; Now is the time to think about making it translatable. It’s best to think about this early in your development as it becomes increasingly difficult the longer you put it off.
Having a translation system setup when you start to implement your plugin will help you save time, and encourage people to contribute translations early!
Prerequisite
Koha added the functionality to pass the LANG
variable to plugin templates
with bug 25099
so translatable plugins are well supported since the release of 19.11.06.
The LANG
variable contains the code for the language that has been selected
by the logged in user. As such, your plugin can be aware of the language in
which the strings must be translated.
Setting up the translation system
The basic concept is to have different translated template files served by the plugin for each translated language.
We can use an include file to group all the translatable strings for ease of translation.
Start by creating one empty file Koha/Plugin/FancyPlugin/i18n/default.inc
and reference it from each of your templates as follows:
[% TRY %]
[% PROCESS "$PLUGIN_DIR/i18n/${LANG}.inc" %]
[% CATCH %]
[% PROCESS "$PLUGIN_DIR/i18n/default.inc" %]
[% END %]
Add new strings
Now add new “strings” to your template as [% T.your_string_code %]
and set
their default value in default.inc
:
[%
T = {
your_string_code = "This is an example string to translate",
}
%]
To add a translated language, simply add a new file for language you would like
to translate, for example Koha/Plugin/FancyPlugin/i18n/es-ES.inc
:
[%
T = {
your_string_code = "Esta es una cadena de ejemplo para traducir",
}
%]
And that’s it, you now have an es-ES translation!
This is a naive, but very easy, way to handle translation.
In the future we will provide a more robust solution based on gettext
, to
correctly deal with language problems like plural forms and context.
Going further
It can quickly become a challange to keep the list of strings in all the include files up-to-date with new strings.
There is a script that could be useful in the case your plugin is getting bigger, see the file fetch_po.js from an existing plugin.
It will need small adjustements to make it work however.