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

   1 <h1>Formats: Locale-Specific Messages</h1>
   2
   3
   4 <p>
   5 Each internationalized extension or app has at least one
   6 file named <code>messages.json</code>
   7 that provides locale-specific strings.
   8 This page describes the format of <code>messages.json</code> files.
   9 For information on how to internationalize and localize,
  10 see the <a href="i18n.html">Internationalization</a> page.
  11 </p>
  12
  13 <h2 id="overview"> Field summary </h2>
  14
  15 <p>
  16 The following code shows the supported fields for
  17 <code>messages.json</code>.
  18 Only the "<em>name</em>" and "message" fields are required.
  19 </p>
  20
  21 <pre data-filename="manifest.json">
  22 {
  23   "<a href="#name"><em>name</em></a>": {
  24     "<a href="#message">message</a>": "<em>Message text, with optional placeholders.</em>",
  25     "<a href="#description">description</a>": "<em>Translator-aimed description of the message.</em>",
  26     "<a href="#placeholders">placeholders</a>": {
  27       "<em>placeholder_name</em>": {
  28         "content": "<em>A string to be placed within the message.</em>",
  29         "example": "<em>Translator-aimed example of the placeholder string.</em>"
  30       },
  31       ...
  32     }
  33   },
  34   ...
  35 }
  36 </pre>
  37
  38 <h2 id="example"> Example </h2>
  39
  40 <p>
  41 Here's a <code>messages.json</code> file
  42 that defines three messages
  43 named "prompt_for_name", "hello", and "bye":
  44 </p>
  45
  46 <pre data-filename="messages.json">
  47 {
  48   "prompt_for_name": {
  49     "message": "What's your name?",
  50     "description": "Ask for the user's name"
  51   },
  52   "hello": {
  53     "message": "Hello, $USER$",
  54     "description": "Greet the user",
  55     "placeholders": {
  56       "user": {
  57         "content": "$1",
  58         "example": "Cira"
  59       }
  60     }
  61   },
  62   "bye": {
  63     "message": "Goodbye, $USER$. Come back to $OUR_SITE$ soon!",
  64     "description": "Say goodbye to the user",
  65     "placeholders": {
  66       "our_site": {
  67         "content": "Example.com",
  68       },
  69       "user": {
  70         "content": "$1",
  71         "example": "Cira"
  72       }
  73     }
  74   }
  75 }
  76 </pre>
  77
  78
  79 <h2 id="field_details">Field details</h2>
  80
  81 <p>
  82 This section describes each field
  83 that can appear in a <code>messages.json</code> file.
  84 For details on how the messages file is used &mdash;
  85 for example, what happens when a locale doesn't define
  86 all the messages &mdash;
  87 see <a href="i18n.html">Internationalization</a>.
  88 </p>
  89
  90
  91 <h3 id="name">name</h3>
  92
  93 <p>
  94 Actually, there's no field called "name".
  95 This field's name is the name of the message &mdash;
  96 the same <em>name</em> that you see in
  97 <code>__MSG_<em>name</em>__</code>
  98 or <code>getMessage("<em>name</em>")</code>.
  99 </p>
 100
 101 <p>
 102 The name is a case-insensitive key
 103 that lets you retrieve the localized message text.
 104 The name can include the following characters:
 105 </p>
 106
 107 <ul>
 108   <li> A-Z </li>
 109   <li> a-z </li>
 110   <li> 0-9 </li>
 111   <li> _ (underscore) </li>
 112   <li> @ </li>
 113 </ul>
 114
 115 <p class="note">
 116 <b>Note:</b>
 117 Don't define names that begin with "@@".
 118 Those names are reserved for
 119 <a href="i18n.html#overview-predefined">predefined messages</a>.
 120 </p>
 121
 122 <p>
 123 Here are three examples of names,
 124 taken from the <a href="#example">Example</a> section:
 125 </p>
 126
 127 <pre>
 128 "prompt_for_name": {
 129   ...
 130 },
 131 "hello": {
 132   ...
 133 },
 134 "bye": {
 135   ...
 136 }
 137 </pre>
 138
 139 <p>
 140 For more examples of using names, see the
 141 <a href="i18n.html">Internationalization</a> page.
 142 </p>
 143
 144
 145 <h3 id="message">message</h3>
 146
 147 <p>
 148 The translated message,
 149 in the form of a string that can contain
 150 <a href="#placeholders">placeholders</a>.
 151 Use <code>$<em>placeholder_name</em>$</code>
 152 (case insensitive)
 153 to refer to a particular placeholder.
 154 For example, you can refer to a placeholder named "our_site" as
 155 <code>$our_site$</code>, <code>$OUR_SITE$</code>, or <code>$oUR_sITe$</code>.
 156 </p>
 157
 158 <p>
 159 Here are three examples of messages,
 160 taken from the <a href="#example">Example</a> section:
 161 </p>
 162
 163 <pre>
 164 "message": "What's your name?"
 165 ...
 166 "message": "Hello, $USER$"
 167 ...
 168 "message": "Goodbye, $USER$. Come back to $OUR_SITE$ soon!"
 169 </pre>
 170
 171 <p>
 172 To put a dollar sign (<code>$</code>) into the string,
 173 use <code>$$</code>.
 174 For example, use the following code to specify the message
 175 <b>Amount (in $)</b>:
 176
 177 <pre>
 178 "message": "Amount (in $$)"
 179 </pre>
 180
 181 <p>
 182 Although placeholders such as <code>$USER$</code> are
 183 the preferred way of referring to <em>substitution strings</em>
 184 (strings specified using the <em>substitutions</em> parameter of
 185 $ref:i18n.getMessage)
 186 you can also refer to substitution strings directly
 187 within the message.
 188 For example, the following message
 189 refers to the first three substitution strings passed into
 190 <code>getMessage()</code>:
 191 </p>
 192
 193 <pre>
 194 "message": "Params: $1, $2, $3"
 195 </pre>
 196
 197 <p>
 198 Despite that example,
 199 we recommend that you stick to using placeholders
 200 instead of <code>$<em>n</em></code> strings
 201 within your messages.
 202 Think of placeholders as good variable names.
 203 A week after you write your code,
 204 you'll probably forget what <code>$1</code> refers to,
 205 but you'll know what your placeholders refer to.
 206 For more information on placeholders and substitution strings, see
 207 the <a href="#placeholders">placeholders</a> section.
 208 </p>
 209
 210 <h3 id="description">description</h3>
 211
 212 <p>
 213 <em>Optional.</em>
 214 A description of the message,
 215 intended to give context
 216 or details to help the translator
 217 make the best possible translation.
 218 </p>
 219
 220 <p>
 221 Here are three examples of descriptions,
 222 taken from the <a href="#example">Example</a> section:
 223 </p>
 224
 225 <pre>
 226 "description": "Ask for the user's name"
 227 ...
 228 "description": "Greet the user"
 229 ...
 230 "description": "Say goodbye to the user"
 231 </pre>
 232
 233 <h3 id="placeholders">placeholders</h3>
 234
 235 <p>
 236 <em>Optional.</em>
 237 Defines one or more substrings
 238 to be used within the message.
 239 Here are two reasons you might want to use a placeholder:
 240 </p>
 241
 242 <ul>
 243   <li>
 244     To define the text
 245     for a part of your message
 246     that shouldn't be translated.
 247     Examples: HTML code, trademarked names, formatting specifiers.
 248   </li>
 249   <li>
 250     To refer to a substitution string passed into
 251     <code>getMessage()</code>.
 252     Example: <code>$1</code>.
 253   </li>
 254 </ul>
 255
 256 <p>
 257 Each placeholder has a name,
 258 a "content" item,
 259 and an optional "example" item.
 260 A placeholder's name is case-insensitive
 261 and can contain the same characters
 262 as a <a href="#name">message name</a>.
 263 </p>
 264
 265 <p>
 266 The "content" item's value is a string
 267 that can refer to substitution strings, which are
 268 specified using the
 269 $ref:i18n.getMessage method's
 270 <em>substitutions</em> parameter.
 271 The value of a "content" item is typically something like
 272 "Example.com" or "$1".
 273 If you refer to
 274 a substitution string that doesn't exist,
 275 you get an empty string.
 276 The following table shows how
 277 <code>$<em>n</em></code> strings correspond to
 278 strings specified by the <em>substitutions</em> parameter.
 279 </p>
 280
 281 <table class="simple">
 282 <tr>
 283 <th> <em>substitutions</em> parameter </th>
 284 <th> Value of $1</th>
 285 <th> Value of $2</th>
 286 <th> Value of $3</th>
 287 </tr>
 288 <tr>
 289   <td> <code>userName</code> </td>
 290   <td> value of <code>userName</code> </td>
 291   <td> <code>""</code> </td>
 292   <td> <code>""</code> </td>
 293 </tr>
 294 <tr>
 295   <td> <code>["Cira", "Kathy"]</code> </td>
 296   <td> <code>"Cira"</code> </td>
 297   <td> <code>"Kathy"</code> </td>
 298   <td> <code>""</code> </td>
 299 </tr>
 300 </table>
 301
 302 <p>
 303 The "example" item
 304 (optional, but highly recommended)
 305 helps translators by showing how the content appears to the end user.
 306 For example, a placeholder
 307 for a dollar amount
 308 should have an example like <code>"$23.45"</code>.
 309 </p>
 310
 311 <p>
 312 The following snippet,
 313 taken from the <a href="#example">Example</a> section,
 314 shows a "placeholders" item that contains two placeholders
 315 named "our_site" and "user".
 316 The "our_site" placeholder has no "example" item
 317 because its value is obvious from the "content" field.
 318 </p>
 319
 320 <pre>
 321 "placeholders": {
 322   "our_site": {
 323     "content": "Example.com",
 324   },
 325   "user": {
 326     "content": "$1",
 327     "example": "Cira"
 328   }
 329 }
 330 </pre>