Improved add-on localisation (translation)

It’s a lot of work for both developers and translators to ensure that an add-on is correctly translated into multiple languages but it’s a vital task for any add-on or software that will be used outside of the developer’s home country.

We want KeeFox to be available in many more languages but the existing Firefox localisation system does not do as much as it could to help us reach this goal.

This post will outline the changes I’ve made in KeeFox 1.2 in order to improve the localisation architecture for KeeFox and explain how other browser add-ons could use the same approach.

As I see it, these are the main problems with the standard Firefox localisation system:

Duplication	There are two distinct sources of text. In order to display a particular word or sentence in more than one part of an add-on it is sometimes necessary for that text to be translated twice. This can lead to mistakes and confusion, not to mention the extra workload it places on translators. This duplication is not a problem for simple add-ons that are created using recent improvements in the add-on infrastructure but many complex add-ons like KeeFox can’t be re-written in this new way (for both technical reasons and the shear amount of time it would take).
Fragility	Every language must have every piece of text translated or the entire add-on fails to function. This places a huge burden on translators and in add-ons such as KeeFox where there are many thousands of words to translate it can be a daunting prospect to start a new translation. From a developer perspective, this limitation leads to much manual work before each release in order to ensure that only the correct and complete translations are pushed out to the add-on users. Thorough testing of this manual process is also difficult and laborious.
Rigidity	Translation updates can only occur when the add-on code is updated. Even a one character typo correction has to pass through the full Mozilla add-on review process which often takes several weeks and distracts their review team from more useful tasks. (Note: the review team does not actually look for text accuracy - it’s mainly a check for basic add-on security and functionality). This also causes other issues such as unnecessary update installations for existing users and delays to the release date due to either waiting on ill or otherwise absent translators or the amount of work required to re-integrate the latest locale information every time.

To begin addressing these challenges I’ve developed a new locale system for KeeFox 1.2. It’s implemented as a JavaScript module so should be easily transferable to any other add-on.

Main features

All locales are defined through .properties files.
XML DTD files are not needed, even for localisation of XUL.
If a translation for a particular string in the user’s current locale is not found, the “default” string will be displayed.
In keeping with Mozilla standards, the “default” locale is “en-US” (although this would be easy to change if required).
Locale definitions can be loaded after the application has started.

So this means

No more XML DTD files.
It works with existing Firefox property files.
It works with dynamically loaded JSON locale files.
It could work with existing Google Chrome JSON files:
- Simple “messages” will work provided they are supplied through JavaScript rather than a separate locale file on disk.
- Parameters won’t work yet (mainly because Chrome takes a different approach to parameter selection but also because it’s not been a priority for me to implement that feature yet).
- See developer.chrome.com/extensions/i18n-messages.html for more details on the format of locale that could be supported in future.

What this means for KeeFox translators

I’ll still be looking for 100% completion for each language included in the main KeeFox releases. The flexibility of the new system will provide protection against the mistakes that have previously caused entire countries to be unable to use KeeFox for several weeks.
Temporary exceptions to the “100% complete” rule can be arranged as required.
Translation can occur more independently of the release cycle of KeeFox.
Languages do not have to be completed in order to be included in beta releases. This should help separate the task of translation from the testing phase of a KeeFox release and allow new translators to get their work seen before the entire translation process has been completed.
The messages delivered by FAMS will continue to default to the existing English language and continue to be updated only when a KeeFox update occurs. Any translations added to the FAMS.keefox.properties file in Babelzilla will be included in the beta and final releases; 100% completion of this file is not required (although obviously I suspect that users will benefit if you can translate the whole lot).
If I ever get around to implementing the “dynamic delivery over the internet” for FAMS messages there could be rare ad-hoc translation work (e.g. translating a security warning message) but I’ll provide further information on that when required.

Remaining problems

Having to manually construct a call to internationaliseElements() in each XUL file is messy. It should be possible to change this so that elements to be translated can instead be tagged with a class (or similar).
Dynamic update delivery: The localisation architecture allows for instant updates from the internet but there is currently no infrastructure in place to deliver this.
Dynamic update tools: The localisation file format is simple (JSON) but the existing Babelzilla translation does not currently support it so a temporary workaround will be required.

If you want to address any of those limitations please feel free to fork KeeFox and submit a pull request with your improvements.

Hopefully Firefox will release improvements to the core localisation system one day which will address the limitations that led me to develop an alternative solution for KeeFox. In the mean time, I thought other add-on developers might be interested in this work - documentation on its use is here: https://github.com/luckyrat/KeeFox/wiki/en-|-Technical#wiki-locales