Labs/Ubiquity/Ubiquity 0.5 Command Localization Tutorial

Introduction

Ubiquity 0.5 adds the ability to localize commands bundled with Ubiquity and, in addition, lays the foundation for the future localization of community commands. The "localization of Ubiquity commands" involves the translation of verb names, description and help strings, and message and interface strings in the commands' preview and execute codes.

For information on the localization of the Ubiquity Parser—i.e., teaching Ubiquity the grammar of your language—please read this tutorial. In general, localizing the Parser is a prerequisite to the localization of individual commands.

Gettext and the po format

Ubiquity command localization follows the po (portable object) format of the GNU gettext system. po is a de facto standard in the world of localization, particularly in the UNIX world, and is supported by a variety of different tools and editors.

Like most types of localization, Ubiquity command localization works essentially by replacing strings. The original commands are written without regard for other languages, as long as they follow certain guidelines to keep the command localizable. The commands are written with strings in a set source language and, through the process of localization, Ubiquity will go through and replace those source language strings with the target language equivalents. In the case of Ubiquity's built-in commands, the source language is always English.

Here is one translation entry from a Ubiquity command's po file:

 msgctxt "twitter.execute"
 msgid "direct message sent"
 msgstr "ダイレクトメッセージを送信しました。"

Every* Ubiquity translation entry consists of these three parts:

1. msgctxt, the message context. This is a structured string which tells you which command's string this is, and which aspect of the command's behavior it is related to. Here, this translation entry is from the execute code of the twitter command.
2. msgid, the message id. This is the original text in the source language, so you know exactly what content needs to be translated. This must exactly match the localized string in the command code.
3. msgstr, the message string. This is the localized string in the target language, here Japanese. As expected, the msgstr above says "direct message was sent" in Japanese.

* almost every - see "shared keys" below.

Ubiquity's localization files for built-in commands are all stored in a central directory, and are organized by command feed. For example, the localization of the firefox.js command feed must be called firefox.po and is placed in the directory ubiquity/localization/XX/, where XX is your language's language code. For example, the Danish localization file for firefox.js would be stored as ubiquity/localization/da/firefox.po.

po files may be translated in a text editor or in specialized localization software. Some free tools include poEdit and Translate Toolkit. All Ubiquity po files are in UTF8 encoding. Traditional Gettext also uses a binary format called mo (machine object) but Ubiquity only uses po files.

Localization templates

po localizations are often started based on a po template or pot file. These templates are simply po</code files with all blank msgstr's.

Ubiquity includes a handy localization template tool to create these initial templates for you. Just go to the Ubiquity command list, and click on the "get localization template" link next to a command feed. If no such link is showing up, it means that that feed was not bundled with Ubiquity and thus does not currently support localization.

You can also get many of the pot files pre-generated from the Ubiquity hg repository. If you already get your Ubiquity from the source, you'll find the templates in ubiquity/localization/templates. Else, you can get them from our hg server.

When you start working on a localization, make sure to add your contact and credit information to the header. Each Ubiquity po file begins with a header that looks like this:

 # social.po
 #
 # Localizers:
 # Masahiko Imanaka <test@yahoo.co.jp>

This is from the Japanese po file for social.js, social.po. You'll see a line called "Localizers:". Add a new line (or replace the dummy line) below that and add your name, followed by your email address in <braces>.

Please note that these automatically generated localization templates are not perfect. For technical reasons, there are often a handful of localizable strings which do not get automatically added into the template. When you notice these, you can simply duplicate one of the msgctxt-msgid-msgstr entries and fill in the appropriate details. This will often require that you take a look at the original command feed's source.

Examples

Formatting templates