Restartless Firefox Add-ons, Part 4: Localization (l10n)

Alright, part four has been a long time coming, but I finally got around to typing out an localization include for restartless Firefox 4 addons which I'm ready to talk about. If you haven't read part 2 it's all about how to use includes, so read it first, if you don't know what a restartless addon is, then start with part 1.

To start off with I wrote this include for Restartless Restart, and I consider that to be my demo.

Overview

Alright, so you should know how to use includes in a restartless addon now, and I shouldn't have to explain why localizing your addon is important, and you have an example; here are some notes:

To begin with you will need to copy this l10n.js file in to your addon, then include it at startup (in your addons bootstrap.js file) and create the all important underscore function (literally "_(aKey)"), like so:

Setup

So the example above assumes that you copied the l10n.js into a includes/ subdirectory, and that "filename.properties" is the name of the files within a /locale/en-US/ subdirectory for example, so the path to the english (US) translation for the text in your addon would be "/locale/en-US/filename.properties" (I would recommend using something other than "filename"). After l10n() is called it will create (and return) a global function named "_", which can be used to obtain the appropriate localized text. The 3rd parameter for l10n is the default locale that should be used when all other attempts fail. A failed attempted could be caused by a missing locale file (say you haven't yet translated your addon for the user's locale for instance), or the locale file could exist but not have the requested key, or the key could exist but be blank.

Using _

_ takes 2 arguments aKey, and aLocale which is optional.

aKey is the key for the text in your .properties file.

aLocale allows you to attempt to grab a specific translation before trying to get a translation from the user's locale, and lastly trying the default locale specified by the addon developer in the l10n call above (if that 3rd argument of l10n isn't provided then "en" is used). I use this in Restartless Restart to provide the user with the ability to override their browser's locale and get another translation. So I use the ja-JP translation for Restartless Restart on my Firefox profiles these days just because.

Conclusion

If you have a restartless addon, and you haven't localized it yet, then get to it!