Translations and localisation

You are here: Home · Developing Bika LIMS · Translations and Localisation

---

Table of Contents

1. Translating strings in Python code
2. Translating strings in javascript code
3. Dates and Times
4. Variable Substitutions
5. Overriding Translations

---

The excellent Plone documentation.

Translating strings in Python code

In most python code, just using a MessageFactory is sufficient:

message = _("Some string to be translated")

The MessageFactory does not actually translate anything though. That is normally handled by TAL, or some other utility such as plone_utils.addPortalMessage().

In the case of strings that are being rendered by code outside of Plone (eg, sending an email, writing a text file), the translation must be done manually:

translated_string = context.translate(message)

To prevent encoding errors, all values in the mapping parameter passed to the MessageFactory must be encoded as UTF-8:

title = to_utf8(value)
message = _("The title is: ${title}", mapping={"title":title})

There is a small utility t in the bika.lims.utils package for obtaining correctly translated, utf-8 encooded strings:

from bika.lims.utils import t
translated = t(_("Some english string"))

Translating strings in javascript code

Bika uses jarn.jsi18n to translate values in javascript files.

Strings from Javascript files need to be added in bika-custom.pot - they will not be recognised automatically by i18ndude's scanner.

Dates and Times

There are four msgid's in the that need to be overridden to set the Date and Time formats: These messages most probably should be kept translated uniformly across the plone and bika domains.

#. The variables used here are the same as used in the strftime formating.
#. Supported are ${A}, ${a}, ${B}, ${b}, ${H}, ${I}, ${m}, ${d}, ${M}, ${p},
#. ${S}, ${Y}, ${y}, ${Z}, each used as variable in the msgstr.
#. In english speaking countries default is: ${b} ${d}, ${Y} ${I}:${M} ${p}
msgid "date_format_long"
msgstr "${Y}-${m}-${d} ${I}:${M} ${p}"

#. The variables used here are the same as used in the strftime formating.
#. Supported are ${A}, ${a}, ${B}, ${b}, ${H}, ${I}, ${m}, ${d}, ${M}, ${p},
#. ${S}, ${Y}, ${y}, ${Z}, each used as variable in the msgstr.
#. In english speaking countries default is: ${b} ${d}, ${Y}
msgid "date_format_short"
msgstr "${Y}-${m}-${d}"

#. The variables used here are the same as used in the strftime formating.
#. Supported are ${A}, ${a}, ${B}, ${b}, ${H}, ${I}, ${m}, ${d}, ${M}, ${p},
#. ${S}, ${Y}, ${y}, ${Z}, each used as variable in the msgstr.
#. In english speaking countries default is: ${I}:${M} ${p}
#: ./TranslationServiceTool.py
msgid "time_format"
msgstr "${I}:${M} ${p}"

#. Date format used with the datepicker jqueryui plugin.
# The variables used here are **NOT** the same as the strftime formatting.  They are taken from the jqueryui datepicker widget's readme, and the available strings are: 'dd', 'mm', 'yy', '-', '/', and '.'
#. Default: "mm/dd/yy"
msgid "date_format_short_datepicker"
msgstr "yy-mm-dd"

Variable Substitutions

Variable substitutions in messages that passed to the _() calls (in both Python and Javascript), are done with the gettext-style ${} substitution. Don't use string concatenation, "%s" or "".format to create these strings, the message translation will not work.

Python:

from bika.lims import bikaMessageFactory as _
from bika.lims.utils import t
mapping = {"number": 5}
final = t(_("There are ${number} things.", mapping=mapping)

Javascript:

window.jarn.i18n.loadCatalog("bika");
var _ = window.jarn.i18n.MessageFactory("bika");   
var mapping = {number: 5};
var final = _("There are ${number} things.", mapping);

Overriding translations

Simple instructions for changing defaults or overriding translations for text strings. This is documented lots elsewhere, but simple step-by-step instructions are also good. If you are fixing something you think could be improved in the core translations, please consider opening a bug report or pull request instead.

1: Install Plone.

You will also need to install some or all of the dependencies listed in the Bika installation guide, depending on what you are going to get up to.

2. Run development buildout

bin/buildout -c develop.cfg

In Plone-4.3.2 I had to add 'ExtensionClass >= 4.1a1' to [versions], because buildout will not automatically download versions that look like pre-releases, seemingly even when a package depends on this version.

3. Create a new python package

cd src/
../bin/zopeskel basic_namespace test.package

4. Create translation content

Add language folders for all languages that you want to override.

mkdir -p test.package/test/package/locales/en/LC_MESSAGES

You should download the relevant po files from Github and place it inside your new language folders.

Some strings are translated in the bika domain, some strings are translated in the plone domain, and others are actually present in both, so as to be translated in different areas of the site.

You can edit the files with a normal text editor. I use poedit:

sudo apt-get install poedit
poedit test.package/test/package/locales/en/LC_MESSAGES/bika.po

5. Add the required zcml snippet

In test.package/test/package/configure.zcml:

<configure xmlns:i18n="http://namespaces.zope.org/i18n"
           i18n_domain="my.package">
    <i18n:registerTranslations directory="locales" />
</configure>

6. Add test.package to the eggs, develop and zcml parts of buildout.cfg

My entire buildout.cfg looks like this so far:

[extends]

buildout-original.cfg

eggs +=
    bika.lims
    test.package

develop +=
    src/test.packagen

zcml += 
    test.package

7. Run buildout, and we're done.

bin/buildout
bin/plonectl restart