diff options
Diffstat (limited to 'chrome/common/extensions/docs/templates/articles/i18n-messages.html')
| -rw-r--r-- | chrome/common/extensions/docs/templates/articles/i18n-messages.html | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/chrome/common/extensions/docs/templates/articles/i18n-messages.html b/chrome/common/extensions/docs/templates/articles/i18n-messages.html new file mode 100644 index 0000000..f9a6620 --- /dev/null +++ b/chrome/common/extensions/docs/templates/articles/i18n-messages.html @@ -0,0 +1,330 @@ +<h1>Formats: Locale-Specific Messages</h1> + + +<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>
\ No newline at end of file |