Locale-specific message reference

Each internationalized extension has at least one file named messages.json that provides locale-specific strings. This page describes the format of messages.json files.

messages.json example

The following code shows an example messages.json file, taken from our notify-link-clicks-i18n example extension. Only the "name" and "message" fields are required.

{
  "extensionName": {
    "message": "Notify link clicks i18n",
    "description": "Name of the extension."
  },

  "extensionDescription": {
    "message": "Shows a notification when the user clicks on links.",
    "description": "Description of the extension."
  },

  "notificationTitle": {
    "message": "Click notification",
    "description": "Title of the click notification."
  },

  "notificationContent": {
    "message": "You clicked $URL$.",
    "description": "Tells the user which link they clicked.",
    "placeholders": {
      "url" : {
        "content" : "$1",
        "example" : "https://developer.mozilla.org"
      }
    }
  }
}

Placement

Your messages.json files need to be placed inside directories named after the locale each one is supporting — en, de, ja, etc. These in turn need to be placed inside a directory called _locales, inside the root of your extension.

Member details

This section describes each member that can appear in a messages.json file.

name

Each top-level member is named after the name of the message string you are localizing, for example "extensionName" or "notificationContent" in the example above. Each name is case-insensitive, and acts as a key allowing you to retrieve the localized message text.

The name can include the following characters:

• A-Z
• a-z
• 0-9
• _ (underscore)
• @

message

At least this property must be set for every string. The "message" member contains a localized string that can contain placeholders. You can use:

• $placeholder_name$ (case insensitive) to insert a particular placeholder (for example $URL$ in the example above) into your string.
• $1, $2, $3, etc. to directly insert values obtained from a i18n.getMessage() call into your string.

Other points to note:

• Any number of consecutive dollar signs appearing in strings are replaced by the same number of dollar signs minus one. So, $$ > $, $$$ > $$, etc.
• When the locale file is read, tokens matching /\$([a-z0-9_@]+)\$/i are replaced with the matching value from the string's "placeholders" object. These substitutions happen prior to processing any /\$\d/ tokens in the message.
• When a locale string is used, tokens matching /\$\d+/ are replaced with the replacements passed to i18n.getMessage().
• getMessage() won't process calls with more than 9 placeholders/substitutions.

description

Optional

The "description" member should contain a description of the message string's contents, aimed to provide a translator with help to create the best translation possible of the string.

placeholders

Optional

The "placeholders" member defines one or more placeholder substrings to be used within the message — these can be used to hardcode items that you don't want translated, or refer to variables.

Each placeholder substring definition has a number of values of its own:

"url" : {
  "content" : "$1",
  "example" : "https://developer.mozilla.org"
}

placeholder name

The placeholder name is used to represent the placeholder in the substitution string (e.g. "url" becomes $url$). It is case insensitive and can contain the same characters as a message string name.

content

The "content" item defines the content of the placeholder. This can be a hardcoded string, such as "My placeholder", but it can also include values obtained from a i18n.getMessage() call. This property is required. For more information, see Retrieving message strings from JavaScript.

example

Optional

The optional "example" item is again intended to help translators by showing them an example of how the placeholder would appear to end users, allowing them to make the best choice when localizing the file.