308
edits
Labs/Ubiquity/Ubiquity 0.5 Command Localization Tutorial: Difference between revisions
Labs/Ubiquity/Ubiquity 0.5 Command Localization Tutorial (view source)
Revision as of 01:40, 26 June 2009
, 26 June 2009→Testing your localizations
| (9 intermediate revisions by the same user not shown) | |||
| Line 25: | Line 25: | ||
<small>* almost every - see "shared keys" below.</small> | <small>* almost every - see "shared keys" below.</small> | ||
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 <code>firefox.js</code> command feed must be called <code>firefox.po</code> and is placed in the directory <code>ubiquity/localization/XX/</code>, where <code>XX</code> is your language's language code. For example, the Danish localization file for <code>firefox.js</code> would be stored as <code>ubiquity/localization/da/firefox.po</code>. | 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 <code>firefox.js</code> command feed must be called <code>firefox.po</code> and is placed in the directory <code>ubiquity/localization/XX/</code>, where <code>XX</code> is your language's language code. For example, the Danish localization file for <code>firefox.js</code> would be stored as <code>ubiquity/localization/da/firefox.po</code>. (For more information, see the "Testing your localization" section below.) | ||
<code>po</code> files may be translated in a text editor or in specialized localization software. Some free tools include [http://www.poedit.net/ poEdit] and [http://en.wikipedia.org/wiki/Translate_Toolkit Translate Toolkit]. All Ubiquity <code>po</code> files are in UTF8 encoding. Traditional Gettext also uses a binary format called <code>mo</code> (machine object) but Ubiquity only uses <code>po</code> files. | <code>po</code> files may be translated in a text editor or in specialized localization software. Some free tools include [http://www.poedit.net/ poEdit] and [http://en.wikipedia.org/wiki/Translate_Toolkit Translate Toolkit]. All Ubiquity <code>po</code> files are in UTF8 encoding. Traditional Gettext also uses a binary format called <code>mo</code> (machine object) but Ubiquity only uses <code>po</code> files. | ||
| Line 31: | Line 31: | ||
== Localization templates == | == Localization templates == | ||
<code>po</code> localizations are often started based on a <code>po</code> template or <code>pot</code> file. These templates are simply <code>po</code files with all blank <code>msgstr</code>'s. | <code>po</code> localizations are often started based on a <code>po</code> template or <code>pot</code> file. These templates are simply <code>po</code> files with all blank <code>msgstr</code>'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. | 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. | ||
| Line 42: | Line 42: | ||
# | # | ||
# Localizers: | # Localizers: | ||
# Masahiko Imanaka < | # Masahiko Imanaka <test@yahoo.co.jp> | ||
This is from the Japanese <code>po</code> file for <code>social.js</code>, <code>social.po</code>. 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>. | This is from the Japanese <code>po</code> file for <code>social.js</code>, <code>social.po</code>. 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 <code>msgctxt</code>-<code>msgid</code>-<code>msgstr</code> entries and fill in the appropriate details. This will often require that you take a look at the original command feed's source. | |||
== | == Examples and special cases == | ||
=== Two types of strings === | |||
There are, broadly speaking, two types of translation entries in Ubiquity command localization: '''properties''' and '''inline strings'''. | |||
==== Properties ==== | |||
'''Properties''' are metadata about the command that are in individual properties of command objects. Localizable properties include <code>names</code>, <code>help</code>, and <code>description</code>. As each command only has one each of these properties, there is only one <code>msgcntxt</code> of each kind. For example, a command like <code>twitter</code> would never have two different <code>twitter.names</code> localization entries. Even though it is logically somewhat redundant, these property entries still need to keep both their <code>msgctxt</code> and their <code>msgid</code>'s to function properly. | |||
Note in particular that the <code>names</code> translation may be a plurality of names, not just one. In this case, use the pipe (|) character to delimit the names: | |||
#. twitter command: | |||
#. use | to separate multiple name values: | |||
msgctxt "twitter.names" | |||
msgid "twitter|tweet|share using twitter" | |||
msgstr "呟く|呟いて|呟け|つぶやく|つぶやいて|つぶやけ|twitter|tweet" | |||
==== Inline strings ==== | |||
Inline strings are those strings which are used in a command's <code>preview</code> or <code>execute</code> methods. As such, they always have <code>msgctxt</code> of "command name<code>.preview</code>" or "command name<code>.execute</code>". As there may be many different localizable strings in each of these methods, there can be multiple different translation entries in commands with this same <code>msgctxt</code> but they will each have unique <code>msgid</code>'s. | |||
=== Multiline strings === | |||
Often the strings to localize—and their localizations—will be multiple lines long. In this case, the <code>po</code> format offers a special syntax to deal with such line breaks: | |||
msgctxt "digg.description" | |||
msgid "If not yet submitted, submits the page to Digg.\n" | |||
"Otherwise, it takes you to the story's Digg page." | |||
msgstr "このページを Digg にたれこみます。\n" | |||
"または該当する Digg ページを開きます。" | |||
The convention here is that if a line begins with a quote ("), it is the continuation of the line before it. In this case, newline characters (encoded <code>\n</code>) are not automatically inserted, so a <code>\n</code> must be inserted at the end of the line to mark that there is a newline there. Note that the <code>msgid</code> must match what is in the source code exactly, so it is best to leave the <code>msgid</code>'s as they are in the templates. | |||
<small>There is a [https://ubiquity.mozilla.com/trac/ticket/769 known bug] in Ubiquity 0.5 preventing these multi-line keys from being properly dealt with.</small> | |||
=== Shared keys === | |||
In some situations, a command author will write some shared code which is executed as part of the command's <code>preview</code> and <code>execute</code> or even between commands. | |||
In this special case, as it would be redundant to write the exact same translation entry twice for both <code>preview</code> and <code>execute</code> contexts, you can ''optionally'' make do without the msgctxt: | |||
# no message context | |||
msgid "original message" | |||
msgstr "translation" | |||
By not specifying a context, this same translation entry can be shared across any instance of the string "original message" in any <code>preview</code> or <code>execute</code> string in any command in that feed. You cannot, however, use shared keys to share translations between command feeds. | |||
Note however that there are instances in some languages where you would actually want to localize the two contexts' strings separately: for example, suppose the source language does not mark tense or aspect, but your target language does. A status message in that language may be the same in cases where the action is about to be done (in the <code>preview</code>) and when it was completed (in the <code>execute</code>) and you would thus want to translate these strings differently in the different (future/past) contexts. | |||
=== Localizing formatting templates === | |||
Localizable strings will often contain variable references and other code in {curly braces}, following the [http://code.google.com/p/trimpath/wiki/JavaScriptTemplates JavaScript Templates] format. For example, you may see a string like this: | |||
msgid "${number} results found." | |||
In these cases, the <code>${number}</code> is going to be replaced out by some data, so you will want to leave it alone in your localization, for example (French): | |||
msgstr "Il y a ${number} résultats." | |||
JavaScript templates can also include some basic control structures, most importantly letting you handle pluralization directly in the . Suppose you want your localized string to display slightly differently depending on whether the <code>number</code> value is singular or plural. The JavaScript Templates format allows for a simple <code>{if}</code> statement to handle these possibilities: | |||
msgstr "Il y a ${number} résultat{if number > 1}s{/if}." | |||
This string will produce "Il y a 3 résultat'''s'''." when plural and "Il y a 1 résultat." when singular as we would like. You can also write an <code>{else}</code> condition, using the pattern | |||
{if ...} ... {else} ... {/if} | |||
Alternatively, suppose the source language includes such special syntax for pluralization, but your language does not have plural marking. You can simply remove the <code>{if}...</code> control structure from the localized string. | |||
msgid "${number} result{if number > 1}s{/if} found." | |||
msgstr "找到${number}個結果" | |||
== Testing your localizations == | |||
Manual testing is an important step in preparing your localizations. Testing requires you to place your <code>po</code> files in a specific language directory in your Ubiquity source folder. Where this folder is depends on how you obtained Ubiquity: | |||
* '''for Ubiquity installs via xpi (addons.mozilla.com):''' | |||
**If you installed Ubiquity via a packaged xpi, such as from addons.mozilla.com or from the "Add-ons" menu item in Firefox, your Ubiquity folder is in your Firefox profile. [http://support.mozilla.com/en-US/kb/Profiles This support tutorial] will tell you where to find your Firefox profile. Within your profile drill down to <code>extensions/ubiquity@labs.mozilla.com/</code>. This is your Ubiquity source folder. | |||
* '''for Ubiquity installs from hg:''' | |||
** If you pulled the Ubiquity source from our hg repository and installed it using the <code>manage.py</code> utility, you will find the Ubiquity source folder, <code>ubiquity</code> right in the root level of the repository. | |||
Once you've found your Ubiquity source directory, you want to find your language's directory at <code>localizations/XX/</code> where XX is your language code. If the directory doesn't exist, you can make it. Place your <code>po</code> files there. | |||
Finally, go to the Ubiquity settings page and make sure it's set to use your language (if you haven't already).* Restart to test out your localizations. | |||
<small>* currently there's no way to test localizations for languages which do not yet have parsers for them. Read [[Labs/Ubiquity/Parser_2/Localization_Tutorial|this tutorial]] to learn more about how to write parser language settings for your language.</small> | |||
== Contributing your localizations == | |||
Currently the latest versions of Ubiquity built-in command localizations are kept in Ubiquity's main [https://ubiquity.mozilla.com/hg/ubiquity-firefox/ hg repository]. You can sumbit new localizations by posting them on [https://ubiquity.mozilla.com/trac/ticket/712 this trac ticket]. | |||
You can also ask questions and seek help on Ubiquity localization on the [http://groups.google.com/group/ubiquity-i18n The Ubiquity i18n Google Group]. | |||
== References == | |||
* [[Labs/Ubiquity/i18n]], the Ubiquity i18n project wiki page | |||
* [http://groups.google.com/group/ubiquity-i18n The Ubiquity i18n Google Group], a mailing list to discuss Ubiquity internationalization and localization | |||
* [[Labs/Ubiquity/Ubiquity_0.5_Making_Commands_Localizable|Making commands localizable]], a guide for command authors | |||
* [[Labs/Ubiquity/Parser_2/Localization_Tutorial|Parser 2 localization tutorial]], how to actually teach Ubiquity the grammar of your language | |||
* [http://www.gnu.org/software/gettext/manual/gettext.html The GNU gettext manual] | |||
* [http://jsgettext.berlios.de/ JS Gettext], the open source JavaScript library chosen to incorporate <code>po</code> file handling in Ubiquity. | |||