Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(3)

Issues Search
    My Issues | Starred     Open | Closed | All

Side by Side Diff: chrome/common/extensions/docs/i18n.html

Issue 525077: First pass at expanded i18n doc.... (Closed) Base URL: svn://chrome-svn/chrome/trunk/src/
Patch Set: '' Created 10 years, 11 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch | Annotate | Revision Log
« no previous file with comments | « chrome/common/extensions/docs/hosting.html ('k') | chrome/common/extensions/docs/images/i18n-after-1.gif » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 <!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note: 1 <!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note:
2 1) The <head> information in this page is significant, should be uniform 2 1) The <head> information in this page is significant, should be uniform
3 across api docs and should be edited only with knowledge of the 3 across api docs and should be edited only with knowledge of the
4 templating mechanism. 4 templating mechanism.
5 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a 5 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a
6 browser, it will be re-generated from the template, json schema and 6 browser, it will be re-generated from the template, json schema and
7 authored overview content. 7 authored overview content.
8 4) The <body>.innerHTML is also generated by an offline step so that this 8 4) The <body>.innerHTML is also generated by an offline step so that this
9 page may easily be indexed by search engines. 9 page may easily be indexed by search engines.
10 --><html xmlns="http://www.w3.org/1999/xhtml"><head> 10 --><html xmlns="http://www.w3.org/1999/xhtml"><head>
11 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 11 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
12 <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css"> 12 <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css">
13 <link href="css/print.css" rel="stylesheet" type="text/css" media="print"> 13 <link href="css/print.css" rel="stylesheet" type="text/css" media="print">
14 <script type="text/javascript" src="../../../third_party/jstemplate/jstempla te_compiled.js"> 14 <script type="text/javascript" src="../../../third_party/jstemplate/jstempla te_compiled.js">
15 </script> 15 </script>
16 <script type="text/javascript" src="js/api_page_generator.js"></script> 16 <script type="text/javascript" src="js/api_page_generator.js"></script>
17 <script type="text/javascript" src="js/bootstrap.js"></script> 17 <script type="text/javascript" src="js/bootstrap.js"></script>
18 <title>i18n - Google Chrome Extensions - Google Code</title></head><body> <di v id="gc-container" class="labs"> 18 <title>Internationalization (i18n) - Google Chrome Extensions - Google Code</t itle></head><body> <div id="gc-container" class="labs">
19 <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION --> 19 <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION -->
20 <!-- In particular, sub-templates that recurse, must be used by allowing 20 <!-- In particular, sub-templates that recurse, must be used by allowing
21 jstemplate to make a copy of the template in this section which 21 jstemplate to make a copy of the template in this section which
22 are not operated on by way of the jsskip="true" --> 22 are not operated on by way of the jsskip="true" -->
23 <div style="display:none"> 23 <div style="display:none">
24 24
25 <!-- VALUE --> 25 <!-- VALUE -->
26 <div id="valueTemplate"> 26 <div id="valueTemplate">
27 <dt> 27 <dt>
28 <var>paramName</var> 28 <var>paramName</var>
(...skipping 115 matching lines...) Expand 10 before | Expand all | Expand 10 after
144 <li><a href="events.html">Events</a></li> 144 <li><a href="events.html">Events</a></li>
145 <li><a href="tabs.html">Tabs</a></li> 145 <li><a href="tabs.html">Tabs</a></li>
146 <li><a href="windows.html">Windows</a></li> 146 <li><a href="windows.html">Windows</a></li>
147 </ul> 147 </ul>
148 </li> 148 </li>
149 <li>Implementation 149 <li>Implementation
150 <ul> 150 <ul>
151 <li><a href="background_pages.html">Background Pages</a></li> 151 <li><a href="background_pages.html">Background Pages</a></li>
152 <li><a href="content_scripts.html">Content Scripts</a></li> 152 <li><a href="content_scripts.html">Content Scripts</a></li>
153 <li><a href="xhr.html">Cross-Origin XHR</a></li> 153 <li><a href="xhr.html">Cross-Origin XHR</a></li>
154 <li class="leftNavSelected">Internationalization</li>
154 <li><a href="messaging.html">Message Passing</a></li> 155 <li><a href="messaging.html">Message Passing</a></li>
155 <li><a href="npapi.html">NPAPI Plugins</a></li> 156 <li><a href="npapi.html">NPAPI Plugins</a></li>
156 </ul> 157 </ul>
157 </li> 158 </li>
158 <li>Finishing 159 <li>Finishing
159 <ul> 160 <ul>
160 <li><a href="autoupdate.html">Autoupdating</a></li> 161 <li><a href="autoupdate.html">Autoupdating</a></li>
161 <li><a href="packaging.html">Packaging</a></li> 162 <li><a href="packaging.html">Packaging</a></li>
162 </ul> 163 </ul>
163 </li> 164 </li>
(...skipping 16 matching lines...) Expand all
180 <li><a href="api_index.html">chrome.* APIs</a></li> 181 <li><a href="api_index.html">chrome.* APIs</a></li>
181 <li><a href="api_other.html">Other APIs</a></li> 182 <li><a href="api_other.html">Other APIs</a></li>
182 </ul> 183 </ul>
183 </li> 184 </li>
184 <li><h2><a href="samples.html">Samples</a></h2></li> 185 <li><h2><a href="samples.html">Samples</a></h2></li>
185 </ul> 186 </ul>
186 </div> 187 </div>
187 188
188 <div class="g-unit" id="gc-pagecontent"> 189 <div class="g-unit" id="gc-pagecontent">
189 <div id="pageTitle"> 190 <div id="pageTitle">
190 <h1 class="page_title">i18n</h1> 191 <h1 class="page_title">Internationalization (i18n)</h1>
191 </div> 192 </div>
192 <!-- TABLE OF CONTENTS --> 193 <!-- TABLE OF CONTENTS -->
193 <div id="toc"> 194 <div id="toc">
194 <h2>Contents</h2> 195 <h2>Contents</h2>
195 <ol> 196 <ol>
196 <li> 197 <li>
197 <a href="#overview-examples">Examples</a> 198 <a href="#l10">How to support multiple languages</a>
198 <ol> 199 <ol>
199 <li style="display: none; "> 200 <li style="display: none; ">
200 <a>h3Name</a> 201 <a>h3Name</a>
201 </li> 202 </li>
202 </ol> 203 </ol>
204 </li><li>
205 <a href="#overview-locales">Locales</a>
206 <ol>
207 <li>
208 <a href="#locales-supported">Supported locales</a>
209 </li><li>
210 <a href="#locales-usage">How extensions find strings</a>
211 </li><li>
212 <a href="#locales-testing">How to set your browser's locale</a >
213 </li>
214 </ol>
215 </li><li>
216 <a href="#overview-examples">Examples</a>
217 <ol>
218 <li>
219 <a href="#examples-getMessage">Examples: getMessage</a>
220 </li><li>
221 <a href="#example-accept-languages">Example: getAcceptLanguage s</a>
222 </li>
223 </ol>
203 </li> 224 </li>
204 <li> 225 <li>
205 <a href="#apiReference">API reference: chrome.i18n</a> 226 <a href="#apiReference">API reference: chrome.i18n</a>
206 <ol> 227 <ol>
207 <li style="display: none; "> 228 <li style="display: none; ">
208 <a href="#properties">Properties</a> 229 <a href="#properties">Properties</a>
209 <ol> 230 <ol>
210 <li> 231 <li>
211 <a href="#property-anchor">propertyName</a> 232 <a href="#property-anchor">propertyName</a>
212 </li> 233 </li>
(...skipping 25 matching lines...) Expand all
238 </li> 259 </li>
239 </ol> 260 </ol>
240 </li> 261 </li>
241 </ol> 262 </ol>
242 </li> 263 </li>
243 </ol> 264 </ol>
244 </div> 265 </div>
245 <!-- /TABLE OF CONTENTS --> 266 <!-- /TABLE OF CONTENTS -->
246 267
247 <!-- STATIC CONTENT PLACEHOLDER --> 268 <!-- STATIC CONTENT PLACEHOLDER -->
248 <div id="static"><div id="pageData-name" class="pageData">i18n</div> 269 <div id="static"><div id="pageData-name" class="pageData">Internationali zation (i18n)</div>
270
271 <!--
272 [NOTEs for editors:
273 * Try to be consistent about string vs. message
274 -->
249 275
250 <!-- BEGIN AUTHORED CONTENT --> 276 <!-- BEGIN AUTHORED CONTENT -->
251 <p id="classSummary"> 277 <p id="classSummary">
252 Use the <code>chrome.i18n</code> module to manipulate the i18n related browser 278 Use the <code>chrome.i18n</code> module to
253 settings, such as the accept languages. 279 get localized messages for the current locale,
254 <!-- [PENDING: add when getMessage works: "or to get localized messages for the current locale."] --> 280 from either the extension or its content script.
255 </p> 281 You can also use this module to get the languages that the browser accepts.
282 </p>
283
284 <h2 id="l10">How to support multiple languages</h2>
285
286 <p>
287 To simplify translating your extension,
288 <em>internationalize</em> it by
289 putting all its user-visible strings
290 in a file named <code>messages.json</code>.
291 For example, let's say you have an extension
292 with the files shown in the following figure:
293 </p>
294
295 <img src="images/i18n-before.gif" alt="" width="" height="">
296
297 <p>
298 To internationalize this extension,
299 put each user-visible string into a messages file.
300 For an extension that's in English,
301 the messages file can be at
302 <code>_locales/en/messages.json</code>.
303 Each message has a name.
304 The extension's manifest and JavaScript code
305 use this name to get the localized message.
306 </p>
307
308 <p>
309 The next figure shows an internationalized extension
310 that has only English strings.
311 </p>
312
313 <img src="images/i18n-after-1.gif" alt="" width="" height="">
314
315 <p class="note">
316 <b>Important:</b>
317 If an extension has a <code>_locales</code> directory,
318 the <a href="manifest.html">manifest</a>
319 <b>must</b> define "default_locale".
320 </p>
321
322 <p>
323 Once an extension is internationalized,
324 translating it is simple.
325 You just copy <code>messages.json</code>,
326 translate it,
327 and put the copy into a new directory under <code>_locales</code>.
328 For example, to support Spanish,
329 just put the translated copy of <code>messages.json</code>
330 under <code>_locales/es</code>.
331 The following figure shows the extension with a new Spanish translation.
332 </p>
333
334 <img src="images/i18n-after-2.gif" alt="" width="" height="">
335
336 <p>
337 Some notes about internationalizing extensions:
338 </p>
339
340 <ul>
341 <li><p>
342 Use only <a href="#overview-locales">supported locales</a>!
343 </p></li>
344
345 <li>
346 In <code>manifest.json</code>,
347 refer to a string named <em>messagename</em> like this:
348 <pre>__MSG_<em>messagename</em>__</pre>
349 </li>
350
351 <li>
352 In your extension's JavaScript code,
353 refer to a string named <em>messagename</em>
354 like this:
355 <pre>chrome.i18n.getMessage("<em>messagename</em>")</pre>
356
357 </li><li> <p>
358 In each call to <code>getMessage()</code>,
359 you can supply up to 9 strings
360 to be included in the message.
361 See <a href="#examples-getMessage">Examples: getMessage</a>
362 for details.
363 </p>
364 </li>
365
366 <li>
367 In <code>messages.json</code>,
368 each user-visible string has a name, a "message" item,
369 and an optional "description" item.
370 The name is a key
371 such as "extName" or "search_string"
372 that identifies the string.
373 The "message" specifies
374 the value of the string in this locale.
375 The optional "description"
376 provides help to translators,
377 who might not be able to see how the string is used in your extension.
378 For example:
379 <pre>{
380 "search_string": {
381 "message": "hello%20world",
382 "description": "The string we search for. Put %20 between words that go toge ther."
383 },
384 ...
385 }</pre>
386 </li>
387
388 </ul>
389
390 <!--
391 For more information, see
392 <a href="message.html">Formats: Message Files</a>.
393 [PENDING: write this page!]
394 -->
395
396 <h2 id="overview-locales">Locales</h2>
397
398 <p>
399 Extensions can use all the locales that Google Chrome supports,
400 plus a few (such as <code>en</code>)
401 that let a single translation support multiple variations of a language
402 (such as <code>en_GB</code> and <code>en_US</code>).
403 </p>
404
405
406 <h3 id="locales-supported">Supported locales</h3>
407
408 <p>
409 Your extension can use any of the following locales:
410 </p>
411
412 <p>
413 <code>am ar bg bn ca cs da de el en en_GB en_US es es_419 et fi fil fr gu he hi hr hu id it ja kn ko lt
414 lv ml mr nb nl or pl pt pt_BR pt_PT ro ru sk sl sr sv sw ta te th tr uk vi zh zh_CN zh_TW</code>
415 </p>
416
417
418 <h3 id="locales-usage">How extensions find strings</h3>
419
420 <p>
421 You don't have to define every string for every locale
422 that your internationalized extension supports.
423 As long as the default locale's <code>messages.json</code> file
424 has a value for every string,
425 your extension will run no matter how sparse a translation is.
426 Here's how the extension system searches for a message:
427 </p>
428
429 <ol>
430 <li>
431 Search the messages file (if any)
432 for the user's preferred locale.
433 For example, when Google Chrome's locale is set to
434 British English (<code>en_GB</code>),
435 the system first looks for the message in
436 <code>_locales/en_GB/messages.json</code>.
437 If that file exists and the message is there,
438 the system looks no further.
439 </li>
440 <li>
441 If the user's preferred locale has a region
442 (that is, the locale has an underscore: _),
443 search the locale without that region.
444 For example, if the <code>en_GB</code> messages file
445 doesn't exist or doesn't contain the message,
446 the system looks in the <code>en</code> messages file.
447 If that file exists and the message is there,
448 the system looks no further.
449 </li>
450 <li>
451 Search the messages file for the extension's default locale.
452 For example, if the extension's "default_locale" is set to "es",
453 and neither <code>_locales/en_GB/messages.json</code>
454 nor <code>_locales/en/messages.json</code> contains the message,
455 the extension uses the message from
456 <code>_locales/es/messages.json</code>.
457 </li>
458 </ol>
459
460 <p>
461 In the following figure,
462 the message named "color" is in all three locales
463 that the extension supports,
464 but "extName" is in only two of the locales.
465 Where a user running Google Chrome in US English sees the heading "Color",
466 a user running it in British English sees "Colour".
467 Both US English and British English users
468 see the extension name "Hello World".
469 Because the default language is Spanish,
470 users running Google Chrome in any non-English language
471 see the heading "Color" and the extension name "Hola mundo".
472 </p>
473
474 <img src="images/i18n-strings.gif" alt="" width="496" height="490">
475
476 <h3 id="locales-testing">How to set your browser's locale</h3>
477
478 <p>
479 When you test translations, you might want to set your browser's locale.
480 Here's how.
481 </p>
482
483 <h4 id="testing-win">Windows</h4>
484
485 <ol>
486 <li> Tools menu (wrench) &gt; <b>Options</b> </li>
487 <li> Choose the <b>Under the Hood</b> tab </li>
488 <li> Scroll down to <b>Web Content</b> </li>
489 <li> Click <b>Change font and language settings</b> </li>
490 <li> Choose the <b>Languages</b> tab </li>
491 <li> Use the drop down to set the <b>Google Chrome language</b> </li>
492 <li> Restart Chrome </li>
493 </ol>
494
495 <h4 id="testing-mac">Mac OS X</h4>
496
497 <ol>
498 <li> From the Apple menu, choose <b>System Preferences</b> </li>
499 <li> Under the <b>Personal</b> section, choose <b>International</b> </li>
500 <li> Choose your language and location </li>
501 <li> Restart Chrome </li>
502 </ol>
503
504 <h4 id="testing-linux">Linux</h4>
505
506 <p>
507 Set the language environment variable, and then launch Google Chrome.
508 For example:
509 </p>
510
511 <pre>LANGUAGE=es ./chrome
512 </pre>
513
256 514
257 <h2 id="overview-examples">Examples</h2> 515 <h2 id="overview-examples">Examples</h2>
258 516
259 <p> 517 <p>
518 You can find simple examples of internationalization in the
519 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extension s/docs/examples/api/i18n/">examples/api/i18n</a>
520 directory.
521 For a more complete example, see
522 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extension s/docs/examples/extensions/news_i18n/">examples/extensions/news_i18n</a>
523 (compare it to
524 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extension s/docs/examples/extensions/news/">examples/extensions/news</a>).
525 For other examples and for help in viewing the source code, see
526 <a href="samples.html">Samples</a>.
527 </p>
528
529
530 <h3 id="examples-getMessage">Examples: getMessage</h3>
531
532 <!--
533 [PENDING: improve this section. it should probably start with a
534 one-variable example that includes the messages.json code.]
535 -->
536
537 <p>
538 The following code gets a localized message from the browser
539 and displays it as a string.
540 It replaces two placeholders within the message with the strings
541 "string1" and "string2".
542 </p>
543
544 <pre>function getMessage() {
545 var message = chrome.i18n.getMessage("click_here", ["string1", "string2"]);
546 document.getElementById("languageSpan").innerHTML = message;
547 }
548 </pre>
549
550 <p>
551 Here's how you'd supply and use a single string:
552 </p>
553
554 <pre><em>// In JavaScript code</em>
555 status.innerText = chrome.i18n.getMessage("error", errorDetails);
556
557 <em>// In messages.json</em>
558 "error": {
559 "message": "Error: $details$",
560 "description": "Generic error template. Expects error parameter to be passed i n.",
561 "placeholders": {
562 "details": {
563 "content": "$1",
564 "example": "Failed to fetch RSS feed."
565 }
566 }
567 }
568 </pre>
569
570 <p>
571 For more information about placeholders,
572 see the <a href="http://dev.chromium.org/developers/design-documents/extensions/ i18n#TOC-Replacement-policy">internationalization design doc</a>.
573 </p>
574
575 <h3 id="example-accept-languages">Example: getAcceptLanguages</h3>
576 <p>
260 The following code gets accept-languages from the browser and displays them as a 577 The following code gets accept-languages from the browser and displays them as a
261 string by separating each accept-language with ','. 578 string by separating each accept-language with ','.
262 </p> 579 </p>
263 580
264 <pre>function getAcceptLanguages() { 581 <pre>function getAcceptLanguages() {
265 chrome.i18n.getAcceptLanguages(function(languageList) { 582 chrome.i18n.getAcceptLanguages(function(languageList) {
266 var languages = languageList.join(","); 583 var languages = languageList.join(",");
267 document.getElementById("languageSpan").innerHTML = languages; 584 document.getElementById("languageSpan").innerHTML = languages;
268 }) 585 })
269 } 586 }
270 </pre> 587 </pre>
271 588
272 <!-- [PENDING: add the following when getMessage is working]
273 <p>
274 The following code gets a localized message from the browser and displays it as a
275 string. It replaces two placeholders within the message with values arg1 and
276 arg2.
277 </p>
278
279 <pre>
280 function getMessage() {
281 var message = chrome.i18n.getMessage("click_here", ["arg1", "arg2"]);
282 document.getElementById("languageSpan").innerHTML = message;
283 }
284 </pre>
285 -->
286
287 <p>
288 You can find simple examples of internationalization in the
289 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extension s/docs/examples/api/i18n/">examples/api/i18n</a>
290 directory.
291 For other examples and for help in viewing the source code, see
292 <a href="samples.html">Samples</a>.
293 </p>
294
295 <!-- END AUTHORED CONTENT --> 589 <!-- END AUTHORED CONTENT -->
296 </div> 590 </div>
297 591
298 <!-- API PAGE --> 592 <!-- API PAGE -->
299 <div class="apiPage"> 593 <div class="apiPage">
300 <a name="apiReference"></a> 594 <a name="apiReference"></a>
301 <h2>API reference: chrome.i18n</h2> 595 <h2>API reference: chrome.i18n</h2>
302 596
303 <!-- PROPERTIES --> 597 <!-- PROPERTIES -->
304 <div class="apiGroup" style="display: none; "> 598 <div class="apiGroup" style="display: none; ">
(...skipping 430 matching lines...) Expand 10 before | Expand all | Expand 10 after
735 _uff=0; 1029 _uff=0;
736 urchinTracker(); 1030 urchinTracker();
737 } 1031 }
738 catch(e) {/* urchinTracker not available. */} 1032 catch(e) {/* urchinTracker not available. */}
739 </script> 1033 </script>
740 <!-- end analytics --> 1034 <!-- end analytics -->
741 </div> 1035 </div>
742 </div> <!-- /gc-footer --> 1036 </div> <!-- /gc-footer -->
743 </div> <!-- /gc-container --> 1037 </div> <!-- /gc-container -->
744 </body></html> 1038 </body></html>
OLDNEW
« no previous file with comments | « chrome/common/extensions/docs/hosting.html ('k') | chrome/common/extensions/docs/images/i18n-after-1.gif » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698