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 3 across api docs and should be edited only with knowledge of the 4 templating mechanism. 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 7 authored overview content. 8 4) The <body>.innerHTML is also generated by an offline step so that this 9 page may easily be indexed by search engines. 10 --><html xmlns="http://www.w3.org/1999/xhtml"><head> 11 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 12 <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css"> 13 <link href="css/print.css" rel="stylesheet" type="text/css" media="print"> 14 <script type="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.js"> 15 </script> 16 <script type="text/javascript" src="js/api_page_generator.js"></script> 17 <script type="text/javascript" src="js/bootstrap.js"></script> 18 <script type="text/javascript" src="js/sidebar.js"></script> 19 <title>Internationalization (i18n) - Google Chrome Extensions - Google Code</title></head> 20 <body> <div id="gc-container" class="labs"> 21 <div id="devModeWarning"> 22 You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files. 23 </div> 24 <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION --> 25 <!-- In particular, sub-templates that recurse, must be used by allowing 26 jstemplate to make a copy of the template in this section which 27 are not operated on by way of the jsskip="true" --> 28 <div style="display:none"> 29 30 <!-- VALUE --> 31 <div id="valueTemplate"> 32 <dt> 33 <var>paramName</var> 34 <em> 35 36 <!-- TYPE --> 37 <div style="display:inline"> 38 ( 39 <span class="optional">optional</span> 40 <span class="enum">enumerated</span> 41 <span id="typeTemplate"> 42 <span> 43 <a> Type</a> 44 </span> 45 <span> 46 <span> 47 array of <span><span></span></span> 48 </span> 49 <span>paramType</span> 50 <span></span> 51 </span> 52 </span> 53 ) 54 </div> 55 56 </em> 57 </dt> 58 <dd class="todo"> 59 Undocumented. 60 </dd> 61 <dd> 62 Description of this parameter from the json schema. 63 </dd> 64 <dd> 65 This parameter was added in version 66 <b><span></span></b>. 67 You must omit this parameter in earlier versions, 68 and you may omit it in any version. If you require this 69 parameter, the manifest key 70 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 71 can ensure that your extension won't be run in an earlier browser version. 72 </dd> 73 74 <!-- OBJECT PROPERTIES --> 75 <dd> 76 <dl> 77 <div> 78 <div> 79 </div> 80 </div> 81 </dl> 82 </dd> 83 84 <!-- OBJECT METHODS --> 85 <dd> 86 <div></div> 87 </dd> 88 89 <!-- OBJECT EVENT FIELDS --> 90 <dd> 91 <div></div> 92 </dd> 93 94 <!-- FUNCTION PARAMETERS --> 95 <dd> 96 <div></div> 97 </dd> 98 99 </div> <!-- /VALUE --> 100 101 <div id="functionParametersTemplate"> 102 <h5>Parameters</h5> 103 <dl> 104 <div> 105 <div> 106 </div> 107 </div> 108 </dl> 109 </div> 110 </div> <!-- /SUBTEMPLATES --> 111 112 <a id="top"></a> 113 <div id="skipto"> 114 <a href="#gc-pagecontent">Skip to page content</a> 115 <a href="#gc-toc">Skip to main navigation</a> 116 </div> 117 <!-- API HEADER --> 118 <table id="header" width="100%" cellspacing="0" border="0"> 119 <tbody><tr> 120 <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> 121 <td valign="middle" width="100%" style="padding-left:0.6em;"> 122 <form action="http://www.google.com/cse" id="cse" style="margin-top:0.5em"> 123 <div id="gsc-search-box"> 124 <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno"> 125 <input type="hidden" name="ie" value="UTF-8"> 126 <input type="text" name="q" value="" size="55"> 127 <input class="gsc-search-button" type="submit" name="sa" value="Search"> 128 <br> 129 <span class="greytext">e.g. "page action" or "tabs"</span> 130 </div> 131 </form> 132 133 <script type="text/javascript" src="http://www.google.com/jsapi"></script> 134 <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script> 135 <script type="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse&t13n_langs=en"></script> 136 <script type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse&lang=en"></script> 137 </td> 138 </tr> 139 </tbody></table> 140 141 <div id="codesiteContent" class=""> 142 143 <a id="gc-topnav-anchor"></a> 144 <div id="gc-topnav"> 145 <h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Labs</a>)</h1> 146 <ul id="home" class="gc-topnav-tabs"> 147 <li id="home_link"> 148 <a href="index.html" title="Google Chrome Extensions home page">Home</a> 149 </li> 150 <li id="docs_link"> 151 <a href="docs.html" title="Official Google Chrome Extensions documentation">Docs</a> 152 </li> 153 <li id="faq_link"> 154 <a href="faq.html" title="Answers to frequently asked questions about Google Chrome Extensions">FAQ</a> 155 </li> 156 <li id="samples_link"> 157 <a href="samples.html" title="Sample extensions (with source code)">Samples</a> 158 </li> 159 <li id="group_link"> 160 <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions" title="Google Chrome Extensions developer forum">Group</a> 161 </li> 162 </ul> 163 </div> <!-- end gc-topnav --> 164 165 <div class="g-section g-tpl-170"> 166 <!-- SIDENAV --> 167 <div class="g-unit g-first" id="gc-toc"> 168 <ul> 169 <li><a href="getstarted.html">Getting Started</a></li> 170 <li><a href="overview.html">Overview</a></li> 171 <li><a href="whats_new.html">What's New?</a></li> 172 <li><h2><a href="devguide.html">Developer's Guide</a></h2> 173 <ul> 174 <li>Browser UI 175 <ul> 176 <li><a href="browserAction.html">Browser Actions</a></li> 177 <li><a href="contextMenus.html">Context Menus</a></li> 178 <li><a href="notifications.html">Desktop Notifications</a></li> 179 <li><a href="omnibox.html">Omnibox</a></li> 180 <li><a href="options.html">Options Pages</a></li> 181 <li><a href="override.html">Override Pages</a></li> 182 <li><a href="pageAction.html">Page Actions</a></li> 183 </ul> 184 </li> 185 <li>Browser Interaction 186 <ul> 187 <li><a href="bookmarks.html">Bookmarks</a></li> 188 <li><a href="cookies.html">Cookies</a></li> 189 <li><a href="events.html">Events</a></li> 190 <li><a href="history.html">History</a></li> 191 <li><a href="management.html">Management</a></li> 192 <li><a href="tabs.html">Tabs</a></li> 193 <li><a href="windows.html">Windows</a></li> 194 </ul> 195 </li> 196 <li>Implementation 197 <ul> 198 <li><a href="a11y.html">Accessibility</a></li> 199 <li><a href="background_pages.html">Background Pages</a></li> 200 <li><a href="content_scripts.html">Content Scripts</a></li> 201 <li><a href="xhr.html">Cross-Origin XHR</a></li> 202 <li><a href="idle.html">Idle</a></li> 203 <li class="leftNavSelected">Internationalization</li> 204 <li><a href="messaging.html">Message Passing</a></li> 205 <li><a href="npapi.html">NPAPI Plugins</a></li> 206 </ul> 207 </li> 208 <li>Finishing 209 <ul> 210 <li><a href="hosting.html">Hosting</a></li> 211 <li><a href="external_extensions.html">Other Deployment Options</a></li> 212 </ul> 213 </li> 214 </ul> 215 </li> 216 <li><h2><a href="apps.html">Packaged Apps</a></h2></li> 217 <li><h2><a href="tutorials.html">Tutorials</a></h2> 218 <ul> 219 <li><a href="tut_debugging.html">Debugging</a></li> 220 <li><a href="tut_analytics.html">Google Analytics</a></li> 221 <li><a href="tut_oauth.html">OAuth</a></li> 222 </ul> 223 </li> 224 <li><h2>Reference</h2> 225 <ul> 226 <li>Formats 227 <ul> 228 <li><a href="manifest.html">Manifest Files</a></li> 229 <li><a href="match_patterns.html">Match Patterns</a></li> 230 </ul> 231 </li> 232 <li><a href="permission_warnings.html">Permission Warnings</a></li> 233 <li><a href="api_index.html">chrome.* APIs</a></li> 234 <li><a href="api_other.html">Other APIs</a></li> 235 </ul> 236 </li> 237 <li><h2><a href="samples.html">Samples</a></h2></li> 238 <div class="line"> </div> 239 <li><h2>More</h2> 240 <ul> 241 <li><a href="http://code.google.com/chrome/webstore/docs/index.html">Chrome Web Store</a></li> 242 <li><a href="http://code.google.com/chrome/apps/docs/developers_guide.html">Hosted Apps</a></li> 243 <li><a href="themes.html">Themes</a></li> 244 </ul> 245 </li> 246 </ul> 247 </div> 248 <script> 249 initToggles(); 250 </script> 251 252 <div class="g-unit" id="gc-pagecontent"> 253 <div id="pageTitle"> 254 <h1 class="page_title">Internationalization (i18n)</h1> 255 </div> 256 <!-- TABLE OF CONTENTS --> 257 <div id="toc"> 258 <h2>Contents</h2> 259 <ol> 260 <li> 261 <a href="#l10">How to support multiple languages</a> 262 <ol> 263 <li style="display: none; "> 264 <a>h3Name</a> 265 </li> 266 </ol> 267 </li><li> 268 <a href="#overview-predefined">Predefined messages</a> 269 <ol> 270 <li style="display: none; "> 271 <a>h3Name</a> 272 </li> 273 </ol> 274 </li><li> 275 <a href="#overview-locales">Locales</a> 276 <ol> 277 <li> 278 <a href="#locales-supported">Supported locales</a> 279 </li><li> 280 <a href="#locales-usage">How extensions find strings</a> 281 </li><li> 282 <a href="#locales-testing">How to set your browser's locale</a> 283 </li> 284 </ol> 285 </li><li> 286 <a href="#overview-examples">Examples</a> 287 <ol> 288 <li> 289 <a href="#examples-getMessage">Examples: getMessage</a> 290 </li><li> 291 <a href="#example-accept-languages">Example: getAcceptLanguages</a> 292 </li> 293 </ol> 294 </li> 295 <li> 296 <a href="#apiReference">API reference: chrome.i18n</a> 297 <ol> 298 <li style="display: none; "> 299 <a href="#properties">Properties</a> 300 <ol> 301 <li> 302 <a href="#property-anchor">propertyName</a> 303 </li> 304 </ol> 305 </li> 306 <li> 307 <a href="#global-methods">Methods</a> 308 <ol> 309 <li> 310 <a href="#method-getAcceptLanguages">getAcceptLanguages</a> 311 </li><li> 312 <a href="#method-getMessage">getMessage</a> 313 </li> 314 </ol> 315 </li> 316 <li style="display: none; "> 317 <a>Events</a> 318 <ol> 319 <li> 320 <a href="#event-anchor">eventName</a> 321 </li> 322 </ol> 323 </li> 324 <li style="display: none; "> 325 <a href="#types">Types</a> 326 <ol> 327 <li> 328 <a href="#id-anchor">id</a> 329 </li> 330 </ol> 331 </li> 332 </ol> 333 </li> 334 </ol> 335 </div> 336 <!-- /TABLE OF CONTENTS --> 337 338 <!-- Standard content lead-in for experimental API pages --> 339 <p id="classSummary" style="display: none; "> 340 For information on how to use experimental APIs, see the <a href="experimental.html">chrome.experimental.* APIs</a> page. 341 </p> 342 343 <!-- STATIC CONTENT PLACEHOLDER --> 344 <div id="static"><div id="pageData-name" class="pageData">Internationalization (i18n)</div> 345 346 <!-- 347 [NOTEs for editors: 348 * Try to be consistent about string vs. message (it's probably not yet). 349 --> 350 351 <!-- BEGIN AUTHORED CONTENT --> 352 <p id="classSummary"> 353 An <em>internationalized</em> extension 354 can be easily 355 <em>localized</em> 356 adapted to languages and regions 357 that it didn't originally support. 358 </p> 359 360 <p> 361 To internationalize your extension, 362 you need to put all of its user-visible strings into a file 363 named <a href="i18n-messages.html"><code>messages.json</code></a>. 364 Each time you localize your extension 365 you add a messages file 366 under a directory 367 named <code>_locales/<em>localeCode</em></code>, 368 where <em>localeCode</em> is a code such as 369 <code>en</code> for English. 370 </p> 371 372 <p> 373 Here's the file hierarchy 374 for an internationalized extension that supports 375 English (<code>en</code>), 376 Spanish (<code>es</code>), and 377 Korean (<code>ko</code>): 378 </p> 379 380 <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"> 381 382 383 <h2 id="l10">How to support multiple languages</h2> 384 385 <p> 386 Say you have an extension 387 with the files shown in the following figure: 388 </p> 389 390 <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"> 391 392 <p> 393 To internationalize this extension, 394 you name each user-visible string 395 and put it into a messages file. 396 The extension's manifest, 397 CSS files, 398 and JavaScript code 399 use each string's name to get its localized version. 400 </p> 401 402 <p> 403 Here's what the extension looks like when it's internationalized 404 (note that it still has only English strings): 405 </p> 406 407 <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"> 408 409 <p class="note"> 410 <b>Important:</b> 411 If an extension has a <code>_locales</code> directory, 412 the <a href="manifest.html">manifest</a> 413 <b>must</b> define "default_locale". 414 </p> 415 416 <p> 417 Some notes about internationalizing extensions: 418 </p> 419 420 <ul> 421 <li><p> 422 You can use any of the <a href="#overview-locales">supported locales</a>. 423 If you use an unsupported locale, 424 Google Chrome ignores it. 425 </p></li> 426 427 <li> 428 In <code>manifest.json</code> 429 and CSS files, 430 refer to a string named <em>messagename</em> like this: 431 <pre>__MSG_<em>messagename</em>__</pre> 432 </li> 433 434 <li> 435 In your extension's JavaScript code, 436 refer to a string named <em>messagename</em> 437 like this: 438 <pre>chrome.i18n.getMessage("<em>messagename</em>")</pre> 439 440 </li><li> <p> 441 In each call to <code>getMessage()</code>, 442 you can supply up to 9 strings 443 to be included in the message. 444 See <a href="#examples-getMessage">Examples: getMessage</a> 445 for details. 446 </p> 447 </li> 448 449 <li><p> 450 Some messages, such as <code>@@bidi_dir</code> and <code>@@ui_locale</code>, 451 are provided by the internationalization system. 452 See the <a href="#overview-predefined">Predefined messages</a> section 453 for a full list of predefined message names. 454 </p> 455 </li> 456 457 <li> 458 In <code>messages.json</code>, 459 each user-visible string has a name, a "message" item, 460 and an optional "description" item. 461 The name is a key 462 such as "extName" or "search_string" 463 that identifies the string. 464 The "message" specifies 465 the value of the string in this locale. 466 The optional "description" 467 provides help to translators, 468 who might not be able to see how the string is used in your extension. 469 For example: 470 <pre>{ 471 "search_string": { 472 "message": "hello%20world", 473 "description": "The string we search for. Put %20 between words that go together." 474 }, 475 ... 476 }</pre> 477 478 <p> 479 For more information, see 480 <a href="i18n-messages.html">Formats: Locale-Specific Messages</a>. 481 </p> 482 </li> 483 </ul> 484 485 <p> 486 Once an extension is internationalized, 487 translating it is simple. 488 You copy <code>messages.json</code>, 489 translate it, 490 and put the copy into a new directory under <code>_locales</code>. 491 For example, to support Spanish, 492 just put a translated copy of <code>messages.json</code> 493 under <code>_locales/es</code>. 494 The following figure shows the previous extension 495 with a new Spanish translation. 496 </p> 497 498 <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"> 499 500 501 <h2 id="overview-predefined">Predefined messages</h2> 502 503 <p> 504 The internationalization system provides a few predefined 505 messages to help you localize your extension. 506 These include <code>@@ui_locale</code>, 507 so you can detect the current UI locale, 508 and a few <code>@@bidi_...</code> messages 509 that let you detect the text direction. 510 The latter messages have similar names to constants in the 511 <a href="http://code.google.com/apis/gadgets/docs/i18n.html#BIDI"> 512 gadgets BIDI (bi-directional) API</a>. 513 </p> 514 515 <p> 516 The special message <code>@@extension_id</code> 517 can be used in the CSS and JavaScript files of any extension, 518 whether or not the extension is localized. 519 This message doesn't work in manifest files. 520 </p> 521 522 <p class="note"> 523 <b>Note:</b> 524 Content script CSS files can't use 525 predefined messages such as <code>@@extension_id</code>. 526 For details, see 527 <a href="http://crbug.com/39899">bug 39899</a>. 528 </p> 529 530 <p> 531 The following table describes each predefined message. 532 </p> 533 534 <table> 535 <tbody><tr> 536 <th>Message name</th> <th>Description</th> 537 </tr> 538 <tr> 539 <td> <code>@@extension_id</code> </td> 540 <td>The extension ID; 541 you might use this string to construct URLs 542 for resources inside the extension. 543 Even unlocalized extensions can use this message. 544 <br> 545 <b>Note:</b> You can't use this message in a manifest file. 546 </td> 547 </tr> 548 <tr> 549 <td> <code>@@ui_locale</code> </td> 550 <td>The current locale; 551 you might use this string to construct locale-specific URLs. </td> 552 </tr> 553 <tr> 554 <td> <code>@@bidi_dir</code> </td> 555 <td> The text direction for the current locale, 556 either "ltr" for left-to-right languages such as English 557 or "rtl" for right-to-left languages such as Japanese. </td> 558 </tr> 559 <tr> 560 <td> <code>@@bidi_reversed_dir</code> </td> 561 <td> If the <code>@@bidi_dir</code> is "ltr", then this is "rtl"; 562 otherwise, it's "ltr". </td> 563 </tr> 564 <tr> 565 <td> <code>@@bidi_start_edge</code> </td> 566 <td> If the <code>@@bidi_dir</code> is "ltr", then this is "left"; 567 otherwise, it's "right". </td> 568 </tr> 569 <tr> 570 <td> <code>@@bidi_end_edge</code> </td> 571 <td> If the <code>@@bidi_dir</code> is "ltr", then this is "right"; 572 otherwise, it's "left". </td> 573 </tr> 574 </tbody></table> 575 576 <p> 577 Here's an example of using <code>@@extension_id</code> in a CSS file 578 to construct a URL: 579 </p> 580 581 <pre>body { 582 <b>background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');</b> 583 } 584 </pre> 585 586 <p> 587 If the extension ID is abcdefghijklmnopqrstuvwxyzabcdef, 588 then the bold line in the previous code snippet becomes: 589 </p> 590 591 <pre>background-image:url('chrome-extension://abcdefghijklmnopqrstuvwxyzabcdef/background.png'); 592 </pre> 593 594 <p> 595 Here's an example of using <code>@@bidi_*</code> messages in a CSS file: 596 </p> 597 598 <pre>body { 599 <b>direction: __MSG_@@bidi_dir__;</b> 600 } 601 602 div#header { 603 margin-bottom: 1.05em; 604 overflow: hidden; 605 padding-bottom: 1.5em; 606 <b>padding-__MSG_@@bidi_start_edge__: 0;</b> 607 <b>padding-__MSG_@@bidi_end_edge__: 1.5em;</b> 608 position: relative; 609 } 610 </pre> 611 612 <p> 613 For left-to-right languages such as English, 614 the bold lines become: 615 </p> 616 617 <pre>dir: ltr; 618 padding-left: 0; 619 padding-right: 1.5em; 620 </pre> 621 622 623 <h2 id="overview-locales">Locales</h2> 624 625 <p> 626 You can choose from many locales, 627 including some (such as <code>en</code>) 628 that let a single translation support multiple variations of a language 629 (such as <code>en_GB</code> and <code>en_US</code>). 630 </p> 631 632 633 <h3 id="locales-supported">Supported locales</h3> 634 635 <p> 636 Extensions can use any of the 637 <a href="http://code.google.com/chrome/webstore/docs/i18n.html#localeTable">locales that the Chrome Web Store supports</a>. 638 </p> 639 640 641 <h3 id="locales-usage">How extensions find strings</h3> 642 643 <p> 644 You don't have to define every string for every locale 645 that your internationalized extension supports. 646 As long as the default locale's <code>messages.json</code> file 647 has a value for every string, 648 your extension will run no matter how sparse a translation is. 649 Here's how the extension system searches for a message: 650 </p> 651 652 <ol> 653 <li> 654 Search the messages file (if any) 655 for the user's preferred locale. 656 For example, when Google Chrome's locale is set to 657 British English (<code>en_GB</code>), 658 the system first looks for the message in 659 <code>_locales/en_GB/messages.json</code>. 660 If that file exists and the message is there, 661 the system looks no further. 662 </li> 663 <li> 664 If the user's preferred locale has a region 665 (that is, the locale has an underscore: _), 666 search the locale without that region. 667 For example, if the <code>en_GB</code> messages file 668 doesn't exist or doesn't contain the message, 669 the system looks in the <code>en</code> messages file. 670 If that file exists and the message is there, 671 the system looks no further. 672 </li> 673 <li> 674 Search the messages file for the extension's default locale. 675 For example, if the extension's "default_locale" is set to "es", 676 and neither <code>_locales/en_GB/messages.json</code> 677 nor <code>_locales/en/messages.json</code> contains the message, 678 the extension uses the message from 679 <code>_locales/es/messages.json</code>. 680 </li> 681 </ol> 682 683 <p> 684 In the following figure, 685 the message named "colores" is in all three locales 686 that the extension supports, 687 but "extName" is in only two of the locales. 688 Wherever a user running Google Chrome in US English sees the label "Colors", 689 a user of British English sees "Colours". 690 Both US English and British English users 691 see the extension name "Hello World". 692 Because the default language is Spanish, 693 users running Google Chrome in any non-English language 694 see the label "Colores" and the extension name "Hola mundo". 695 </p> 696 697 <img src="images/i18n-strings.gif" alt="Four files: manifest.json and three 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"> 698 699 <h3 id="locales-testing">How to set your browser's locale</h3> 700 701 <p> 702 To test translations, you might want to set your browser's locale. 703 This section tells you how to set the locale in 704 <a href="#testing-win">Windows</a>, 705 <a href="#testing-mac">Mac OS X</a>, and 706 <a href="#testing-linux">Linux</a>. 707 </p> 708 709 <h4 id="testing-win">Windows</h4> 710 711 <p> 712 You can change the locale using either 713 a locale-specific shortcut 714 or the Google Chrome UI. 715 The shortcut approach is quicker, once you've set it up, 716 and it lets you use several languages at once. 717 </p> 718 719 <h5 id="win-shortcut">Using a locale-specific shortcut</h5> 720 721 <p> 722 To create and use a shortcut that launches Google Chrome 723 with a particular locale: 724 </p> 725 726 <ol> 727 <li> 728 Make a copy of the Google Chrome shortcut 729 that's already on your desktop. 730 </li> 731 <li> 732 Rename the new shortcut to match the new locale. 733 </li> 734 <li> 735 Change the shortcut's properties 736 so that the Target field specifies the 737 <code>--lang</code> and 738 <code>--user-data-dir</code> flags. 739 The target should look something like this: 740 741 <pre><em>path_to_chrome.exe</em> --lang=<em>locale</em> --user-data-dir=c:\<em>locale_profile_dir</em></pre> 742 </li> 743 744 <li> 745 Launch Google Chrome by double-clicking the shortcut. 746 </li> 747 </ol> 748 749 <p> 750 For example, to create a shortcut 751 that launches Google Chrome in Spanish (<code>es</code>), 752 you might create a shortcut named <code>chrome-es</code> 753 that has the following target: 754 </p> 755 756 <pre><em>path_to_chrome.exe</em> --lang=es --user-data-dir=c:\chrome-profile-es</pre> 757 758 <p> 759 You can create as many shortcuts as you like, 760 making it easy to test your extension in multiple languages. 761 For example: 762 </p> 763 764 <pre><em>path_to_chrome.exe</em> --lang=en --user-data-dir=c:\chrome-profile-en 765 <em>path_to_chrome.exe</em> --lang=en_GB --user-data-dir=c:\chrome-profile-en_GB 766 <em>path_to_chrome.exe</em> --lang=ko --user-data-dir=c:\chrome-profile-ko</pre> 767 768 <p class="note"> 769 <b>Note:</b> 770 Specifying <code>--user-data-dir</code> is optional but handy. 771 Having one data directory per locale 772 lets you run the browser 773 in several languages at the same time. 774 A disadvantage is that because the locales' data isn't shared, 775 you have to install your extension multiple times once per locale, 776 which can be challenging when you don't speak the language. 777 For more information, see 778 <a href="http://www.chromium.org/developers/creating-and-using-profiles">Creating and Using Profiles</a>. 779 </p> 780 781 782 <h5 id="win-ui">Using the UI</h5> 783 784 <p> 785 Here's how to change the locale using the UI on Google Chrome for Windows: 786 </p> 787 788 <ol> 789 <li> Wrench icon > <b>Options</b> </li> 790 <li> Choose the <b>Under the Hood</b> tab </li> 791 <li> Scroll down to <b>Web Content</b> </li> 792 <li> Click <b>Change font and language settings</b> </li> 793 <li> Choose the <b>Languages</b> tab </li> 794 <li> Use the drop down to set the <b>Google Chrome language</b> </li> 795 <li> Restart Chrome </li> 796 </ol> 797 798 799 <h4 id="testing-mac">Mac OS X</h4> 800 801 <p> 802 To change the locale on Mac, 803 you use the system preferences. 804 </p> 805 806 <ol> 807 <li> From the Apple menu, choose <b>System Preferences</b> </li> 808 <li> Under the <b>Personal</b> section, choose <b>International</b> </li> 809 <li> Choose your language and location </li> 810 <li> Restart Chrome </li> 811 </ol> 812 813 814 <h4 id="testing-linux">Linux</h4> 815 816 <p> 817 To change the locale on Linux, 818 first quit Google Chrome. 819 Then, all in one line, 820 set the LANGUAGE environment variable 821 and launch Google Chrome. 822 For example: 823 </p> 824 825 <pre>LANGUAGE=es ./chrome 826 </pre> 827 828 829 <h2 id="overview-examples">Examples</h2> 830 831 <p> 832 You can find simple examples of internationalization in the 833 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/i18n/">examples/api/i18n</a> 834 directory. 835 For a complete example, see 836 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/extensions/news/">examples/extensions/news</a>. 837 For other examples and for help in viewing the source code, see 838 <a href="samples.html">Samples</a>. 839 </p> 840 841 842 <h3 id="examples-getMessage">Examples: getMessage</h3> 843 844 <!-- 845 [PENDING: improve this section. it should probably start with a 846 one-variable example that includes the messages.json code.] 847 --> 848 849 <p> 850 The following code gets a localized message from the browser 851 and displays it as a string. 852 It replaces two placeholders within the message with the strings 853 "string1" and "string2". 854 </p> 855 856 <pre>function getMessage() { 857 var message = chrome.i18n.getMessage("click_here", ["string1", "string2"]); 858 document.getElementById("languageSpan").innerHTML = message; 859 } 860 </pre> 861 862 <p> 863 Here's how you'd supply and use a single string: 864 </p> 865 866 <pre><em>// In JavaScript code</em> 867 status.innerText = chrome.i18n.getMessage("error", errorDetails); 868 869 <em>// In messages.json</em> 870 "error": { 871 "message": "Error: $details$", 872 "description": "Generic error template. Expects error parameter to be passed in.", 873 "placeholders": { 874 "details": { 875 "content": "$1", 876 "example": "Failed to fetch RSS feed." 877 } 878 } 879 } 880 </pre> 881 882 <p> 883 For more information about placeholders, see the 884 <a href="i18n-messages.html">Locale-Specific Messages</a> page. 885 For details on calling <code>getMessage()</code>, see the 886 <a href="#method-getMessage">API reference</a>. 887 </p> 888 889 <h3 id="example-accept-languages">Example: getAcceptLanguages</h3> 890 <p> 891 The following code gets accept-languages from the browser and displays them as a 892 string by separating each accept-language with ','. 893 </p> 894 895 <pre>function getAcceptLanguages() { 896 chrome.i18n.getAcceptLanguages(function(languageList) { 897 var languages = languageList.join(","); 898 document.getElementById("languageSpan").innerHTML = languages; 899 }) 900 } 901 </pre> 902 903 <p> 904 For details on calling <code>getAcceptLanguages()</code>, see the 905 <a href="#method-getAcceptLanguages">API reference</a>. 906 </p> 907 908 <!-- END AUTHORED CONTENT --> 909 </div> 910 911 <!-- API PAGE --> 912 <div class="apiPage"> 913 <a name="apiReference"></a> 914 <h2>API reference: chrome.i18n</h2> 915 916 <!-- PROPERTIES --> 917 <div class="apiGroup" style="display: none; "> 918 <a name="properties"></a> 919 <h3 id="properties">Properties</h3> 920 921 <div> 922 <a></a> 923 <h4>getLastError</h4> 924 <div class="summary"> 925 <!-- Note: intentionally longer 80 columns --> 926 <span>chrome.extension</span><span>lastError</span> 927 </div> 928 <div> 929 </div> 930 </div> 931 932 </div> <!-- /apiGroup --> 933 934 <!-- METHODS --> 935 <div id="methodsTemplate" class="apiGroup"> 936 <a name="global-methods"></a> 937 <h3>Methods</h3> 938 939 <!-- iterates over all functions --> 940 <div class="apiItem"> 941 <a name="method-getAcceptLanguages"></a> <!-- method-anchor --> 942 <h4>getAcceptLanguages</h4> 943 944 <div class="summary"><span style="display: none; ">void</span> 945 <!-- Note: intentionally longer 80 columns --> 946 <span>chrome.i18n.getAcceptLanguages</span>(<span class="null"><span style="display: none; ">, </span><span>function</span> 947 <var><span>callback</span></var></span>)</div> 948 949 <div class="description"> 950 <p class="todo" style="display: none; ">Undocumented.</p> 951 <p>Gets the accept-languages of the browser. This is different from the locale used by the browser; to get the locale, use <code>window.navigator.language</code>.</p> 952 953 <!-- PARAMETERS --> 954 <h4>Parameters</h4> 955 <dl> 956 <div> 957 <div> 958 <dt> 959 <var>callback</var> 960 <em> 961 962 <!-- TYPE --> 963 <div style="display:inline"> 964 ( 965 <span class="optional" style="display: none; ">optional</span> 966 <span class="enum" style="display: none; ">enumerated</span> 967 <span id="typeTemplate"> 968 <span style="display: none; "> 969 <a> Type</a> 970 </span> 971 <span> 972 <span style="display: none; "> 973 array of <span><span></span></span> 974 </span> 975 <span>function</span> 976 <span style="display: none; "></span> 977 </span> 978 </span> 979 ) 980 </div> 981 982 </em> 983 </dt> 984 <dd class="todo"> 985 Undocumented. 986 </dd> 987 <dd style="display: none; "> 988 Description of this parameter from the json schema. 989 </dd> 990 <dd style="display: none; "> 991 This parameter was added in version 992 <b><span></span></b>. 993 You must omit this parameter in earlier versions, 994 and you may omit it in any version. If you require this 995 parameter, the manifest key 996 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 997 can ensure that your extension won't be run in an earlier browser version. 998 </dd> 999 1000 <!-- OBJECT PROPERTIES --> 1001 <dd style="display: none; "> 1002 <dl> 1003 <div> 1004 <div> 1005 </div> 1006 </div> 1007 </dl> 1008 </dd> 1009 1010 <!-- OBJECT METHODS --> 1011 <dd style="display: none; "> 1012 <div></div> 1013 </dd> 1014 1015 <!-- OBJECT EVENT FIELDS --> 1016 <dd style="display: none; "> 1017 <div></div> 1018 </dd> 1019 1020 <!-- FUNCTION PARAMETERS --> 1021 <dd style="display: none; "> 1022 <div></div> 1023 </dd> 1024 1025 </div> 1026 </div> 1027 </dl> 1028 1029 <!-- RETURNS --> 1030 <h4 style="display: none; ">Returns</h4> 1031 <dl> 1032 <div style="display: none; "> 1033 <div> 1034 </div> 1035 </div> 1036 </dl> 1037 1038 <!-- CALLBACK --> 1039 <div> 1040 <div> 1041 <h4>Callback function</h4> 1042 <p> 1043 The callback <em>parameter</em> should specify a function 1044 that looks like this: 1045 </p> 1046 <p style="display: none; "> 1047 If you specify the <em>callback</em> parameter, it should 1048 specify a function that looks like this: 1049 </p> 1050 1051 <!-- Note: intentionally longer 80 columns --> 1052 <pre>function(<span>array of string languages</span>) <span class="subdued">{...}</span>;</pre> 1053 <dl> 1054 <div> 1055 <div> 1056 <dt> 1057 <var>languages</var> 1058 <em> 1059 1060 <!-- TYPE --> 1061 <div style="display:inline"> 1062 ( 1063 <span class="optional" style="display: none; ">optional</span> 1064 <span class="enum" style="display: none; ">enumerated</span> 1065 <span id="typeTemplate"> 1066 <span style="display: none; "> 1067 <a> Type</a> 1068 </span> 1069 <span> 1070 <span> 1071 array of <span><span> 1072 <span style="display: none; "> 1073 <a> Type</a> 1074 </span> 1075 <span> 1076 <span style="display: none; "> 1077 array of <span><span></span></span> 1078 </span> 1079 <span>string</span> 1080 <span style="display: none; "></span> 1081 </span> 1082 </span></span> 1083 </span> 1084 <span style="display: none; ">paramType</span> 1085 <span style="display: none; "></span> 1086 </span> 1087 </span> 1088 ) 1089 </div> 1090 1091 </em> 1092 </dt> 1093 <dd class="todo" style="display: none; "> 1094 Undocumented. 1095 </dd> 1096 <dd>Array of the accept languages of the browser, such as en-US,en,zh-CN</dd> 1097 <dd style="display: none; "> 1098 This parameter was added in version 1099 <b><span></span></b>. 1100 You must omit this parameter in earlier versions, 1101 and you may omit it in any version. If you require this 1102 parameter, the manifest key 1103 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 1104 can ensure that your extension won't be run in an earlier browser version. 1105 </dd> 1106 1107 <!-- OBJECT PROPERTIES --> 1108 <dd style="display: none; "> 1109 <dl> 1110 <div> 1111 <div> 1112 </div> 1113 </div> 1114 </dl> 1115 </dd> 1116 1117 <!-- OBJECT METHODS --> 1118 <dd style="display: none; "> 1119 <div></div> 1120 </dd> 1121 1122 <!-- OBJECT EVENT FIELDS --> 1123 <dd style="display: none; "> 1124 <div></div> 1125 </dd> 1126 1127 <!-- FUNCTION PARAMETERS --> 1128 <dd style="display: none; "> 1129 <div></div> 1130 </dd> 1131 1132 </div> 1133 </div> 1134 </dl> 1135 </div> 1136 </div> 1137 1138 <!-- MIN_VERSION --> 1139 <p style="display: none; "> 1140 This function was added in version <b><span></span></b>. 1141 If you require this function, the manifest key 1142 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 1143 can ensure that your extension won't be run in an earlier browser version. 1144 </p> 1145 </div> <!-- /description --> 1146 1147 </div><div class="apiItem"> 1148 <a name="method-getMessage"></a> <!-- method-anchor --> 1149 <h4>getMessage</h4> 1150 1151 <div class="summary"><span>string</span> 1152 <!-- Note: intentionally longer 80 columns --> 1153 <span>chrome.i18n.getMessage</span>(<span class="null"><span style="display: none; ">, </span><span>string</span> 1154 <var><span>messageName</span></var></span><span class="optional"><span>, </span><span>string or array of string</span> 1155 <var><span>substitutions</span></var></span>)</div> 1156 1157 <div class="description"> 1158 <p class="todo" style="display: none; ">Undocumented.</p> 1159 <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> 1160 1161 <!-- PARAMETERS --> 1162 <h4>Parameters</h4> 1163 <dl> 1164 <div> 1165 <div> 1166 <dt> 1167 <var>messageName</var> 1168 <em> 1169 1170 <!-- TYPE --> 1171 <div style="display:inline"> 1172 ( 1173 <span class="optional" style="display: none; ">optional</span> 1174 <span class="enum" style="display: none; ">enumerated</span> 1175 <span id="typeTemplate"> 1176 <span style="display: none; "> 1177 <a> Type</a> 1178 </span> 1179 <span> 1180 <span style="display: none; "> 1181 array of <span><span></span></span> 1182 </span> 1183 <span>string</span> 1184 <span style="display: none; "></span> 1185 </span> 1186 </span> 1187 ) 1188 </div> 1189 1190 </em> 1191 </dt> 1192 <dd class="todo" style="display: none; "> 1193 Undocumented. 1194 </dd> 1195 <dd>The name of the message, as specified in the <a href="i18n-messages.html"><code>messages.json</code></a> file.</dd> 1196 <dd style="display: none; "> 1197 This parameter was added in version 1198 <b><span></span></b>. 1199 You must omit this parameter in earlier versions, 1200 and you may omit it in any version. If you require this 1201 parameter, the manifest key 1202 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 1203 can ensure that your extension won't be run in an earlier browser version. 1204 </dd> 1205 1206 <!-- OBJECT PROPERTIES --> 1207 <dd style="display: none; "> 1208 <dl> 1209 <div> 1210 <div> 1211 </div> 1212 </div> 1213 </dl> 1214 </dd> 1215 1216 <!-- OBJECT METHODS --> 1217 <dd style="display: none; "> 1218 <div></div> 1219 </dd> 1220 1221 <!-- OBJECT EVENT FIELDS --> 1222 <dd style="display: none; "> 1223 <div></div> 1224 </dd> 1225 1226 <!-- FUNCTION PARAMETERS --> 1227 <dd style="display: none; "> 1228 <div></div> 1229 </dd> 1230 1231 </div> 1232 </div><div> 1233 <div> 1234 <dt> 1235 <var>substitutions</var> 1236 <em> 1237 1238 <!-- TYPE --> 1239 <div style="display:inline"> 1240 ( 1241 <span class="optional">optional</span> 1242 <span class="enum" style="display: none; ">enumerated</span> 1243 <span id="typeTemplate"> 1244 <span style="display: none; "> 1245 <a> Type</a> 1246 </span> 1247 <span> 1248 <span style="display: none; "> 1249 array of <span><span></span></span> 1250 </span> 1251 <span>string or array of string</span> 1252 <span style="display: none; "></span> 1253 </span> 1254 </span> 1255 ) 1256 </div> 1257 1258 </em> 1259 </dt> 1260 <dd class="todo" style="display: none; "> 1261 Undocumented. 1262 </dd> 1263 <dd>1 - 9 substitution strings, if the message requires any.</dd> 1264 <dd style="display: none; "> 1265 This parameter was added in version 1266 <b><span></span></b>. 1267 You must omit this parameter in earlier versions, 1268 and you may omit it in any version. If you require this 1269 parameter, the manifest key 1270 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 1271 can ensure that your extension won't be run in an earlier browser version. 1272 </dd> 1273 1274 <!-- OBJECT PROPERTIES --> 1275 <dd style="display: none; "> 1276 <dl> 1277 <div> 1278 <div> 1279 </div> 1280 </div> 1281 </dl> 1282 </dd> 1283 1284 <!-- OBJECT METHODS --> 1285 <dd style="display: none; "> 1286 <div></div> 1287 </dd> 1288 1289 <!-- OBJECT EVENT FIELDS --> 1290 <dd style="display: none; "> 1291 <div></div> 1292 </dd> 1293 1294 <!-- FUNCTION PARAMETERS --> 1295 <dd style="display: none; "> 1296 <div></div> 1297 </dd> 1298 1299 </div> 1300 </div> 1301 </dl> 1302 1303 <!-- RETURNS --> 1304 <h4>Returns</h4> 1305 <dl> 1306 <div> 1307 <div> 1308 <dt> 1309 <var style="display: none; ">paramName</var> 1310 <em> 1311 1312 <!-- TYPE --> 1313 <div style="display:inline"> 1314 ( 1315 <span class="optional" style="display: none; ">optional</span> 1316 <span class="enum" style="display: none; ">enumerated</span> 1317 <span id="typeTemplate"> 1318 <span style="display: none; "> 1319 <a> Type</a> 1320 </span> 1321 <span> 1322 <span style="display: none; "> 1323 array of <span><span></span></span> 1324 </span> 1325 <span>string</span> 1326 <span style="display: none; "></span> 1327 </span> 1328 </span> 1329 ) 1330 </div> 1331 1332 </em> 1333 </dt> 1334 <dd class="todo" style="display: none; "> 1335 Undocumented. 1336 </dd> 1337 <dd>Message localized for current locale.</dd> 1338 <dd style="display: none; "> 1339 This parameter was added in version 1340 <b><span></span></b>. 1341 You must omit this parameter in earlier versions, 1342 and you may omit it in any version. If you require this 1343 parameter, the manifest key 1344 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 1345 can ensure that your extension won't be run in an earlier browser version. 1346 </dd> 1347 1348 <!-- OBJECT PROPERTIES --> 1349 <dd style="display: none; "> 1350 <dl> 1351 <div> 1352 <div> 1353 </div> 1354 </div> 1355 </dl> 1356 </dd> 1357 1358 <!-- OBJECT METHODS --> 1359 <dd style="display: none; "> 1360 <div></div> 1361 </dd> 1362 1363 <!-- OBJECT EVENT FIELDS --> 1364 <dd style="display: none; "> 1365 <div></div> 1366 </dd> 1367 1368 <!-- FUNCTION PARAMETERS --> 1369 <dd style="display: none; "> 1370 <div></div> 1371 </dd> 1372 1373 </div> 1374 </div> 1375 </dl> 1376 1377 <!-- CALLBACK --> 1378 <div style="display: none; "> 1379 <div> 1380 <h4>Callback function</h4> 1381 <p> 1382 The callback <em>parameter</em> should specify a function 1383 that looks like this: 1384 </p> 1385 <p> 1386 If you specify the <em>callback</em> parameter, it should 1387 specify a function that looks like this: 1388 </p> 1389 1390 <!-- Note: intentionally longer 80 columns --> 1391 <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>;</pre> 1392 <dl> 1393 <div> 1394 <div> 1395 </div> 1396 </div> 1397 </dl> 1398 </div> 1399 </div> 1400 1401 <!-- MIN_VERSION --> 1402 <p style="display: none; "> 1403 This function was added in version <b><span></span></b>. 1404 If you require this function, the manifest key 1405 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 1406 can ensure that your extension won't be run in an earlier browser version. 1407 </p> 1408 </div> <!-- /description --> 1409 1410 </div> <!-- /apiItem --> 1411 1412 </div> <!-- /apiGroup --> 1413 1414 <!-- EVENTS --> 1415 <div id="eventsTemplate" class="apiGroup" style="display: none; "> 1416 <a></a> 1417 <h3>Events</h3> 1418 <!-- iterates over all events --> 1419 <div class="apiItem"> 1420 <a></a> 1421 <h4>event name</h4> 1422 1423 <div class="summary"> 1424 <!-- Note: intentionally longer 80 columns --> 1425 <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>); 1426 </div> 1427 1428 <div class="description"> 1429 <p class="todo">Undocumented.</p> 1430 <p> 1431 A description from the json schema def of the event goes here. 1432 </p> 1433 1434 <!-- PARAMETERS --> 1435 <div> 1436 <h4>Parameters</h4> 1437 <dl> 1438 <div> 1439 <div> 1440 </div> 1441 </div> 1442 </dl> 1443 </div> 1444 </div> <!-- /decription --> 1445 1446 </div> <!-- /apiItem --> 1447 1448 </div> <!-- /apiGroup --> 1449 1450 <!-- TYPES --> 1451 <div class="apiGroup" style="display: none; "> 1452 <a name="types"></a> 1453 <h3 id="types">Types</h3> 1454 1455 <!-- iterates over all types --> 1456 <div class="apiItem"> 1457 <a></a> 1458 <h4>type name</h4> 1459 1460 <div> 1461 </div> 1462 1463 </div> <!-- /apiItem --> 1464 1465 </div> <!-- /apiGroup --> 1466 1467 </div> <!-- /apiPage --> 1468 </div> <!-- /gc-pagecontent --> 1469 </div> <!-- /g-section --> 1470 </div> <!-- /codesiteContent --> 1471 <div id="gc-footer" --=""> 1472 <div class="text"> 1473 <p> 1474 Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>, 1475 the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons 1476 Attribution 3.0 License</a>, and code samples are licensed under the 1477 <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>. 1478 </p> 1479 <p> 1480 2011 Google 1481 </p> 1482 1483 <!-- begin analytics --> 1484 <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script> 1485 <script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script> 1486 1487 <script type="text/javascript"> 1488 // chrome doc tracking 1489 try { 1490 var engdocs = _gat._getTracker("YT-10763712-2"); 1491 engdocs._trackPageview(); 1492 } catch(err) {} 1493 1494 // code.google.com site-wide tracking 1495 try { 1496 _uacct="UA-18071-1"; 1497 _uanchor=1; 1498 _uff=0; 1499 urchinTracker(); 1500 } 1501 catch(e) {/* urchinTracker not available. */} 1502 </script> 1503 <!-- end analytics --> 1504 </div> 1505 </div> <!-- /gc-footer --> 1506 </div> <!-- /gc-container --> 1507 </body></html> 1508
