Localizing extension descriptions

This article provides details on how to go about localizing the descriptions of Mozilla add-ons, as well as for other metadata about your add-on. Because a new method for doing so was implemented in Gecko 1.9 (Firefox 3), there are two sets of instructions below.

Localizing in Gecko 1.9

Gecko 1.9 includes a new, more robust method for localizing add-on descriptions and other metadata. All of the different descriptions now appear in the install.rdf file using em:localized properties. Each has at least one em:locale property marking the locale that the information should be used for and then all the various strings for the locale. The following example demonstrates this (most normal manifest properties have been removed for brevity):

<?xml version="1.0"?>
<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="http://www.mozilla.org/2004/em-rdf#">
  <Description about="urn:mozilla:install-manifest">
    <em:id>TabSidebar@blueprintit.co.uk</em:id>
    <em:localized>
      <Description>
        <em:locale>de-DE</em:locale>
        <em:name>Tab Sidebar</em:name>
        <em:description>Zeigt in einer Sidebar Vorschaubilder der Inhalte aller offenen Tabs an.</em:description>
      </Description>
    </em:localized>
    <em:localized>
      <Description>
        <em:locale>es-ES</em:locale>
        <em:name>Tab Sidebar</em:name>
        <em:description>Muestra una vista previa de sus pestañas en su panel lateral.</em:description>
      </Description>
    </em:localized>
    <em:localized>
      <Description>
        <em:locale>nl-NL</em:locale>
        <em:name>Tab Sidebar</em:name>
        <em:description>Laat voorbeeldweergaven van uw tabbladen in de zijbalk zien.</em:description>
      </Description>
    </em:localized>
    <em:name>Tab Sidebar</em:name>
    <em:description>Displays previews of your tabs in your sidebar.</em:description>
  </Description>
</RDF>

All of the metadata mentioned below can be localized in this way. The localization information provided by the em:localized property can be overriden using a set of localized preferences as detailed below.

The process for selecting the em:localized property to use for a given locale is as follows:

1. If a property exists with an em:locale that matches the locale exactly, then use that.
2. If we have inexact matches then use the one with the most matching parts, parts being separated by a dash (e.g., es would match for es-ES and vice versa).
3. If there is more than one locale with the same number of matching parts, then use the most general one (e.g., en in preference to en-GB when searching for en-US).

The current app locale will be searched for and then there will be a fallback search for en-US.

If a preference isn't set and there isn't a matching em:localized property for the current locale or en-US, then the properties specified directly on the install manifest are used as a last resort, as they were always used before Gecko 1.9.

Localizing before Gecko 1.9

Before Gecko 1.9, add-on developers must go through a special process to define localized add-on descriptions for add-ons targeting toolkit-based apps (such as Firefox or Thunderbird).

• If you do not currently have them, create localized properties files. Make sure to use UTF-8 encoding (without BOM) to ensure foreign characters display correctly.
• Add the following line to each of your localization properties files (where EXTENSION_ID matches your extension ID (<em:id> from install.rdf) and LOCALIZED_DESCRIPTION is the description of your extension that you want to appear in the given language):

  extensions.EXTENSION_ID.description=LOCALIZED_DESCRIPTION

• If you do not currently have one, create a default preferences file.
• Add the following line to it (where EXTENSION_ID matches your application ID from install.rdf and PATH_TO_LOCALIZATION_FILE is the chrome path to the localization file you added to earlier):

  pref("extensions.EXTENSION_ID.description", "PATH_TO_LOCALIZATION_FILE");

Localizable strings

The following add-on metadata can be localized using this process:

• name
• description
• creator
• homepageURL

Localizable lists

In cases where multiple values can exist, a numeric index is appended to the end of the preference name:

extensions.EXTENSION_ID.contributor.1=FIRST_LOCALIZED_CONTRIBUTOR_NAME
extensions.EXTENSION_ID.contributor.2=SECOND_LOCALIZED_CONTRIBUTOR_NAME
extensions.EXTENSION_ID.contributor.3=THRID_LOCALIZED_CONTRIBUTOR_NAME
pref("extensions.EXTENSION_ID.contributor.1", "PATH_TO_LOCALIZATION_FILE");
pref("extensions.EXTENSION_ID.contributor.2", "PATH_TO_LOCALIZATION_FILE");
pref("extensions.EXTENSION_ID.contributor.3", "PATH_TO_LOCALIZATION_FILE");

The following add-on metadata can be localized using this process:

• developer
• translator
• contributor