Firebug Localization

From FirebugWiki

(Difference between revisions)
Jump to: navigation, search
(Localization APIs)
m (Fixed code formatting)
(6 intermediate revisions not shown)
Line 1: Line 1:
-
== Localization ==
 
Firebug is using [http://www.babelzilla.org/ BabelZilla] (BZ) to utilize an existing community of localizers and get translation to various languages. This effort requires a process and Firebug developers should follow some rules that help to synchronize files coming from BZ to the development source tree.
Firebug is using [http://www.babelzilla.org/ BabelZilla] (BZ) to utilize an existing community of localizers and get translation to various languages. This effort requires a process and Firebug developers should follow some rules that help to synchronize files coming from BZ to the development source tree.
Line 9: Line 8:
* [http://www.babelzilla.org/index.php?option=com_wts&Itemid=203&type=show&extension=4387 Firebug Translations] (on BabelZilla)
* [http://www.babelzilla.org/index.php?option=com_wts&Itemid=203&type=show&extension=4387 Firebug Translations] (on BabelZilla)
* [http://developer.mozilla.org/En/XUL_Tutorial/Property_Files Property Files]
* [http://developer.mozilla.org/En/XUL_Tutorial/Property_Files Property Files]
 +
* [https://developer.mozilla.org/En/Localization_and_Plurals Plurals]
== Development Rules ==
== Development Rules ==
-
* FB developers should change only the en-US locale files, which stand like a
+
* Developers should only change the <code>en-US</code> locale files, which stand like a template for all other translated locales.
-
template for all other translated locales.
+
-
* If some string (its value) is changed, change also its key so, translators can see
+
* If some string (its value) is changed, change also its key, so translators can see there is something new to translate. (BZ doesn't recognize string changes.)
-
there is something new to translate.
+
-
* When updating from BZ, always get all translations (even for not released
+
* When updating from BZ, always get all translations (even for not released locales) from BZ before uploading new version. So no translation made since the last upload is lost. The only dir, which is *not* synced with BZ is <code>locale/en-US</code>.
-
locales) from BZ before uploading new version. So, no translation made since the last
+
-
upload is lost. The only dir, which is *not* synced with BZ is locale/en-US.
+
-
* Only ''*.properties'' files should be used for localization (Firebug doesn't want to use DTD files due a lack of script-ability)
+
* Only ''*.properties'' files should be used for localization. (Firebug doesn't want to use DTD files due a lack of script-ability.)
 +
 
 +
* Do not put an empty string into ''*.properties'' files.
== Naming Conventions ==
== Naming Conventions ==
-
Every string in ''*.properties'' file is identified by ID (a key). For example, following string is identified by ''net.Response_Header'' and it's value is set to ''net.Response Header''.
+
Every string in ''*.properties'' file is identified by ID (a key). For example, following string is identified by ''net.Response_Header'' and it's value is set to ''Response Header''.
-
<code>net.Response_Header=Response Header</code>
+
<source lang="properties">
 +
net.Response_Header=Response Header
 +
</source>
String IDs in Firebug use following naming rules:
String IDs in Firebug use following naming rules:
-
* The key is prefixed with lower case module name using the string (e.g. ''net'' or ''console'', ...)
+
* The key is prefixed with a lower case module name using the string (e.g. ''net'' or ''console'', ...).
-
* In case of many strings in one module you can use additional prefix to further group related strings. Again such prefix should be followed by a period.
+
* In case of many strings in one module you can use an additional prefix to further group related strings. Such a prefix should be followed by a period.
-
* The part after last period is used as the default value (with underscores replaced by spaces) in case the string is not available in the current locale.
+
* The part after the last period is used as the default value (with underscores replaced by spaces) in case the string is not available in the current locale.
See examples:
See examples:
 +
<source lang="javascript">
 +
$STR("net.Response Header");
 +
</source>
-
<code>$STR("net.Response Header");</code>
 
* key is: ''net.Response_Header''
* key is: ''net.Response_Header''
* default is: ''Response Header''
* default is: ''Response Header''
-
<code>$STR("net.timing.Request Time");</code>
+
<source lang="javascript">
 +
$STR("net.timing.Request Time");
 +
</source>
* key is: ''net.timing.Request_Time''
* key is: ''net.timing.Request_Time''
* default is: ''Request Time''
* default is: ''Request Time''
-
 
+
''HINT: In case a string is not translated for the current Firefox locale, the <code>en-US</code> locale is used as fallback. Note that the <code>en-US</code> locale must always define all strings.''
-
''Firebug 1.6 (beta) uses a new way how to deal with missing translations. In case when a string is not translated for the current Firefox locale, the en-US locale is used as fall-back (en-US translation is used instead). Note that en-US locale must always define all strings.''
+
== Localization APIs ==
== Localization APIs ==
-
There are several APIs that are be used to make Firebug code localizable.
+
There are several APIs that are used to make Firebug code localizable.
-
* $STR - localization of a static string.
+
* <code>$STR</code> - localization of a static string.
-
* $STRF - localization of a string with dynamically inserted values (see [https://developer.mozilla.org/En/XUL_Tutorial/Property_Files#Text_Formatting more]).
+
* <code>$STRF</code> - localization of a string with dynamically inserted values (see [https://developer.mozilla.org/En/XUL_Tutorial/Property_Files#Text_Formatting more]).
-
* $STRP - localization of a plural form.
+
* <code>$STRP</code> - localization of a plural form (see an [https://developer.mozilla.org/En/Localization_and_Plurals#Polish example]).
Some examples:
Some examples:
-
 
+
<source lang="javascript">
-
<pre class="code">
+
// Search for key "Label" within firebug *.properties files and returns its value.
// Search for key "Label" within firebug *.properties files and returns its value.
// If the key doesn't exist returns "Label".
// If the key doesn't exist returns "Label".
$STR("Label");
$STR("Label");
-
</pre>
+
</source>
-
<pre class="code">
+
<source lang="javascript">
// Search for key "Button_Label" within the firebug *.properties files.
// Search for key "Button_Label" within the firebug *.properties files.
// If the key doesn't exist returns "Button Label".
// If the key doesn't exist returns "Button Label".
$STR("Button Label");
$STR("Button Label");
-
</pre>
+
</source>
-
<pre class="code">
+
<source lang="javascript">
// Search for key "net.Response_Header".
// Search for key "net.Response_Header".
// If the key doesn't exist returns "Response Header".
// If the key doesn't exist returns "Response Header".
$STR("net.Response Header");
$STR("net.Response Header");
-
</pre>
+
</source>
-
<pre class="code">
+
<source lang="javascript">
var param1 = 10;
var param1 = 10;
var param2 = "ms";
var param2 = "ms";
// Returns "Request Time: 10 [ms]" for key that looks as follows:
// Returns "Request Time: 10 [ms]" for key that looks as follows:
-
// net.timing.Request_Time=Request Time: %S [%S]
+
// net.timing.Request_Time=Request Time: %1$S [%2$S]
$STRF("net.timing.Request Time", param1, param2);
$STRF("net.timing.Request Time", param1, param2);
-
</pre>
+
</source>
-
<pre class="code">
+
<source lang="javascript">
-
// the key can look like as follows:
+
// the key can look like as follows for en-US (two plural forms):
-
// plural.Request_Count=%S request;%S requests
+
// plural.Request_Count=%1$S request;%1$S requests
$STRP("plural.Request Count", 1); // Returns: 1 request
$STRP("plural.Request Count", 1); // Returns: 1 request
$STRP("plural.Request Count", 10); // Returns: 10 requests
$STRP("plural.Request Count", 10); // Returns: 10 requests
-
</pre>
+
</source>
-
In order to register a new string bundle (*.properties file) use <code>Firebug.registerStringBundle</code> method. This method should be also used from within a Firebug extension so, Firebug localization API properly work.
+
In order to register a new string bundle (*.properties file) and to let the Firebug localization API work properly use the <code>Firebug.registerStringBundle()</code> method. This method should be also used from within Firebug extensions.
-
<pre class="code">
+
<source lang="javascript">
-
Firebug.registerStringBundle("chrome://firecookie/locale/firecookie.properties");
+
Firebug.registerStringBundle("chrome://myfirebugextension/locale/myfirebugextension.properties");
-
</pre>
+
</source>
== Localization Events ==
== Localization Events ==
-
Every Firebug module ([[Firebug.Module]]), no matter if it's built-in core module or coming from an extension, should perform initial localization within ''internationalizeUI'' method. This module method is executed upon an ''internationalizeUI'' event that is dispatched to all registered modules during Firebug initialization process.
+
Every Firebug module ([[Firebug.Module]]), no matter if it's a built-in module or coming from an extension, should perform an initial localization within the <code>internationalizeUI</code> method. This module method is executed upon an <code>internationalizeUI</code> event that is dispatched to all registered modules during the Firebug initialization process.
-
 
+
-
Here is an example of such method.
+
 +
Here is an example of such a method:
<source lang="javascript">
<source lang="javascript">
-
Firebug.FireCookieModel = extend(Firebug.Module,
+
Firebug.MyFirebugExtension = Obj.extend(Module,
{
{
     //...
     //...
Line 110: Line 111:
     internationalizeUI: function()
     internationalizeUI: function()
     {
     {
-
         var elements = ["fcCookiesMenu", "fcExportAll", "fcExportForSite",
+
         var elements = ["button1", "button2", "button3"];
-
            "fcRemoveAll", "fcCreate", "fcCookieViewAll"];
+
-
         for (var i=0; i<elements.length; i++)
+
         for (var i = 0; i < elements.length; i++)
         {
         {
             var element = Firebug.chrome.$(elements[i]);
             var element = Firebug.chrome.$(elements[i]);
             if (element.hasAttribute("label"))
             if (element.hasAttribute("label"))
-
                 FBL.internationalize(element, "label");
+
                 Locale.internationalize(element, "label");
             if (element.hasAttribute("tooltiptext"))
             if (element.hasAttribute("tooltiptext"))
-
                 FBL.internationalize(element, "tooltiptext");
+
                 Locale.internationalize(element, "tooltiptext");
         }
         }
     },
     },
Line 131: Line 131:
<source lang="javascript">
<source lang="javascript">
-
    internationalizeUI: function()
+
internationalizeUI: function()
-
    {
+
{
-
        var elements = ["fcCookiesMenu", "fcExportAll", "fcExportForSite",
+
    var elements = ["button1", "button2", "button3"];
-
            "fcRemoveAll", "fcCreate", "fcCookieViewAll"];
+
-
        var attributes = ["label", "tooltiptext"];
+
    var attributes = ["label", "tooltiptext"];
-
        FBL.internationalizeElements(doc, elements, attributes);
+
    Locale.internationalizeElements(doc, elements, attributes);
-
    },
+
},
</source>
</source>

Revision as of 07:19, 3 February 2014

Firebug is using BabelZilla (BZ) to utilize an existing community of localizers and get translation to various languages. This effort requires a process and Firebug developers should follow some rules that help to synchronize files coming from BZ to the development source tree.

In case of any problems related to wrong usage of translated string within the Firebug's UI, please report a new issue.

Contents

Links

Development Rules

  • Developers should only change the en-US locale files, which stand like a template for all other translated locales.
  • If some string (its value) is changed, change also its key, so translators can see there is something new to translate. (BZ doesn't recognize string changes.)
  • When updating from BZ, always get all translations (even for not released locales) from BZ before uploading new version. So no translation made since the last upload is lost. The only dir, which is *not* synced with BZ is locale/en-US.
  • Only *.properties files should be used for localization. (Firebug doesn't want to use DTD files due a lack of script-ability.)
  • Do not put an empty string into *.properties files.

Naming Conventions

Every string in *.properties file is identified by ID (a key). For example, following string is identified by net.Response_Header and it's value is set to Response Header.

net.Response_Header=Response Header

String IDs in Firebug use following naming rules:

  • The key is prefixed with a lower case module name using the string (e.g. net or console, ...).
  • In case of many strings in one module you can use an additional prefix to further group related strings. Such a prefix should be followed by a period.
  • The part after the last period is used as the default value (with underscores replaced by spaces) in case the string is not available in the current locale.

See examples:

$STR("net.Response Header");
  • key is: net.Response_Header
  • default is: Response Header
$STR("net.timing.Request Time");
  • key is: net.timing.Request_Time
  • default is: Request Time

HINT: In case a string is not translated for the current Firefox locale, the en-US locale is used as fallback. Note that the en-US locale must always define all strings.

Localization APIs

There are several APIs that are used to make Firebug code localizable.

  • $STR - localization of a static string.
  • $STRF - localization of a string with dynamically inserted values (see more).
  • $STRP - localization of a plural form (see an example).

Some examples:

// Search for key "Label" within firebug *.properties files and returns its value.
// If the key doesn't exist returns "Label".
$STR("Label");
// Search for key "Button_Label" within the firebug *.properties files.
// If the key doesn't exist returns "Button Label".
$STR("Button Label");
// Search for key "net.Response_Header".
// If the key doesn't exist returns "Response Header".
$STR("net.Response Header");
var param1 = 10;
var param2 = "ms";
 
// Returns "Request Time: 10 [ms]" for key that looks as follows:
// net.timing.Request_Time=Request Time: %1$S [%2$S]
$STRF("net.timing.Request Time", param1, param2);
// the key can look like as follows for en-US (two plural forms):
// plural.Request_Count=%1$S request;%1$S requests
$STRP("plural.Request Count", 1); // Returns: 1 request
$STRP("plural.Request Count", 10); // Returns: 10 requests

In order to register a new string bundle (*.properties file) and to let the Firebug localization API work properly use the Firebug.registerStringBundle() method. This method should be also used from within Firebug extensions.

Firebug.registerStringBundle("chrome://myfirebugextension/locale/myfirebugextension.properties");

Localization Events

Every Firebug module (Firebug.Module), no matter if it's a built-in module or coming from an extension, should perform an initial localization within the internationalizeUI method. This module method is executed upon an internationalizeUI event that is dispatched to all registered modules during the Firebug initialization process.

Here is an example of such a method:

Firebug.MyFirebugExtension = Obj.extend(Module,
{
    //...
 
    internationalizeUI: function()
    {
        var elements = ["button1", "button2", "button3"];
 
        for (var i = 0; i < elements.length; i++)
        {
            var element = Firebug.chrome.$(elements[i]);
            if (element.hasAttribute("label"))
                Locale.internationalize(element, "label");
 
            if (element.hasAttribute("tooltiptext"))
                Locale.internationalize(element, "tooltiptext");
        }
    },
 
    //...
});

Here is a simplified version of the same:

internationalizeUI: function()
{
    var elements = ["button1", "button2", "button3"];
 
    var attributes = ["label", "tooltiptext"];
 
    Locale.internationalizeElements(doc, elements, attributes);
},
Personal tools