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
| (5 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 98: | Line 98: | ||
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. | 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. | |||