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.

**Note:** For information on how to internationalize your extensions, see our i18n guide.

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.


```json
{
  "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)
* @

**Note:** You shouldn't define names that start with @@. Such names are reserved for predefined messages.

### 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:


```json
"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.