diff options
| author | kathyw@chromium.org <kathyw@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98> | 2010-01-19 23:50:00 +0000 |
|---|---|---|
| committer | kathyw@chromium.org <kathyw@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98> | 2010-01-19 23:50:00 +0000 |
| commit | 1ab370fcdbcde6b2c1ff476a9db5c9ad183ecb24 (patch) | |
| tree | 169337900027639484834ae0031e301ceaf6666a | |
| parent | 140ee653f8fdfa395cb829e40e5cc991dc0e86e0 (diff) | |
| download | chromium_src-1ab370fcdbcde6b2c1ff476a9db5c9ad183ecb24.zip chromium_src-1ab370fcdbcde6b2c1ff476a9db5c9ad183ecb24.tar.gz chromium_src-1ab370fcdbcde6b2c1ff476a9db5c9ad183ecb24.tar.bz2 | |
Fleshing out the i18n doc. Added a page for the messages.json
format (i18n-messages.html). Miscellaneous small improvements to i18n.html and to the generated API doc.
TEST=none
BUG=none
Review URL: http://codereview.chromium.org/546060
git-svn-id: svn://svn.chromium.org/chrome/trunk/src@36573 0039d316-1c4b-4281-b951-d872f2087c98
| -rwxr-xr-x | chrome/common/extensions/api/extension_api.json | 6 | ||||
| -rw-r--r-- | chrome/common/extensions/docs/i18n-messages.html | 772 | ||||
| -rw-r--r-- | chrome/common/extensions/docs/i18n.html | 38 | ||||
| -rwxr-xr-x | chrome/common/extensions/docs/static/i18n-messages.html | 325 | ||||
| -rw-r--r-- | chrome/common/extensions/docs/static/i18n.html | 37 |
5 files changed, 1148 insertions, 30 deletions
diff --git a/chrome/common/extensions/api/extension_api.json b/chrome/common/extensions/api/extension_api.json index 1daeb09..5a3e6c5 100755 --- a/chrome/common/extensions/api/extension_api.json +++ b/chrome/common/extensions/api/extension_api.json @@ -1635,11 +1635,11 @@ "name": "getMessage", "type": "function", "unprivileged": true, - "description": "Gets the localized string for the specified message.", + "description": "Gets the localized string for the specified message. If the message is missing, this method returns an empty string (''). If the format of the <code>getMessage()</code> call is wrong — for example, <em>messageName</em> is not a string or the <em>substitutions</em> array is empty or has more than 9 elements — this method returns <code>undefined</code>.", "parameters": [ { "type": "string", "name": "messageName", - "description": "The name of the message, as specified in the <code>messages.json</code> file." + "description": "The name of the message, as specified in the <a href='i18n-messages.html'><code>messages.json</code></a> file." }, { "choices": [ @@ -1653,7 +1653,7 @@ ], "name": "substitutions", "optional": true, - "description": "1 - 9 substitution parameters, if the message requires any." + "description": "1 - 9 substitution strings, if the message requires any." } ], "returns": { diff --git a/chrome/common/extensions/docs/i18n-messages.html b/chrome/common/extensions/docs/i18n-messages.html new file mode 100644 index 0000000..b76c49f --- /dev/null +++ b/chrome/common/extensions/docs/i18n-messages.html @@ -0,0 +1,772 @@ +<!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note: + 1) The <head> information in this page is significant, should be uniform + across api docs and should be edited only with knowledge of the + templating mechanism. + 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a + browser, it will be re-generated from the template, json schema and + authored overview content. + 4) The <body>.innerHTML is also generated by an offline step so that this + page may easily be indexed by search engines. +--><html xmlns="http://www.w3.org/1999/xhtml"><head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css"> + <link href="css/print.css" rel="stylesheet" type="text/css" media="print"> + <script type="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.js"> + </script> + <script type="text/javascript" src="js/api_page_generator.js"></script> + <script type="text/javascript" src="js/bootstrap.js"></script> + <title>Formats: Locale-Specific Messages - Google Chrome Extensions - Google Code</title></head><body> <div id="gc-container" class="labs"> + <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION --> + <!-- In particular, sub-templates that recurse, must be used by allowing + jstemplate to make a copy of the template in this section which + are not operated on by way of the jsskip="true" --> + <div style="display:none"> + + <!-- VALUE --> + <div id="valueTemplate"> + <dt> + <var>paramName</var> + <em> + + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <a> Type</a> + </span> + <span> + <span> + array of <span><span></span></span> + </span> + <span>paramType</span> + </span> + </span> + ) + </div> + + </em> + </dt> + <dd class="todo"> + Undocumented. + </dd> + <dd> + Description of this parameter from the json schema. + </dd> + + <!-- OBJECT PROPERTIES --> + <dd> + <dl> + <div> + <div> + </div> + </div> + </dl> + </dd> + </div> <!-- /VALUE --> + + </div> <!-- /SUBTEMPLATES --> + + <a id="top"></a> + <div id="skipto"> + <a href="#gc-pagecontent">Skip to page content</a> + <a href="#gc-toc">Skip to main navigation</a> + </div> + <!-- API HEADER --> + <table id="header" width="100%" cellspacing="0" border="0"> + <tbody><tr> + <td valign="middle"><a href="http://code.google.com/"><img src="images/code_labs_logo.gif" height="43" width="161" alt="Google Code Labs" style="border:0; margin:0;"></a></td> + <td valign="middle" width="100%" style="padding-left:0.6em;"> + <form action="http://www.google.com/cse" id="cse" style="margin-top:0.5em"> + <div id="gsc-search-box"> + <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno"> + <input type="hidden" name="ie" value="UTF-8"> + <input type="text" name="q" value="" size="55"> + <input class="gsc-search-button" type="submit" name="sa" value="Search"> + <br> + <span class="greytext">e.g. "page action" or "tabs"</span> + </div> + </form> + + <script type="text/javascript" src="http://www.google.com/jsapi"></script> + <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script> + <script type="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse&t13n_langs=en"></script> + <script type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse&lang=en"></script> + </td> + </tr> + </tbody></table> + + <div id="codesiteContent" class=""> + + <a id="gc-topnav-anchor"></a> + <div id="gc-topnav"> + <h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Labs</a>)</h1> + <ul id="home" class="gc-topnav-tabs"> + <li id="home_link"> + <a href="index.html" title="Google Chrome Extensions home page">Home</a> + </li> + <li id="docs_link"> + <a href="docs.html" title="Official Google Chrome Extensions documentation">Docs</a> + </li> + <li id="faq_link"> + <a href="faq.html" title="Answers to frequently asked questions about Google Chrome Extensions">FAQ</a> + </li> + <li id="samples_link"> + <a href="samples.html" title="Sample extensions (with source code)">Samples</a> + </li> + <li id="group_link"> + <a href="http://groups.google.com/group/chromium-extensions" title="Google Chrome Extensions developer forum">Group</a> + </li> + </ul> + </div> <!-- end gc-topnav --> + + <div class="g-section g-tpl-170"> + <!-- SIDENAV --> + <div class="g-unit g-first" id="gc-toc"> + <ul> + <li><a href="getstarted.html">Getting Started</a></li> + <li><a href="overview.html">Overview</a></li> + <li><h2><a href="devguide.html">Developer's Guide</a></h2> + <ul> + <li>Browser UI + <ul> + <li><a href="browserAction.html">Browser Actions</a></li> + <li><a href="options.html">Options Pages</a></li> + <li><a href="override.html">Override Pages</a></li> + <li><a href="pageAction.html">Page Actions</a></li> + <li><a href="themes.html">Themes</a></li> + </ul> + </li> + <li>Browser Interaction + <ul> + <li><a href="bookmarks.html">Bookmarks</a></li> + <li><a href="events.html">Events</a></li> + <li><a href="tabs.html">Tabs</a></li> + <li><a href="windows.html">Windows</a></li> + </ul> + </li> + <li>Implementation + <ul> + <li><a href="background_pages.html">Background Pages</a></li> + <li><a href="content_scripts.html">Content Scripts</a></li> + <li><a href="xhr.html">Cross-Origin XHR</a></li> + <li><a href="i18n.html">Internationalization</a></li> + <li><a href="messaging.html">Message Passing</a></li> + <li><a href="npapi.html">NPAPI Plugins</a></li> + </ul> + </li> + <li>Finishing + <ul> + <li><a href="autoupdate.html">Autoupdating</a></li> + <li><a href="packaging.html">Packaging</a></li> + <li><a href="external_extensions.html">External Extensions</a></li> + </ul> + </li> + </ul> + </li> + <li><h2><a href="tutorials.html">Tutorials</a></h2> + <ul> + <li><a href="tut_debugging.html">Debugging</a></li> + </ul> + </li> + <li><h2>Reference</h2> + <ul> + <li>Formats + <ul> + <li><a href="manifest.html">Manifest Files</a></li> + <li><a href="match_patterns.html">Match Patterns</a></li> + <!-- <li>Packages (.crx)</li> --> + </ul> + </li> + <li><a href="api_index.html">chrome.* APIs</a></li> + <li><a href="api_other.html">Other APIs</a></li> + </ul> + </li> + <li><h2><a href="samples.html">Samples</a></h2></li> + </ul> + </div> + + <div class="g-unit" id="gc-pagecontent"> + <div id="pageTitle"> + <h1 class="page_title">Formats: Locale-Specific Messages</h1> + </div> + <!-- TABLE OF CONTENTS --> + <div id="toc"> + <h2>Contents</h2> + <ol> + <li> + <a href="#overview"> Field summary </a> + <ol> + <li style="display: none; "> + <a>h3Name</a> + </li> + </ol> + </li><li> + <a href="#example"> Example </a> + <ol> + <li style="display: none; "> + <a>h3Name</a> + </li> + </ol> + </li><li> + <a href="#H2-2">Field details</a> + <ol> + <li> + <a href="#name">name</a> + </li><li> + <a href="#message">message</a> + </li><li> + <a href="#description">description</a> + </li><li> + <a href="#placeholders">placeholders</a> + </li> + </ol> + </li> + <li style="display: none; "> + <a href="#apiReference">API reference</a> + <ol> + <li> + <a href="#properties">Properties</a> + <ol> + <li> + <a href="#property-anchor">propertyName</a> + </li> + </ol> + </li> + <li> + <a href="#methods">Methods</a> + <ol> + <li> + <a href="#method-anchor">methodName</a> + </li> + </ol> + </li> + <li> + <a href="#events">Events</a> + <ol> + <li> + <a href="#event-anchor">eventName</a> + </li> + </ol> + </li> + <li> + <a href="#types">Types</a> + <ol> + <li> + <a href="#id-anchor">id</a> + </li> + </ol> + </li> + </ol> + </li> + </ol> + </div> + <!-- /TABLE OF CONTENTS --> + + <!-- STATIC CONTENT PLACEHOLDER --> + <div id="static"><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> + + +<a name="H2-2"></a><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> +</ul> + +<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>: + +</p><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> +<tbody><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> +</tbody></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> + + + +</div> + + <!-- API PAGE --> + <div class="apiPage" style="display: none; "> + <a name="apiReference"></a> + <h2>API reference: chrome.apiname </h2> + + <!-- PROPERTIES --> + <div class="apiGroup"> + <a name="properties"></a> + <h3 id="properties">Properties</h3> + + <div> + <a></a> + <h4>getLastError</h4> + <div class="summary"> + <!-- Note: intentionally longer 80 columns --> + <span>chrome.extension</span><span>lastError</span> + </div> + <div> + </div> + </div> + + </div> <!-- /apiGroup --> + + <!-- METHODS --> + <div class="apiGroup" id="methods"> + <a name="methods"></a> + <h3>Methods</h3> + + <!-- iterates over all functions --> + <div class="apiItem"> + <a></a> <!-- method-anchor --> + <h4>method name</h4> + + <div class="summary"><span>void</span> + <!-- Note: intentionally longer 80 columns --> + <span>chrome.module.methodName</span>(<span><span>, </span><span></span> + <var><span></span></var></span>)</div> + + <div class="description"> + <p class="todo">Undocumented.</p> + <p> + A description from the json schema def of the function goes here. + </p> + + <!-- PARAMETERS --> + <h4>Parameters</h4> + <dl> + <div> + <div> + </div> + </div> + </dl> + + <!-- RETURNS --> + <h4>Returns</h4> + <dl> + <div> + <div> + </div> + </div> + </dl> + + <!-- CALLBACK --> + <div> + <div> + <h4>Callback function</h4> + <p> + The callback <em>parameter</em> should specify a function + that looks like this: + </p> + <p> + If you specify the <em>callback</em> parameter, it should + specify a function that looks like this: + </p> + + <!-- Note: intentionally longer 80 columns --> + <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>);</pre> + <dl> + <div> + <div> + </div> + </div> + </dl> + </div> + </div> + + </div> <!-- /description --> + + </div> <!-- /apiItem --> + + </div> <!-- /apiGroup --> + + <!-- EVENTS --> + <div class="apiGroup"> + <a name="events"></a> + <h3 id="events">Events</h3> + + <!-- iterates over all events --> + <div class="apiItem"> + <a></a> + <h4>event name</h4> + + <div class="summary"> + <!-- Note: intentionally longer 80 columns --> + <span class="subdued">chrome.bookmarks</span><span>onEvent</span><span class="subdued">.addListener</span>(function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>); + </div> + + <div class="description"> + <p class="todo">Undocumented.</p> + <p> + A description from the json schema def of the event goes here. + </p> + + <!-- PARAMETERS --> + <h4>Parameters</h4> + <dl> + <div> + <div> + </div> + </div> + </dl> + + </div> <!-- /decription --> + + </div> <!-- /apiItem --> + + </div> <!-- /apiGroup --> + + <!-- TYPES --> + <div class="apiGroup"> + <a name="types.sort(sortByName)"></a> + <h3 id="types">Types</h3> + + <!-- iterates over all types --> + <div class="apiItem"> + <a></a> + <h4>type name</h4> + + <div> + </div> + + </div> <!-- /apiItem --> + + </div> <!-- /apiGroup --> + + </div> <!-- /apiPage --> + </div> <!-- /gc-pagecontent --> + </div> <!-- /g-section --> + </div> <!-- /codesiteContent --> + <div id="gc-footer" --=""> + <div class="text"> + <p> + Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>, + the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons + Attribution 3.0 License</a>, and code samples are licensed under the + <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>. + </p> + <p> + ©2009 Google + </p> + +<!-- begin analytics --> +<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script> +<script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script> + +<script type="text/javascript"> + // chrome doc tracking + try { + var engdocs = _gat._getTracker("YT-10763712-2"); + engdocs._trackPageview(); + } catch(err) {} + + // code.google.com site-wide tracking + try { + _uacct="UA-18071-1"; + _uanchor=1; + _uff=0; + urchinTracker(); + } + catch(e) {/* urchinTracker not available. */} +</script> +<!-- end analytics --> + </div> + </div> <!-- /gc-footer --> + </div> <!-- /gc-container --> +</body></html> diff --git a/chrome/common/extensions/docs/i18n.html b/chrome/common/extensions/docs/i18n.html index d6ffd33..a7ecdc8 100644 --- a/chrome/common/extensions/docs/i18n.html +++ b/chrome/common/extensions/docs/i18n.html @@ -286,7 +286,7 @@ that it didn't originally support. <p> To internationalize your extension, you need to put all of its user-visible strings into a file -named <code>messages.json</code>. +named <a href="i18n-messages.html"><code>messages.json</code></a>. Each time you localize your extension you add a messages file under a directory @@ -303,7 +303,7 @@ Spanish (<code>es</code>), and Korean (<code>ko</code>): </p> -<img src="images/i18n-hierarchy.gif" alt="" width="385" height="77"> +<img src="images/i18n-hierarchy.gif" alt="In the extension directory: manifest.json, *.html, *.js, _locales directory. In the _locales directory: en, es, and ko directories, each with a messages.json file." width="385" height="77"> <h2 id="l10">How to support multiple languages</h2> @@ -313,7 +313,7 @@ Say you have an extension with the files shown in the following figure: </p> -<img src="images/i18n-before.gif" alt="" width="323" height="148"> +<img src="images/i18n-before.gif" alt="A manifest.json file and a file with JavaScript. The .json file has "name": "Hello World". The JavaScript file has title = "Hello World";" width="323" height="148"> <p> To internationalize this extension, @@ -328,7 +328,7 @@ Here's what the extension looks like when it's internationalized (note that it still has only English strings): </p> -<img src="images/i18n-after-1.gif" alt="" width="782" height="228"> +<img src="images/i18n-after-1.gif" alt="In the manifest.json file, "Hello World" has been changed to "__MSG_extName__", and a new "default_locale" item has the value "en". In the JavaScript file, "Hello World" has been changed to chrome.i18n.getMessage("extName"). A new file named _locales/en/messages.json defines "extName"." width="782" height="228"> <p class="note"> <b>Important:</b> @@ -388,11 +388,10 @@ Some notes about internationalizing extensions: ... }</pre> -<!-- +<p> For more information, see -<a href="message.html">Formats: Message Files</a>. -[PENDING: write this page!] ---> +<a href="i18n-messages.html">Formats: Locale-Specific Messages</a>. +</p> </li> </ul> @@ -409,7 +408,7 @@ The following figure shows the previous extension with a new Spanish translation. </p> -<img src="images/i18n-after-2.gif" alt="" width="782" height="358"> +<img src="images/i18n-after-2.gif" alt="This looks the same as the previous figure, but with a new file at _locales/es/messages.json that contains a Spanish translation of the messages." width="782" height="358"> <h2 id="overview-locales">Locales</h2> @@ -490,7 +489,9 @@ users running Google Chrome in any non-English language see the label "Colores" and the extension name "Hola mundo". </p> -<img src="images/i18n-strings.gif" alt="" width="493" height="488"> +<img src="images/i18n-strings.gif" alt="Four files: manifest.json, and messages.json files for es, en, and en_GB. + The es and en files show entries for messages named "extName" and "colores"; + the en_GB file has just one entry (for "colores")." width="493" height="488"> <h3 id="locales-testing">How to set your browser's locale</h3> @@ -678,8 +679,10 @@ status.innerText = chrome.i18n.getMessage("error", errorDetails); </pre> <p> -For more information about placeholders, -see the <a href="http://dev.chromium.org/developers/design-documents/extensions/i18n#TOC-Replacement-policy">internationalization design doc</a>. +For more information about placeholders, see the +<a href="i18n-messages.html">Locale-Specific Messages</a> page. +For details on calling <code>getMessage()</code>, see the +<a href="#method-getMessage">API reference</a>. </p> <h3 id="example-accept-languages">Example: getAcceptLanguages</h3> @@ -696,6 +699,11 @@ string by separating each accept-language with ','. } </pre> +<p> +For details on calling <code>getAcceptLanguages()</code>, see the +<a href="#method-getAcceptLanguages">API reference</a>. +</p> + <!-- END AUTHORED CONTENT --> </div> @@ -885,7 +893,7 @@ string by separating each accept-language with ','. <div class="description"> <p class="todo" style="display: none; ">Undocumented.</p> - <p>Gets the localized string for the specified message.</p> + <p>Gets the localized string for the specified message. If the message is missing, this method returns an empty string (''). If the format of the <code>getMessage()</code> call is wrong — for example, <em>messageName</em> is not a string or the <em>substitutions</em> array is empty or has more than 9 elements — this method returns <code>undefined</code>.</p> <!-- PARAMETERS --> <h4>Parameters</h4> @@ -919,7 +927,7 @@ string by separating each accept-language with ','. <dd class="todo" style="display: none; "> Undocumented. </dd> - <dd>The name of the message, as specified in the <code>messages.json</code> file.</dd> + <dd>The name of the message, as specified in the <a href="i18n-messages.html"><code>messages.json</code></a> file.</dd> <!-- OBJECT PROPERTIES --> <dd style="display: none; "> @@ -960,7 +968,7 @@ string by separating each accept-language with ','. <dd class="todo" style="display: none; "> Undocumented. </dd> - <dd>1 - 9 substitution parameters, if the message requires any.</dd> + <dd>1 - 9 substitution strings, if the message requires any.</dd> <!-- OBJECT PROPERTIES --> <dd style="display: none; "> diff --git a/chrome/common/extensions/docs/static/i18n-messages.html b/chrome/common/extensions/docs/static/i18n-messages.html new file mode 100755 index 0000000..7bb0693 --- /dev/null +++ b/chrome/common/extensions/docs/static/i18n-messages.html @@ -0,0 +1,325 @@ +<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> +</ul> + +<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> + + + diff --git a/chrome/common/extensions/docs/static/i18n.html b/chrome/common/extensions/docs/static/i18n.html index 419ee08..328fc5e 100644 --- a/chrome/common/extensions/docs/static/i18n.html +++ b/chrome/common/extensions/docs/static/i18n.html @@ -17,7 +17,7 @@ that it didn't originally support. <p> To internationalize your extension, you need to put all of its user-visible strings into a file -named <code>messages.json</code>. +named <a href="i18n-messages.html"><code>messages.json</code></a>. Each time you localize your extension you add a messages file under a directory @@ -34,7 +34,8 @@ Spanish (<code>es</code>), and Korean (<code>ko</code>): </p> -<img src="images/i18n-hierarchy.gif" alt="" +<img src="images/i18n-hierarchy.gif" + alt='In the extension directory: manifest.json, *.html, *.js, _locales directory. In the _locales directory: en, es, and ko directories, each with a messages.json file.' width="385" height="77" /> @@ -45,7 +46,8 @@ Say you have an extension with the files shown in the following figure: </p> -<img src="images/i18n-before.gif" alt="" +<img src="images/i18n-before.gif" + alt='A manifest.json file and a file with JavaScript. The .json file has "name": "Hello World". The JavaScript file has title = "Hello World";' width="323" height="148"> <p> @@ -61,7 +63,8 @@ Here's what the extension looks like when it's internationalized (note that it still has only English strings): </p> -<img src="images/i18n-after-1.gif" alt="" +<img src="images/i18n-after-1.gif" + alt='In the manifest.json file, "Hello World" has been changed to "__MSG_extName__", and a new "default_locale" item has the value "en". In the JavaScript file, "Hello World" has been changed to chrome.i18n.getMessage("extName"). A new file named _locales/en/messages.json defines "extName".' width="782" height="228"> <p class="note"> @@ -123,11 +126,10 @@ Some notes about internationalizing extensions: ... }</pre> -<!-- +<p> For more information, see -<a href="message.html">Formats: Message Files</a>. -[PENDING: write this page!] ---> +<a href="i18n-messages.html">Formats: Locale-Specific Messages</a>. +</p> </li> </ul> @@ -144,7 +146,8 @@ The following figure shows the previous extension with a new Spanish translation. </p> -<img src="images/i18n-after-2.gif" alt="" +<img src="images/i18n-after-2.gif" + alt='This looks the same as the previous figure, but with a new file at _locales/es/messages.json that contains a Spanish translation of the messages.' width="782" height="358"> @@ -226,7 +229,10 @@ users running Google Chrome in any non-English language see the label "Colores" and the extension name "Hola mundo". </p> -<img src="images/i18n-strings.gif" alt="" +<img src="images/i18n-strings.gif" + alt='Four files: manifest.json, and messages.json files for es, en, and en_GB. + The es and en files show entries for messages named "extName" and "colores"; + the en_GB file has just one entry (for "colores").' width="493" height="488" /> <h3 id="locales-testing">How to set your browser's locale</h3> @@ -418,8 +424,10 @@ status.innerText = chrome.i18n.getMessage("error", errorDetails); </pre> <p> -For more information about placeholders, -see the <a href="http://dev.chromium.org/developers/design-documents/extensions/i18n#TOC-Replacement-policy">internationalization design doc</a>. +For more information about placeholders, see the +<a href="i18n-messages.html">Locale-Specific Messages</a> page. +For details on calling <code>getMessage()</code>, see the +<a href="#method-getMessage">API reference</a>. </p> <h3 id="example-accept-languages">Example: getAcceptLanguages</h3> @@ -437,4 +445,9 @@ function getAcceptLanguages() { } </pre> +<p> +For details on calling <code>getAcceptLanguages()</code>, see the +<a href="#method-getAcceptLanguages">API reference</a>. +</p> + <!-- END AUTHORED CONTENT --> |