chrome/common/extensions/docs/i18n.html - Issue 10642015: Basic setup for generating app docs

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

Issue 10642015: Basic setup for generating app docs (Closed) Base URL: svn://svn.chromium.org/chrome/trunk/src

Patch Set: fix Created 8 years, 6 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

« chrome/common/extensions/docs/build/build.py ('K') | « chrome/common/extensions/docs/hosting.html ('k') | chrome/common/extensions/docs/i18n-messages.html » ('j') | chrome/common/extensions/docs/js/api_page_generator.js » ('J')
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Hide Comments ('s')

OLD	NEW
	(Empty)
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/jstempla te_compiled.js">

15 </script>

16 <script type="text/javascript" src="../../../../third_party/json_minify/mini fy-sans-regexp.js">

17 </script>

18 <script type="text/javascript" src="js/api_page_generator.js"></script>

19 <script type="text/javascript" src="js/bootstrap.js"></script>

20 <script type="text/javascript" src="js/sidebar.js"></script>

21 <meta name="description" content="Documentation for the chrome.i18n module, wh ich is part of the Google Chrome extension APIs."><title>Internationalization ( i18n) - Google Chrome Extensions - Google Code</title></head>

22 <body> <div id="devModeWarning" class="displayModeWarning">

23 You are viewing extension docs in chrome via the 'file:' scheme: are you exp ecting to see local changes when you refresh? You'll need run chrome with --allo w-file-access-from-files.

24 </div>

25 <div id="branchWarning" class="displayModeWarning">

26 <span>WARNING: This is the <span id="branchName">BETA</span> documentation.

27 It may not work with the stable release of Chrome.</span>

28 <select id="branchChooser">

29 <option>Choose a different version...

30 </option><option value="">Stable

31 </option><option value="beta">Beta

32 </option><option value="dev">Dev

33 </option><option value="trunk">Trunk

34 </option></select>

35 </div>

36 <div id="unofficialWarning" class="displayModeWarning">

37 <span>WARNING: This is unofficial documentation. It may not work with the

38 current release of Chrome.</span>

39 <button id="goToOfficialDocs">Go to the official docs</button>

40 </div>

41 <div id="gc-container" class="labs">

42 <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION -->

43 <!-- In particular, sub-templates that recurse, must be used by allowing

44 jstemplate to make a copy of the template in this section which

45 are not operated on by way of the jsskip="true" -->

46 <!-- /SUBTEMPLATES -->

47 <a id="top"></a>

48 <div id="skipto">

49 <a href="#gc-pagecontent">Skip to page content</a>

50 <a href="#gc-toc">Skip to main navigation</a>

51 </div>

52 <!-- API HEADER -->

53 <table id="header" width="100%" cellspacing="0" border="0">

54 <tbody><tr>

55 <td valign="middle"><a href="http://code.google.com/"><img src="images/c ode_labs_logo.gif" height="43" width="161" alt="Google Code Labs" style="border: 0; margin:0;"></a></td>

56 <td valign="middle" width="100%" style="padding-left:0.6em;">

57 <form action="http://www.google.com/cse" id="cse" style="margin-top:0. 5em">

58 <div id="gsc-search-box">

59 <input type="hidden" name="cx" value="002967670403910741006:61_cvz fqtno">

60 <input type="hidden" name="ie" value="UTF-8">

61 <input type="text" name="q" value="" size="55">

62 <input class="gsc-search-button" type="submit" name="sa" value="Se arch">

63 <br>

64 <span class="greytext">e.g. "page action" or "tabs"</span>

65 </div>

66 </form>

67 <script type="text/javascript" src="https://www.google.com/jsapi"></sc ript>

68 <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script>

69 <script type="text/javascript" src="https://www.google.com/coop/cse/t1 3n?form=cse&t13n_langs=en"></script>

70 <script type="text/javascript" src="https://www.google.com/coop/cse/br and?form=cse&lang=en"></script>

71 </td>

72 </tr>

73 </tbody></table>

74 <div id="codesiteContent" class="">

75 <a id="gc-topnav-anchor"></a>

76 <div id="gc-topnav">

77 <h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Lab s</a>)</h1>

78 <ul id="home" class="gc-topnav-tabs">

79 <li id="home_link">

80 <a href="index.html" title="Google Chrome Extensions home page">Home </a>

81 </li>

82 <li id="docs_link">

83 <a href="docs.html" title="Official Google Chrome Extensions documen tation">Docs</a>

84 </li>

85 <li id="faq_link">

86 <a href="faq.html" title="Answers to frequently asked questions abou t Google Chrome Extensions">FAQ</a>

87 </li>

88 <li id="samples_link">

89 <a href="samples.html" title="Sample extensions (with source code)"> Samples</a>

90 </li>

91 <li id="group_link">

92 <a href="http://groups.google.com/a/chromium.org/group/chromium-exte nsions" title="Google Chrome Extensions developer forum">Group</a>

93 </li>

94 <li id="so_link">

95 <a href="http://stackoverflow.com/questions/tagged/google-chrome-ext ension" title="[google-chrome-extension] tag on Stack Overflow">Questions?</a>

96 </li>

97 </ul>

98 </div> <!-- end gc-topnav -->

99 <div class="g-section g-tpl-170">

100 <!-- SIDENAV -->

101 <div class="g-unit g-first" id="gc-toc">

102 <ul>

103 <li><a href="getstarted.html">Getting Started</a></li>

104 <li><a href="overview.html">Overview</a></li>

105 <li><a href="whats_new.html">What's New?</a></li>

106 <li><h2><a href="devguide.html">Developer's Guide</a></h2>

107 <ul>

108 <li>Browser UI

109 <ul>

110 <li><a href="browserAction.html">Browser Actions</a></li>

111 <li><a href="contextMenus.html">Context Menus</a></li>

112 <li><a href="notifications.html">Desktop Notifications</a></li >

113 <li><a href="omnibox.html">Omnibox</a></li>

114 <li><a href="options.html">Options Pages</a></li>

115 <li><a href="override.html">Override Pages</a></li>

116 <li><a href="pageAction.html">Page Actions</a></li>

117 </ul>

118 </li>

119 <li>Browser Interaction

120 <ul>

121 <li><a href="bookmarks.html">Bookmarks</a></li>

122 <li><a href="cookies.html">Cookies</a></li>

123 <li><a href="devtools.html">Developer Tools</a></li>

124 <li><a href="events.html">Events</a></li>

125 <li><a href="history.html">History</a></li>

126 <li><a href="management.html">Management</a></li>

127 <li><a href="tabs.html">Tabs</a></li>

128 <li><a href="windows.html">Windows</a></li>

129 </ul>

130 </li>

131 <li>Implementation

132 <ul>

133 <li><a href="a11y.html">Accessibility</a></li>

134 <li><a href="background_pages.html">Background Pages</a></li>

135 <li><a href="content_scripts.html">Content Scripts</a></li>

136 <li><a href="xhr.html">Cross-Origin XHR</a></li>

137 <li class="leftNavSelected">Internationalization</li>

138 <li><a href="messaging.html">Message Passing</a></li>

139 <li><a href="permissions.html">Optional Permissions</a></li>

140 <li><a href="npapi.html">NPAPI Plugins</a></li>

141 </ul>

142 </li>

143 <li>Finishing

144 <ul>

145 <li><a href="hosting.html">Hosting</a></li>

146 <li><a href="external_extensions.html">Other Deployment Option s</a></li>

147 </ul>

148 </li>

149 </ul>

150 </li>

151 <li><h2><a href="apps.html">Packaged Apps</a></h2></li>

152 <li><h2><a href="tutorials.html">Tutorials</a></h2>

153 <ul>

154 <li><a href="tut_debugging.html">Debugging</a></li>

155 <li><a href="tut_analytics.html">Google Analytics</a></li>

156 <li><a href="tut_oauth.html">OAuth</a></li>

157 </ul>

158 </li>

159 <li><h2>Reference</h2>

160 <ul>

161 <li>Formats

162 <ul>

163 <li><a href="manifest.html">Manifest Files</a></li>

164 <li><a href="match_patterns.html">Match Patterns</a></li>

165 </ul>

166 </li>

167 <li><a href="permission_warnings.html">Permission Warnings</a></li >

168 <li><a href="api_index.html">chrome.* APIs</a></li>

169 <li><a href="api_other.html">Other APIs</a></li>

170 </ul>

171 </li>

172 <li><h2><a href="samples.html">Samples</a></h2></li>

173 <div class="line"> </div>

174 <li><h2>More</h2>

175 <ul>

176 <li><a href="http://code.google.com/chrome/webstore/docs/index.htm l">Chrome Web Store</a></li>

177 <li><a href="http://code.google.com/chrome/apps/docs/developers_gu ide.html">Hosted Apps</a></li>

178 <li><a href="themes.html">Themes</a></li>

179 </ul>

180 </li>

181 </ul>

182 </div>

183 <script>

184 initToggles();

185 </script>

186 <div class="g-unit" id="gc-pagecontent">

187 <div id="pageTitle">

188 <h1 class="page_title">Internationalization (i18n)</h1>

189 </div>

190 <!-- TABLE OF CONTENTS -->

191 <div id="toc">

192 <h2>Contents</h2>

193 <ol>

194 <li>

195 <a href="#l10">How to support multiple languages</a>

196 <ol>

197 </ol>

198 </li><li>

199 <a href="#overview-predefined">Predefined messages</a>

200 <ol>

201 </ol>

202 </li><li>

203 <a href="#overview-locales">Locales</a>

204 <ol>

205 <li>

206 <a href="#locales-supported">Supported locales</a>

207 </li><li>

208 <a href="#locales-usage">How extensions find strings</a>

209 </li><li>

210 <a href="#locales-testing">How to set your browser's locale</a >

211 </li>

212 </ol>

213 </li><li>

214 <a href="#overview-examples">Examples</a>

215 <ol>

216 <li>

217 <a href="#examples-getMessage">Examples: getMessage</a>

218 </li><li>

219 <a href="#example-accept-languages">Example: getAcceptLanguage s</a>

220 </li>

221 </ol>

222 </li>

223 <li>

224 <a href="#apiReference">API reference: chrome.i18n</a>

225 <ol>

226 <li>

227 <a href="#global-methods">Methods</a>

228 <ol>

229 <li>

230 <a href="#method-getAcceptLanguages">getAcceptLanguages</a>

231 </li><li>

232 <a href="#method-getMessage">getMessage</a>

233 </li>

234 </ol>

235 </li>

236 </ol>

237 </li>

238 </ol>

239 </div>

240 <!-- /TABLE OF CONTENTS -->

241 <!-- Standard content lead-in for experimental API pages -->

242 <!-- STATIC CONTENT PLACEHOLDER -->

243 <div id="static"><div id="pageData-name" class="pageData">Internationali zation (i18n)</div>

244 <!--

245 [NOTEs for editors:

246 * Try to be consistent about string vs. message (it's probably not yet).

247 -->

248 <!-- BEGIN AUTHORED CONTENT -->

249 <p id="classSummary">

250 An <em>internationalized</em> extension

251 can be easily

252 <em>localized</em> —

253 adapted to languages and regions

254 that it didn't originally support.

255 </p>

256 <p>

257 To internationalize your extension,

258 you need to put all of its user-visible strings into a file

259 named <a href="i18n-messages.html"><code>messages.json</code></a>.

260 Each time you localize your extension

261 you add a messages file

262 under a directory

263 named <code>_locales/<em>localeCode</em></code>,

264 where <em>localeCode</em> is a code such as

265 <code>en</code> for English.

266 </p>

267 <p>

268 Here's the file hierarchy

269 for an internationalized extension that supports

270 English (<code>en</code>),

271 Spanish (<code>es</code>), and

272 Korean (<code>ko</code>):

273 </p>

274 <img src="images/i18n-hierarchy.gif" alt="In the extension directory: manifest.j son, .html, .js, _locales directory. In the _locales directory: en, es, and ko directories, each with a messages.json file." width="385" height="77">

275 <h2 id="l10">How to support multiple languages</h2>

276 <p>

277 Say you have an extension

278 with the files shown in the following figure:

279 </p>

280 <img src="images/i18n-before.gif" alt="A manifest.json file and a file with Java Script. The .json file has "name": "Hello World". The JavaSc ript file has title = "Hello World";" width="323" height="148">

281 <p>

282 To internationalize this extension,

283 you name each user-visible string

284 and put it into a messages file.

285 The extension's manifest,

286 CSS files,

287 and JavaScript code

288 use each string's name to get its localized version.

289 </p>

290 <p>

291 Here's what the extension looks like when it's internationalized

292 (note that it still has only English strings):

293 </p>

294 <img src="images/i18n-after-1.gif" alt="In the manifest.json file, "Hello W orld" has been changed to "__MSG_extName__", and a new "defa ult_locale" item has the value "en". In the JavaScript file, &quo t;Hello World" has been changed to chrome.i18n.getMessage("extName&quo t;). A new file named _locales/en/messages.json defines "extName"." wi dth="782" height="228">

295 <p class="note">

296 <b>Important:</b>

297 If an extension has a <code>_locales</code> directory,

298 the <a href="manifest.html">manifest</a>

299 <b>must</b> define "default_locale".

300 </p>

301 <p>

302 Some notes about internationalizing extensions:

303 </p>

304 <ul>

305 <li><p>

306 You can use any of the <a href="#overview-locales">supported locales</a>.

307 If you use an unsupported locale,

308 Google Chrome ignores it.

309 </p></li>

310 <li>

311 In <code>manifest.json</code>

312 and CSS files,

313 refer to a string named <em>messagename</em> like this:

314 <pre>__MSG_<em>messagename</em>__</pre>

315 </li>

316 <li>

317 In your extension's JavaScript code,

318 refer to a string named <em>messagename</em>

319 like this:

320 <pre>chrome.i18n.getMessage("<em>messagename</em>")</pre>

321 </li><li> <p>

322 In each call to <code>getMessage()</code>,

323 you can supply up to 9 strings

324 to be included in the message.

325 See <a href="#examples-getMessage">Examples: getMessage</a>

326 for details.

327 </p>

328 </li>

329 <li><p>

330 Some messages, such as <code>@@bidi_dir</code> and <code>@@ui_locale</code>,

331 are provided by the internationalization system.

332 See the <a href="#overview-predefined">Predefined messages</a> section

333 for a full list of predefined message names.

334 </p>

335 </li>

336 <li>

337 In <code>messages.json</code>,

338 each user-visible string has a name, a "message" item,

339 and an optional "description" item.

340 The name is a key

341 such as "extName" or "search_string"

342 that identifies the string.

343 The "message" specifies

344 the value of the string in this locale.

345 The optional "description"

346 provides help to translators,

347 who might not be able to see how the string is used in your extension.

348 For example:

349 <pre>{

350 "search_string": {

351 "message": "hello%20world",

352 "description": "The string we search for. Put %20 between words that go toge ther."

353 },

354 ...

355 }</pre>

356 <p>

357 For more information, see

358 <a href="i18n-messages.html">Formats: Locale-Specific Messages</a>.

359 </p>

360 </li>

361 </ul>

362 <p>

363 Once an extension is internationalized,

364 translating it is simple.

365 You copy <code>messages.json</code>,

366 translate it,

367 and put the copy into a new directory under <code>_locales</code>.

368 For example, to support Spanish,

369 just put a translated copy of <code>messages.json</code>

370 under <code>_locales/es</code>.

371 The following figure shows the previous extension

372 with a new Spanish translation.

373 </p>

374 <img src="images/i18n-after-2.gif" alt="This looks the same as the previous figu re, but with a new file at _locales/es/messages.json that contains a Spanish tra nslation of the messages." width="782" height="358">

375 <h2 id="overview-predefined">Predefined messages</h2>

376 <p>

377 The internationalization system provides a few predefined

378 messages to help you localize your extension.

379 These include <code>@@ui_locale</code>,

380 so you can detect the current UI locale,

381 and a few <code>@@bidi_...</code> messages

382 that let you detect the text direction.

383 The latter messages have similar names to constants in the

384 <a href="http://code.google.com/apis/gadgets/docs/i18n.html#BIDI">

385 gadgets BIDI (bi-directional) API</a>.

386 </p>

387 <p>

388 The special message <code>@@extension_id</code>

389 can be used in the CSS and JavaScript files of any extension,

390 whether or not the extension is localized.

391 This message doesn't work in manifest files.

392 </p>

393 <p>

394 The following table describes each predefined message.

395 </p>

396 <table>

397 <tbody><tr>

398 <th>Message name</th> <th>Description</th>

399 </tr>

400 <tr>

401 <td> <code>@@extension_id</code> </td>

402 <td>The extension ID;

403 you might use this string to construct URLs

404 for resources inside the extension.

405 Even unlocalized extensions can use this message.

406 <br>

407 <b>Note:</b> You can't use this message in a manifest file.

408 </td>

409 </tr>

410 <tr>

411 <td> <code>@@ui_locale</code> </td>

412 <td>The current locale;

413 you might use this string to construct locale-specific URLs. </td>

414 </tr>

415 <tr>

416 <td> <code>@@bidi_dir</code> </td>

417 <td> The text direction for the current locale,

418 either "ltr" for left-to-right languages such as English

419 or "rtl" for right-to-left languages such as Japanese. </td>

420 </tr>

421 <tr>

422 <td> <code>@@bidi_reversed_dir</code> </td>

423 <td> If the <code>@@bidi_dir</code> is "ltr", then this is "rtl";

424 otherwise, it's "ltr". </td>

425 </tr>

426 <tr>

427 <td> <code>@@bidi_start_edge</code> </td>

428 <td> If the <code>@@bidi_dir</code> is "ltr", then this is "left";

429 otherwise, it's "right". </td>

430 </tr>

431 <tr>

432 <td> <code>@@bidi_end_edge</code> </td>

433 <td> If the <code>@@bidi_dir</code> is "ltr", then this is "right";

434 otherwise, it's "left". </td>

435 </tr>

436 </tbody></table>

437 <p>

438 Here's an example of using <code>@@extension_id</code> in a CSS file

439 to construct a URL:

440 </p>

441 <pre>body {

442 <b>background-image:url('chrome-extension://__MSG_@@extension_id__/background. png');</b>

443 }

444 </pre>

445 <p>

446 If the extension ID is abcdefghijklmnopqrstuvwxyzabcdef,

447 then the bold line in the previous code snippet becomes:

448 </p>

449 <pre>background-image:url('chrome-extension://abcdefghijklmnopqrstuvwxyzabcdef/b ackground.png');

450 </pre>

451 <p>

452 Here's an example of using <code>@@bidi_*</code> messages in a CSS file:

453 </p>

454 <pre>body {

455 <b>direction: __MSG_@@bidi_dir__;</b>

456 }

457 div#header {

458 margin-bottom: 1.05em;

459 overflow: hidden;

460 padding-bottom: 1.5em;

461 <b>padding-__MSG_@@bidi_start_edge__: 0;</b>

462 <b>padding-__MSG_@@bidi_end_edge__: 1.5em;</b>

463 position: relative;

464 }

465 </pre>

466 <p>

467 For left-to-right languages such as English,

468 the bold lines become:

469 </p>

470 <pre>dir: ltr;

471 padding-left: 0;

472 padding-right: 1.5em;

473 </pre>

474 <h2 id="overview-locales">Locales</h2>

475 <p>

476 You can choose from many locales,

477 including some (such as <code>en</code>)

478 that let a single translation support multiple variations of a language

479 (such as <code>en_GB</code> and <code>en_US</code>).

480 </p>

481 <h3 id="locales-supported">Supported locales</h3>

482 <p>

483 Extensions can use any of the

484 <a href="http://code.google.com/chrome/webstore/docs/i18n.html#localeTable">loca les that the Chrome Web Store supports</a>.

485 </p>

486 <h3 id="locales-usage">How extensions find strings</h3>

487 <p>

488 You don't have to define every string for every locale

489 that your internationalized extension supports.

490 As long as the default locale's <code>messages.json</code> file

491 has a value for every string,

492 your extension will run no matter how sparse a translation is.

493 Here's how the extension system searches for a message:

494 </p>

495 <ol>

496 <li>

497 Search the messages file (if any)

498 for the user's preferred locale.

499 For example, when Google Chrome's locale is set to

500 British English (<code>en_GB</code>),

501 the system first looks for the message in

502 <code>_locales/en_GB/messages.json</code>.

503 If that file exists and the message is there,

504 the system looks no further.

505 </li>

506 <li>

507 If the user's preferred locale has a region

508 (that is, the locale has an underscore: _),

509 search the locale without that region.

510 For example, if the <code>en_GB</code> messages file

511 doesn't exist or doesn't contain the message,

512 the system looks in the <code>en</code> messages file.

513 If that file exists and the message is there,

514 the system looks no further.

515 </li>

516 <li>

517 Search the messages file for the extension's default locale.

518 For example, if the extension's "default_locale" is set to "es",

519 and neither <code>_locales/en_GB/messages.json</code>

520 nor <code>_locales/en/messages.json</code> contains the message,

521 the extension uses the message from

522 <code>_locales/es/messages.json</code>.

523 </li>

524 </ol>

525 <p>

526 In the following figure,

527 the message named "colores" is in all three locales

528 that the extension supports,

529 but "extName" is in only two of the locales.

530 Wherever a user running Google Chrome in US English sees the label "Colors",

531 a user of British English sees "Colours".

532 Both US English and British English users

533 see the extension name "Hello World".

534 Because the default language is Spanish,

535 users running Google Chrome in any non-English language

536 see the label "Colores" and the extension name "Hola mundo".

537 </p>

538 <img src="images/i18n-strings.gif" alt="Four files: manifest.json and three mess ages.json files (for es, en, and en_GB). The es and en files show entries for m essages named "extName" and "colores"; the en_GB file has ju st one entry (for "colores")." width="493" height="488">

539 <h3 id="locales-testing">How to set your browser's locale</h3>

540 <p>

541 To test translations, you might want to set your browser's locale.

542 This section tells you how to set the locale in

543 <a href="#testing-win">Windows</a>,

544 <a href="#testing-mac">Mac OS X</a>, and

545 <a href="#testing-linux">Linux</a>.

546 </p>

547 <h4 id="testing-win">Windows</h4>

548 <p>

549 You can change the locale using either

550 a locale-specific shortcut

551 or the Google Chrome UI.

552 The shortcut approach is quicker, once you've set it up,

553 and it lets you use several languages at once.

554 </p>

555 <h5 id="win-shortcut">Using a locale-specific shortcut</h5>

556 <p>

557 To create and use a shortcut that launches Google Chrome

558 with a particular locale:

559 </p>

560 <ol>

561 <li>

562 Make a copy of the Google Chrome shortcut

563 that's already on your desktop.

564 </li>

565 <li>

566 Rename the new shortcut to match the new locale.

567 </li>

568 <li>

569 Change the shortcut's properties

570 so that the Target field specifies the

571 <code>--lang</code> and

572 <code>--user-data-dir</code> flags.

573 The target should look something like this:

574 <pre><em>path_to_chrome.exe</em> --lang=<em>locale</em> --user-data-dir=c:\<em>l ocale_profile_dir</em></pre>

575 </li>

576 <li>

577 Launch Google Chrome by double-clicking the shortcut.

578 </li>

579 </ol>

580 <p>

581 For example, to create a shortcut

582 that launches Google Chrome in Spanish (<code>es</code>),

583 you might create a shortcut named <code>chrome-es</code>

584 that has the following target:

585 </p>

586 <pre><em>path_to_chrome.exe</em> --lang=es --user-data-dir=c:\chrome-profile-es< /pre>

587 <p>

588 You can create as many shortcuts as you like,

589 making it easy to test your extension in multiple languages.

590 For example:

591 </p>

592 <pre><em>path_to_chrome.exe</em> --lang=en --user-data-dir=c:\chrome-profile-en

593 <em>path_to_chrome.exe</em> --lang=en_GB --user-data-dir=c:\chrome-profile-en_GB

594 <em>path_to_chrome.exe</em> --lang=ko --user-data-dir=c:\chrome-profile-ko</pre>

595 <p class="note">

596 <b>Note:</b>

597 Specifying <code>--user-data-dir</code> is optional but handy.

598 Having one data directory per locale

599 lets you run the browser

600 in several languages at the same time.

601 A disadvantage is that because the locales' data isn't shared,

602 you have to install your extension multiple times — once per locale,

603 which can be challenging when you don't speak the language.

604 For more information, see

605 <a href="http://www.chromium.org/developers/creating-and-using-profiles">Creatin g and Using Profiles</a>.

606 </p>

607 <h5 id="win-ui">Using the UI</h5>

608 <p>

609 Here's how to change the locale using the UI on Google Chrome for Windows:

610 </p>

611 <ol>

612 <li> Wrench icon > <b>Options</b> </li>

613 <li> Choose the <b>Under the Hood</b> tab </li>

614 <li> Scroll down to <b>Web Content</b> </li>

615 <li> Click <b>Change font and language settings</b> </li>

616 <li> Choose the <b>Languages</b> tab </li>

617 <li> Use the drop down to set the <b>Google Chrome language</b> </li>

618 <li> Restart Chrome </li>

619 </ol>

620 <h4 id="testing-mac">Mac OS X</h4>

621 <p>

622 To change the locale on Mac,

623 you use the system preferences.

624 </p>

625 <ol>

626 <li> From the Apple menu, choose <b>System Preferences</b> </li>

627 <li> Under the <b>Personal</b> section, choose <b>International</b> </li>

628 <li> Choose your language and location </li>

629 <li> Restart Chrome </li>

630 </ol>

631 <h4 id="testing-linux">Linux</h4>

632 <p>

633 To change the locale on Linux,

634 first quit Google Chrome.

635 Then, all in one line,

636 set the LANGUAGE environment variable

637 and launch Google Chrome.

638 For example:

639 </p>

640 <pre>LANGUAGE=es ./chrome

641 </pre>

642 <h2 id="overview-examples">Examples</h2>

643 <p>

644 You can find simple examples of internationalization in the

645 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extension s/docs/examples/api/i18n/">examples/api/i18n</a>

646 directory.

647 For a complete example, see

648 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extension s/docs/examples/extensions/news/">examples/extensions/news</a>.

649 For other examples and for help in viewing the source code, see

650 <a href="samples.html">Samples</a>.

651 </p>

652 <h3 id="examples-getMessage">Examples: getMessage</h3>

653 <!--

654 [PENDING: improve this section. it should probably start with a

655 one-variable example that includes the messages.json code.]

656 -->

657 <p>

658 The following code gets a localized message from the browser

659 and displays it as a string.

660 It replaces two placeholders within the message with the strings

661 "string1" and "string2".

662 </p>

663 <pre>function getMessage() {

664 var message = chrome.i18n.getMessage("click_here", ["string1", "string2"]);

665 document.getElementById("languageSpan").innerHTML = message;

666 }

667 </pre>

668 <p>

669 Here's how you'd supply and use a single string:

670 </p>

671 <pre><em>// In JavaScript code</em>

672 status.innerText = chrome.i18n.getMessage("error", errorDetails);

673 <em>// In messages.json</em>

674 "error": {

675 "message": "Error: $details$",

676 "description": "Generic error template. Expects error parameter to be passed i n.",

677 "placeholders": {

678 "details": {

679 "content": "$1",

680 "example": "Failed to fetch RSS feed."

681 }

682 }

683 }

684 </pre>

685 <p>

686 For more information about placeholders, see the

687 <a href="i18n-messages.html">Locale-Specific Messages</a> page.

688 For details on calling <code>getMessage()</code>, see the

689 <a href="#method-getMessage">API reference</a>.

690 </p>

691 <h3 id="example-accept-languages">Example: getAcceptLanguages</h3>

692 <p>

693 The following code gets accept-languages from the browser and displays them as a

694 string by separating each accept-language with ','.

695 </p>

696 <pre>function getAcceptLanguages() {

697 chrome.i18n.getAcceptLanguages(function(languageList) {

698 var languages = languageList.join(",");

699 document.getElementById("languageSpan").innerHTML = languages;

700 })

701 }

702 </pre>

703 <p>

704 For details on calling <code>getAcceptLanguages()</code>, see the

705 <a href="#method-getAcceptLanguages">API reference</a>.

706 </p>

707 <!-- END AUTHORED CONTENT -->

708 </div>

709 <!-- API PAGE -->

710 <div class="apiPage">

711 <a name="apiReference"></a>

712 <h2>API reference: chrome.i18n</h2>

713 <!-- PROPERTIES -->

714 <!-- /apiGroup -->

715 <!-- METHODS -->

716 <div id="methodsTemplate" class="apiGroup">

717 <a name="global-methods"></a>

718 <h3>Methods</h3>

719 <!-- iterates over all functions -->

720 <div class="apiItem">

721 <a name="method-getAcceptLanguages"></a> <!-- method-anchor -->

722 <h4>getAcceptLanguages</h4>

723 <div class="summary">

724 <!-- Note: intentionally longer 80 columns -->

725 <span>chrome.i18n.getAcceptLanguages</span>(<span class="null" ><span>function</span>

726 <var><span>callback</span></var></span>)</div>

727 <div class="description">

728 <p>Gets the accept-languages of the browser. This is different f rom the locale used by the browser; to get the locale, use <code>window.navigato r.language</code>.</p>

729 <!-- PARAMETERS -->

730 <h4>Parameters</h4>

731 <dl>

732 <div>

733 <div>

734 <dt>

735 <var>callback</var>

736 <em>

737 <!-- TYPE -->

738 <div style="display:inline">

739 (

740 <span id="typeTemplate">

741 <span>

742 <span>function</span>

743 </span>

744 </span>

745 )

746 </div>

747 </em>

748 </dt>

749 <dd class="todo">

750 Undocumented.

751 </dd>

752 <!-- OBJECT PROPERTIES -->

753 <!-- OBJECT METHODS -->

754 <!-- OBJECT EVENT FIELDS -->

755 <!-- FUNCTION PARAMETERS -->

756 </div>

757 </div>

758 </dl>

759 <!-- RETURNS -->

760 <dl>

761 </dl>

762 <!-- CALLBACK -->

763 <div>

764 <div>

765 <h4>Callback function</h4>

766 <p>

767 The <em>callback</em> parameter should specify a function

768 that looks like this:

769 </p>

770 <!-- Note: intentionally longer 80 columns -->

771 <pre>function(<span>array of string languages</span>) <span cl ass="subdued">{...}</span>;</pre>

772 <dl>

773 <div>

774 <div>

775 <dt>

776 <var>languages</var>

777 <em>

778 <!-- TYPE -->

779 <div style="display:inline">

780 (

781 <span id="typeTemplate">

782 <span>

783 <span>

784 array of <span><span>

785 <span>

786 <span>string</span>

787 </span>

788 </span></span>

789 </span>

790 </span>

791 </span>

792 )

793 </div>

794 </em>

795 </dt>

796 <dd>Array of the accept languages of the browser, such as en-US,en,zh- CN</dd>

797 <!-- OBJECT PROPERTIES -->

798 <!-- OBJECT METHODS -->

799 <!-- OBJECT EVENT FIELDS -->

800 <!-- FUNCTION PARAMETERS -->

801 </div>

802 </div>

803 </dl>

804 </div>

805 </div>

806 <!-- MIN_VERSION -->

807 </div> <!-- /description -->

808 </div><div class="apiItem">

809 <a name="method-getMessage"></a> <!-- method-anchor -->

810 <h4>getMessage</h4>

811 <div class="summary"><span>string</span>

812 <!-- Note: intentionally longer 80 columns -->

813 <span>chrome.i18n.getMessage</span>(<span class="null"><span>s tring</span>

814 <var><span>messageName</span></var></span><span class="opt ional"><span>, </span><span>any</span>

815 <var><span>substitutions</span></var></span>)</div>

816 <div class="description">

817 <p>Gets the localized string for the specified message. If the m essage is missing, this method returns an empty string (''). If the format of th e <code>getMessage()</code> call is wrong — for example, <em>messageName</em> is not a string or the <em>substitutions</em> array has more than 9 elements — thi s method returns <code>undefined</code>.</p>

818 <!-- PARAMETERS -->

819 <h4>Parameters</h4>

820 <dl>

821 <div>

822 <div>

823 <dt>

824 <var>messageName</var>

825 <em>

826 <!-- TYPE -->

827 <div style="display:inline">

828 (

829 <span id="typeTemplate">

830 <span>

831 <span>string</span>

832 </span>

833 </span>

834 )

835 </div>

836 </em>

837 </dt>

838 <dd>The name of the message, as specified in the <a href="i18n-message s.html"><code>messages.json</code></a> file.</dd>

839 <!-- OBJECT PROPERTIES -->

840 <!-- OBJECT METHODS -->

841 <!-- OBJECT EVENT FIELDS -->

842 <!-- FUNCTION PARAMETERS -->

843 </div>

844 </div><div>

845 <div>

846 <dt>

847 <var>substitutions</var>

848 <em>

849 <!-- TYPE -->

850 <div style="display:inline">

851 (

852 <span class="optional">optional</span>

853 <span id="typeTemplate">

854 <span>

855 <span>any</span>

856 </span>

857 </span>

858 )

859 </div>

860 </em>

861 </dt>

862 <dd>Up to 9 substitution strings, if the message requires any.</dd>

863 <!-- OBJECT PROPERTIES -->

864 <!-- OBJECT METHODS -->

865 <!-- OBJECT EVENT FIELDS -->

866 <!-- FUNCTION PARAMETERS -->

867 </div>

868 </div>

869 </dl>

870 <!-- RETURNS -->

871 <h4>Returns</h4>

872 <dl>

873 <div>

874 <div>

875 <dt>

876 <em>

877 <!-- TYPE -->

878 <div style="display:inline">

879 (

880 <span id="typeTemplate">

881 <span>

882 <span>string</span>

883 </span>

884 </span>

885 )

886 </div>

887 </em>

888 </dt>

889 <dd>Message localized for current locale.</dd>

890 <!-- OBJECT PROPERTIES -->

891 <!-- OBJECT METHODS -->

892 <!-- OBJECT EVENT FIELDS -->

893 <!-- FUNCTION PARAMETERS -->

894 </div>

895 </div>

896 </dl>

897 <!-- CALLBACK -->

898 <!-- MIN_VERSION -->

899 </div> <!-- /description -->

900 </div> <!-- /apiItem -->

901 </div> <!-- /apiGroup -->

902 <!-- EVENTS -->

903 <!-- /apiGroup -->

904 <!-- TYPES -->

905 <!-- /apiGroup -->

906 </div> <!-- /apiPage -->

907 </div> <!-- /gc-pagecontent -->

908 </div> <!-- /g-section -->

909 </div> <!-- /codesiteContent -->

910 <div id="gc-footer" --="">

911 <div class="text">

912 <p>

913 Except as otherwise <a href="http://code.google.com/policies.html#restrictions ">noted</a>,

914 the content of this page is licensed under the <a rel="license" href="http://c reativecommons.org/licenses/by/3.0/">Creative Commons

915 Attribution 3.0 License</a>, and code samples are licensed under the

916 <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD Lic ense</a>.

917 </p>

918 <p>

919 ©2011 Google

920 </p>

921 <!-- begin analytics -->

922 <script src="https://www.google-analytics.com/urchin.js" type="text/javascript"> </script>

923 <script src="https://www.google-analytics.com/ga.js" type="text/javascript"></sc ript>

924 <script type="text/javascript">

925 // chrome doc tracking

926 try {

927 var engdocs = _gat._getTracker("YT-10763712-2");

928 engdocs._trackPageview();

929 } catch(err) {}

930 // code.google.com site-wide tracking

931 try {

932 _uacct="UA-18071-1";

933 _uanchor=1;

934 _uff=0;

935 urchinTracker();

936 }

937 catch(e) {/* urchinTracker not available. */}

938 </script>

939 <!-- end analytics -->

940 </div>

941 </div> <!-- /gc-footer -->

942 </div> <!-- /gc-container -->

943 </body></html>

OLD	NEW