Firebug Localization

From FirebugWiki

(Difference between revisions)
Jump to: navigation, search
m (Fixed code formatting)
(Changed localization rules according to https://wiki.mozilla.org/Firebug/WeeklyUpdates/2014-04-15#Localization)
 
Line 6: Line 6:
* [http://www.get-firefox.eu/localization.html MDC]
* [http://www.get-firefox.eu/localization.html MDC]
-
* [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 BZ)
* [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]
* [https://developer.mozilla.org/En/Localization_and_Plurals Plurals]
Line 14: Line 14:
* Developers should only change the <code>en-US</code> locale files, which stand like a template for all other translated locales.
* Developers should only change the <code>en-US</code> 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.)
+
* If some string (the value) is changed, change also its key, so translators can see there is something new to translate. (BZ doesn't recognize value 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 <code>locale/en-US</code>.
+
* When updating from BZ, always get all translations (even for not released locales) from BZ before releasing a new version. So no translation made since the last upload is lost. The only directory, which is *not* synced with BZ is <code>locale/en-US</code>.
* 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.
* Do not put an empty string into ''*.properties'' files.
 +
 +
* Add a short description adding some context for each translation. The description may group several translations. Also it should help to avoid any grammatical misinterpretations (e.g. clarify that "Profile" is used as a verb and not as a noun).
 +
 +
Examples for descriptions:
 +
<source lang="properties">
 +
# LOCALIZATION NOTE (doNotShowThisMessageAgain):
 +
# Label of a checkbox within a confirmation dialog used to disable the confirmation.
 +
</source>
 +
 +
<source lang="properties">
 +
# LOCALIZATION NOTE (console.copyError, console.copyErrorTooltip):
 +
# Context menu option of errors logged to the Console panel.
 +
</source>
 +
 +
<source lang="properties">
 +
# LOCALIZATION NOTE (profile):
 +
# Caption (verb) for the button used to start the JavaScript profiler.
 +
</source>
== 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 ''Response Header''.
+
Every string in a ''*.properties'' file is identified by an ID (a key). For example, the following string is identified by the key ''net.Response_Header'' and it's value is set to ''Response Header''.
<source lang="properties">
<source lang="properties">
-
net.Response_Header=Response Header
+
net.responseHeader=Response Header
</source>
</source>
-
String IDs in Firebug use following naming rules:
+
Localization keys in Firebug follow these naming rules:
-
* The key is prefixed with a lower case module name using the string (e.g. ''net'' or ''console'', ...).
+
* Keys are written in lowerCamelCase, i.e. the initial of each word or abbreviation except the first one is written in uppercase, the rest of the letters in lowercase. (E.g. <code>moduleManager.title</code>, <code>firebug.increaseTextSize</code>
-
* 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.
+
* Do '''not''' use underscores or hyphens.
-
* 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.
+
* Use <code><key name></code> for global translations and <code><module>.<key name></code> for module specific translations.
 +
* For similar UI use similar keys. (E.g. <code>net.filterAllTooltip</code> and <code>cookies.headerMaxAgeTooltip</code>)
-
See examples:
+
''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. If the <code>en-US</code> doesn't contain the translation either, the, the part of the key after the last period is used as the default value (with underscores replaced by spaces).''
 +
 
 +
Examples:
<source lang="javascript">
<source lang="javascript">
-
$STR("net.Response Header");
+
$STR("net.responseHeader");
</source>
</source>
-
* key is: ''net.Response_Header''
+
* key is: ''net.responseHeader''
-
* default is: ''Response Header''
+
* default is: ''responseHeader''
<source lang="javascript">
<source lang="javascript">
-
$STR("net.timing.Request Time");
+
$STR("net.timing.requestTime");
</source>
</source>
-
* key is: ''net.timing.Request_Time''
+
* key is: ''net.timing.requestTime''
-
* default is: ''Request Time''
+
* default is: ''requestTime''
-
 
+
-
''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.''
+
== Localization APIs ==
== Localization APIs ==
Line 61: Line 80:
Some examples:
Some examples:
<source lang="javascript">
<source lang="javascript">
-
// 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");
</source>
</source>
<source lang="javascript">
<source lang="javascript">
-
// Search for key "Button_Label" within the firebug *.properties files.
+
// Search for key "buttonLabel" within the firebug *.properties files.
-
// If the key doesn't exist returns "Button Label".
+
// If the key doesn't exist, returns "buttonLabel".
-
$STR("Button Label");
+
$STR("buttonLabel");
</source>
</source>
<source lang="javascript">
<source lang="javascript">
-
// Search for key "net.Response_Header".
+
// Search for key "net.responseHeader".
-
// If the key doesn't exist returns "Response Header".
+
// If the key doesn't exist, returns "responseHeader".
-
$STR("net.Response Header");
+
$STR("net.responseHeader");
</source>
</source>
Line 83: Line 102:
// 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: %1$S [%2$S]
+
// net.timing.requestTime=Request Time: %1$S [%2$S]
-
$STRF("net.timing.Request Time", param1, param2);
+
$STRF("net.timing.requestTime", param1, param2);
</source>
</source>
<source lang="javascript">
<source lang="javascript">
-
// the key can look like as follows for en-US (two plural forms):
+
// The key can look like as follows for en-US (two plural forms):
-
// plural.Request_Count=%1$S request;%1$S requests
+
// net.requestCount=%1$S request;%1$S requests
-
$STRP("plural.Request Count", 1); // Returns: 1 request
+
$STRP("net.requestCount", 1); // Returns: 1 request
-
$STRP("plural.Request Count", 10); // Returns: 10 requests
+
$STRP("net.requestCount", 10); // Returns: 10 requests
</source>
</source>

Latest revision as of 10:00, 6 May 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

[edit] Links

[edit] Development Rules

  • Developers should only change the en-US locale files, which stand like a template for all other translated locales.
  • If some string (the value) is changed, change also its key, so translators can see there is something new to translate. (BZ doesn't recognize value changes.)
  • When updating from BZ, always get all translations (even for not released locales) from BZ before releasing a new version. So no translation made since the last upload is lost. The only directory, 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.
  • Add a short description adding some context for each translation. The description may group several translations. Also it should help to avoid any grammatical misinterpretations (e.g. clarify that "Profile" is used as a verb and not as a noun).

Examples for descriptions:

# LOCALIZATION NOTE (doNotShowThisMessageAgain): 
# Label of a checkbox within a confirmation dialog used to disable the confirmation.
# LOCALIZATION NOTE (console.copyError, console.copyErrorTooltip):
# Context menu option of errors logged to the Console panel.
# LOCALIZATION NOTE (profile):
# Caption (verb) for the button used to start the JavaScript profiler.

[edit] Naming Conventions

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

net.responseHeader=Response Header

Localization keys in Firebug follow these naming rules:

  • Keys are written in lowerCamelCase, i.e. the initial of each word or abbreviation except the first one is written in uppercase, the rest of the letters in lowercase. (E.g. moduleManager.title, firebug.increaseTextSize
  • Do not use underscores or hyphens.
  • Use <key name> for global translations and <module>.<key name> for module specific translations.
  • For similar UI use similar keys. (E.g. net.filterAllTooltip and cookies.headerMaxAgeTooltip)

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. If the en-US doesn't contain the translation either, the, the part of the key after the last period is used as the default value (with underscores replaced by spaces).

Examples:

$STR("net.responseHeader");
  • key is: net.responseHeader
  • default is: responseHeader
$STR("net.timing.requestTime");
  • key is: net.timing.requestTime
  • default is: requestTime

[edit] 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 "buttonLabel" within the firebug *.properties files.
// If the key doesn't exist, returns "buttonLabel".
$STR("buttonLabel");
// Search for key "net.responseHeader".
// If the key doesn't exist, returns "responseHeader".
$STR("net.responseHeader");
var param1 = 10;
var param2 = "ms";
 
// Returns "Request Time: 10 [ms]" for key that looks as follows:
// net.timing.requestTime=Request Time: %1$S [%2$S]
$STRF("net.timing.requestTime", param1, param2);
// The key can look like as follows for en-US (two plural forms):
// net.requestCount=%1$S request;%1$S requests
$STRP("net.requestCount", 1); // Returns: 1 request
$STRP("net.requestCount", 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");

[edit] 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