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.