<div id="pageData-name" class="pageData">Formats: Locale-Specific Messages</div>
<div id="pageData-showTOC" class="pageData">true</div>
<p>
Each internationalized extension has at least one
file named <code>messages.json</code>
that provides locale-specific strings for the extension.
This page describes the format of <code>messages.json</code> files.
For information on how to internationalize and localize your extension,
see the <a href="i18n.html">Internationalization</a> page.
</p>
<h2 id="overview"> Field summary </h2>
<p>
The following code shows the supported fields for
<code>messages.json</code>.
Only the "<em>name</em>" and "message" fields are required.
</p>
<pre>
{
"<a href="#name"><em>name</em></a>": {
"<a href="#message">message</a>": "<em>Message text, with optional placeholders.</em>",
"<a href="#description">description</a>": "<em>Translator-aimed description of the message.</em>",
"<a href="#placeholders">placeholders</a>": {
"<em>placeholder_name</em>": {
"content": "<em>A string to be placed within the message.</em>",
"example": "<em>Translator-aimed example of the placeholder string.</em>"
},
...
}
},
...
}
</pre>
<h2 id="example"> Example </h2>
<p>
Here's a <code>messages.json</code> file
that defines three messages
named "prompt_for_name", "hello", and "bye":
</p>
<pre>
{
"prompt_for_name": {
"message": "What's your name?",
"description": "Ask for the user's name"
},
"hello": {
"message": "Hello, $USER$",
"description": "Greet the user",
"placeholders": {
"user": {
"content": "$1",
"example": "Cira"
}
}
},
"bye": {
"message": "Goodbye, $USER$. Come back to $OUR_SITE$ soon!",
"description": "Say goodbye to the user",
"placeholders": {
"our_site": {
"content": "Example.com",
},
"user": {
"content": "$1",
"example": "Cira"
}
}
}
}
</pre>
<h2>Field details</h2>
<p>
This section describes each field
that can appear in a <code>messages.json</code> file.
For details on how the messages file is used —
for example, what happens when a locale doesn't define
all the messages —
see <a href="i18n.html">Internationalization</a>.
</p>
<h3 id="name">name</h3>
<p>
Actually, there's no field called "name".
This field's name is the name of the message —
the same <em>name</em> that you see in
<code>__MSG_<em>name</em>__</code>
or <code>getMessage("<em>name</em>")</code>.
</p>
<p>
The name is a case-insensitive key
that lets you retrieve the localized message text.
The name can include the following characters:
</p>
<ul>
<li> A-Z </li>
<li> a-z </li>
<li> 0-9 </li>
<li> _ (underscore) </li>
<li> @ </li>
</ul>
<p class="note">
<b>Note:</b>
Don't define names that begin with "@@".
Those names are reserved for
<a href="i18n.html#overview-predefined">predefined messages</a>.
</p>
<p>
Here are three examples of names,
taken from the <a href="#example">Example</a> section:
</p>
<pre>
"prompt_for_name": {
...
},
"hello": {
...
},
"bye": {
...
}
</pre>
<p>
For more examples of using names, see the
<a href="i18n.html">Internationalization</a> page.
</p>
<h3 id="message">message</h3>
<p>
The translated message,
in the form of a string that can contain
<a href="#placeholders">placeholders</a>.
Use <code>$<em>placeholder_name</em>$</code>
(case insensitive)
to refer to a particular placeholder.
For example, you can refer to a placeholder named "our_site" as
<code>$our_site$</code>, <code>$OUR_SITE$</code>, or <code>$oUR_sITe$</code>.
</p>
<p>
Here are three examples of messages,
taken from the <a href="#example">Example</a> section:
</p>
<pre>
"message": "What's your name?"
...
"message": "Hello, $USER$"
...
"message": "Goodbye, $USER$. Come back to $OUR_SITE$ soon!"
</pre>
<p>
To put a dollar sign (<code>$</code>) into the string,
use <code>$$</code>.
For example, use the following code to specify the message
<b>Amount (in $)</b>:
<pre>
"message": "Amount (in $$)"
</pre>
<p>
Although placeholders such as <code>$USER$</code> are
the preferred way of referring to <em>substitution strings</em>
(strings specified using the <em>substitutions</em> parameter of
<a href="i18n.html#method-getMessage"><code>getMessage()</code></a>)
you can also refer to substitution strings directly
within the message.
For example, the following message
refers to the first three substitution strings passed into
<code>getMessage()</code>:
</p>
<pre>
"message": "Params: $1, $2, $3"
</pre>
<p>
Despite that example,
we recommend that you stick to using placeholders
instead of <code>$<em>n</em></code> strings
within your messages.
Think of placeholders as good variable names.
A week after you write your code,
you'll probably forget what <code>$1</code> refers to,
but you'll know what your placeholders refer to.
For more information on placeholders and substitution strings, see
the <a href="#placeholders">placeholders</a> section.
</p>
<h3 id="description">description</h3>
<p>
<em>Optional.</em>
A description of the message,
intended to give context
or details to help the translator
make the best possible translation.
</p>
<p>
Here are three examples of descriptions,
taken from the <a href="#example">Example</a> section:
</p>
<pre>
"description": "Ask for the user's name"
...
"description": "Greet the user"
...
"description": "Say goodbye to the user"
</pre>
<h3 id="placeholders">placeholders</h3>
<p>
<em>Optional.</em>
Defines one or more substrings
to be used within the message.
Here are two reasons you might want to use a placeholder:
</p>
<ul>
<li>
To define the text
for a part of your message
that shouldn't be translated.
Examples: HTML code, trademarked names, formatting specifiers.
</li>
<li>
To refer to a substitution string passed into
<code>getMessage()</code>.
Example: <code>$1</code>.
</li>
</ul>
<p>
Each placeholder has a name,
a "content" item,
and an optional "example" item.
A placeholder's name is case-insensitive
and can contain the same characters
as a <a href="#name">message name</a>.
</p>
<p>
The "content" item's value is a string
that can refer to substitution strings, which are
specified using the
<a href="i18n.html#method-getMessage"><code>getMessage()</code></a> method's
<em>substitutions</em> parameter.
The value of a "content" item is typically something like
"Example.com" or "$1".
If you refer to
a substitution string that doesn't exist,
you get an empty string.
The following table shows how
<code>$<em>n</em></code> strings correspond to
strings specified by the <em>substitutions</em> parameter.
</p>
<table>
<tr>
<th> <em>substitutions</em> parameter </th>
<th> Value of $1</th>
<th> Value of $2</th>
<th> Value of $3</th>
</tr>
<tr>
<td> <code>userName</code> </td>
<td> value of <code>userName</code> </td>
<td> <code>""</code> </td>
<td> <code>""</code> </td>
</tr>
<tr>
<td> <code>["Cira", "Kathy"]</code> </td>
<td> <code>"Cira"</code> </td>
<td> <code>"Kathy"</code> </td>
<td> <code>""</code> </td>
</tr>
</table>
<p>
The "example" item
(optional, but highly recommended)
helps translators by showing how the content appears to the end user.
For example, a placeholder
for a dollar amount
should have an example like <code>"$23.45"</code>.
</p>
<p>
The following snippet,
taken from the <a href="#example">Example</a> section,
shows a "placeholders" item that contains two placeholders
named "our_site" and "user".
The "our_site" placeholder has no "example" item
because its value is obvious from the "content" field.
</p>
<pre>
"placeholders": {
"our_site": {
"content": "Example.com",
},
"user": {
"content": "$1",
"example": "Cira"
}
}
</pre>