Extensions Docs Server: Doc conversion script

chrome/common/extensions/docs/server2/templates/articles/i18n-messages.html

+<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 &mdash;
+for example, what happens when a locale doesn't define
+all the messages &mdash;
+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 &mdash;
+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>