1 page.title=String Resources 2 parent.title=Resource Types 3 parent.link=available-resources.html 4 @jd:body 5 6 <p>A string resource provides text strings for your application 7 with optional text styling and formatting. There are three types of resources that can provide 8 your application with strings:</p> 9 10 <dl> 11 <dt><a href="#String">String</a></dt> 12 <dd>XML resource that provides a single string.</dd> 13 <dt><a href="#StringArray">String Array</a></dt> 14 <dd>XML resource that provides an array of strings.</dd> 15 <dt><a href="#Plurals">Quantity Strings (Plurals)</a></dt> 16 <dd>XML resource that carries different strings for pluralization.</dd> 17 </dl> 18 19 <p>All strings are capable of applying some styling markup and formatting arguments. For 20 information about styling and formatting strings, see the section about <a 21 href="#FormattingAndStyling">Formatting and Styling</a>.</p> 22 23 24 25 26 <h2 id="String">String</h2> 27 28 <p>A single string that can be referenced from the application or from other resource files (such 29 as an XML layout).</p> 30 31 <p class="note"><strong>Note:</strong> A string is a simple resource that is referenced 32 using the value provided in the {@code name} attribute (not the name of the XML file). So, you can 33 combine string resources with other simple resources in the one XML file, 34 under one {@code <resources>} element.</p> 35 36 <dl class="xml"> 37 38 <dt>file location:</dt> 39 <dd><code>res/values/<em>filename</em>.xml</code><br/> 40 The filename is arbitrary. The {@code <string>} element's {@code name} will be used as the 41 resource ID.</dd> 42 43 <dt>compiled resource datatype:</dt> 44 <dd>Resource pointer to a {@link java.lang.String}.</dd> 45 46 <dt>resource reference:</dt> 47 <dd> 48 In Java: <code>R.string.<em>string_name</em></code><br/> 49 In XML:<code>@string/<em>string_name</em></code> 50 </dd> 51 52 <dt>syntax:</dt> 53 <dd> 54 <pre class="stx"> 55 <?xml version="1.0" encoding="utf-8"?> 56 <<a href="#string-resources-element">resources</a>> 57 <<a href="#string-element">string</a> 58 name="<em>string_name</em>" 59 ><em>text_string</em></string> 60 </resources> 61 </pre> 62 </dd> 63 64 <dt>elements:</dt> 65 <dd> 66 <dl class="tag-list"> 67 68 <dt id="string-resources-element"><code><resources></code></dt> 69 <dd><strong>Required.</strong> This must be the root node. 70 <p>No attributes.</p> 71 </dd> 72 <dt id="string-element"><code><string></code></dt> 73 <dd>A string, which can include styling tags. Beware that you must escape apostrophes and 74 quotation marks. For more information about how to properly style and format your strings see <a 75 href="#FormattingAndStyling">Formatting and Styling</a>, below. 76 <p class="caps">attributes:</p> 77 <dl class="atn-list"> 78 <dt><code>name</code></dt> 79 <dd><em>String</em>. A name for the string. This name will be used as the resource 80 ID.</dd> 81 </dl> 82 </dd> 83 84 </dl> 85 </dd> <!-- end elements and attributes --> 86 87 <dt>example:</dt> 88 <dd>XML file saved at <code>res/values/strings.xml</code>: 89 <pre> 90 <?xml version="1.0" encoding="utf-8"?> 91 <resources> 92 <string name="hello">Hello!</string> 93 </resources> 94 </pre> 95 96 <p>This layout XML applies a string to a View:</p> 97 <pre> 98 <TextView 99 android:layout_width="fill_parent" 100 android:layout_height="wrap_content" 101 <strong>android:text="@string/hello"</strong> /> 102 </pre> 103 104 <p>This application code retrieves a string:</p> 105 <pre> 106 String string = {@link android.content.Context#getString(int) getString}(R.string.hello); 107 </pre> 108 <p>You can use either {@link android.content.Context#getString(int)} or 109 {@link android.content.Context#getText(int)} to retrieve a string. {@link 110 android.content.Context#getText(int)} will retain any rich text styling applied to the string.</p> 111 112 </dd> <!-- end example --> 113 114 </dl> 115 116 117 118 119 120 121 122 123 124 <h2 id="StringArray">String Array</h2> 125 126 <p>An array of strings that can be referenced from the application.</p> 127 128 <p class="note"><strong>Note:</strong> A string array is a simple resource that is referenced 129 using the value provided in the {@code name} attribute (not the name of the XML file). As 130 such, you can combine string array resources with other simple resources in the one XML file, 131 under one {@code <resources>} element.</p> 132 133 <dl class="xml"> 134 135 <dt>file location:</dt> 136 <dd><code>res/values/<em>filename</em>.xml</code><br/> 137 The filename is arbitrary. The {@code <string-array>} element's {@code name} will be used as the 138 resource ID.</dd> 139 140 <dt>compiled resource datatype:</dt> 141 <dd>Resource pointer to an array of {@link java.lang.String}s.</dd> 142 143 <dt>resource reference:</dt> 144 <dd> 145 In Java: <code>R.array.<em>string_array_name</em></code> 146 </dd> 147 148 <dt>syntax:</dt> 149 <dd> 150 <pre class="stx"> 151 <?xml version="1.0" encoding="utf-8"?> 152 <<a href="#string-array-resources-element">resources</a>> 153 <<a href="#string-array-element">string-array</a> 154 name="<em>string_array_name</em>"> 155 <<a href="#string-array-item-element">item</a> 156 ><em>text_string</em></item> 157 </string-array> 158 </resources> 159 </pre> 160 </dd> 161 162 <dt>elements:</dt> 163 <dd> 164 <dl class="tag-list"> 165 <dt id="string-array-resources-element"><code><resources></code></dt> 166 <dd><strong>Required.</strong> This must be the root node. 167 <p>No attributes.</p> 168 </dd> 169 <dt id="string-array-element"><code><string-array></code></dt> 170 <dd>Defines an array of strings. Contains one or more {@code <item>} elements. 171 <p class="caps">attributes:</p> 172 <dl class="atn-list"> 173 <dt><code>name</code></dt> 174 <dd><em>String</em>. A name for the array. This name will be used as the resource 175 ID to reference the array.</dd> 176 </dl> 177 178 </dd> 179 <dt id="string-array-item-element"><code><item></code></dt> 180 <dd>A string, which can include styling tags. The value can be a reference to another 181 string resource. Must be a child of a {@code <string-array>} element. Beware that you 182 must escape apostrophes and 183 quotation marks. See <a href="#FormattingAndStyling">Formatting and Styling</a>, below, for 184 information about to properly style and format your strings. 185 <p>No attributes.</p> 186 </dd> 187 </dl> 188 </dd> <!-- end elements --> 189 190 <dt>example:</dt> 191 <dd>XML file saved at <code>res/values/strings.xml</code>: 192 <pre> 193 <?xml version="1.0" encoding="utf-8"?> 194 <resources> 195 <string-array name="planets_array"> 196 <item>Mercury</item> 197 <item>Venus</item> 198 <item>Earth</item> 199 <item>Mars</item> 200 </string-array> 201 </resources> 202 </pre> 203 204 <p>This application code retrieves a string array:</p> 205 <pre> 206 Resources res = {@link android.content.Context#getResources()}; 207 String[] planets = res.{@link android.content.res.Resources#getStringArray(int) 208 getStringArray}(R.array.planets_array); 209 </pre> 210 </dd> <!-- end example --> 211 212 </dl> 213 214 215 216 217 218 219 220 <h2 id="Plurals">Quantity Strings (Plurals)</h2> 221 222 <p>Different languages have different rules for grammatical agreement with quantity. In English, 223 for example, the quantity 1 is a special case. We write "1 book", but for any other quantity we'd 224 write "<i>n</i> books". This distinction between singular and plural is very common, but other 225 languages make finer distinctions. The full set supported by Android is <code>zero</code>, 226 <code>one</code>, <code>two</code>, <code>few</code>, <code>many</code>, and <code>other</code>. 227 228 <p>The rules for deciding which case to use for a given language and quantity can be very complex, 229 so Android provides you with methods such as 230 {@link android.content.res.Resources#getQuantityString(int,int) getQuantityString()} to select 231 the appropriate resource for you. 232 233 <p>Although historically called "quantity strings" (and still called that in API), quantity 234 strings should <i>only</i> be used for plurals. It would be a mistake to use quantity strings to 235 implement something like Gmail's "Inbox" versus "Inbox (12)" when there are unread messages, for 236 example. It might seem convenient to use quantity strings instead of an {@code if} statement, 237 but it's important to note that some languages (such as Chinese) don't make these grammatical 238 distinctions at all, so you'll always get the <code>other</code> string. 239 240 <p>The selection of which string to use is made solely based on grammatical <i>necessity</i>. 241 In English, a string for <code>zero</code> will be ignored even if the quantity is 0, because 0 242 isn't grammatically different from 2, or any other number except 1 ("zero books", "one book", 243 "two books", and so on). 244 245 <p>Don't be misled either by the fact that, say, <code>two</code> sounds like it could only apply to 246 the quantity 2: a language may require that 2, 12, 102 (and so on) are all treated like one 247 another but differently to other quantities. Rely on your translator to know what distinctions 248 their language actually insists upon. 249 250 <p>It's often possible to avoid quantity strings by using quantity-neutral formulations such as 251 "Books: 1". This will make your life and your translators' lives easier, if it's a style that's 252 in keeping with your application. 253 254 <p class="note"><strong>Note:</strong> A plurals collection is a simple resource that is 255 referenced using the value provided in the {@code name} attribute (not the name of the XML 256 file). As such, you can combine plurals resources with other simple resources in the one 257 XML file, under one {@code <resources>} element.</p> 258 259 <dl class="xml"> 260 261 <dt>file location:</dt> 262 <dd><code>res/values/<em>filename</em>.xml</code><br/> 263 The filename is arbitrary. The {@code <plurals>} element's {@code name} will be used as the 264 resource ID.</dd> 265 266 <dt>resource reference:</dt> 267 <dd> 268 In Java: <code>R.plurals.<em>plural_name</em></code> 269 </dd> 270 271 <dt>syntax:</dt> 272 <dd> 273 <pre class="stx"> 274 <?xml version="1.0" encoding="utf-8"?> 275 <<a href="#plurals-resources-element">resources</a>> 276 <<a href="#plurals-element">plurals</a> 277 name="<em>plural_name</em>"> 278 <<a href="#plurals-item-element">item</a> 279 quantity=["zero" | "one" | "two" | "few" | "many" | "other"] 280 ><em>text_string</em></item> 281 </plurals> 282 </resources> 283 </pre> 284 </dd> 285 286 <dt>elements:</dt> 287 <dd> 288 <dl class="tag-list"> 289 290 <dt id="plurals-resources-element"><code><resources></code></dt> 291 <dd><strong>Required.</strong> This must be the root node. 292 <p>No attributes.</p> 293 </dd> 294 <dt id="plurals-element"><code><plurals></code></dt> 295 <dd>A collection of strings, of which, one string is provided depending on the amount of 296 something. Contains one or more {@code <item>} elements. 297 <p class="caps">attributes:</p> 298 <dl class="atn-list"> 299 <dt><code>name</code></dt> 300 <dd><em>String</em>. A name for the pair of strings. This name will be used as the 301 resource ID.</dd> 302 </dl> 303 304 </dd> 305 <dt id="plurals-item-element"><code><item></code></dt> 306 <dd>A plural or singular string. The value can be a reference to another 307 string resource. Must be a child of a {@code <plurals>} element. Beware that you must 308 escape apostrophes and quotation marks. See <a href="#FormattingAndStyling">Formatting and 309 Styling</a>, below, for information about to properly style and format your strings. 310 <p class="caps">attributes:</p> 311 <dl class="atn-list"> 312 <dt><code>quantity</code></dt> 313 <dd><em>Keyword</em>. A value indicating when this string should be used. Valid 314 values, with non-exhaustive examples in parentheses: 315 <table> 316 <tr><th>Value</th><th>Description</th></tr> 317 <tr> 318 <td>{@code zero}</td><td>When the language requires special treatment of the number 0 (as in Arabic).</td> 319 </tr> 320 <tr> 321 <td>{@code one}</td><td>When the language requires special treatment of numbers like one (as with the number 1 in English and most other languages; in Russian, any number ending in 1 but not ending in 11 is in this class).</td> 322 </tr> 323 <tr> 324 <td>{@code two}</td><td>When the language requires special treatment of numbers like two (as with 2 in Welsh, or 102 in Slovenian).</td> 325 </tr> 326 <tr> 327 <td>{@code few}</td><td>When the language requires special treatment of "small" numbers (as with 2, 3, and 4 in Czech; or numbers ending 2, 3, or 4 but not 12, 13, or 14 in Polish).</td> 328 </tr> 329 <tr> 330 <td>{@code many}</td><td>When the language requires special treatment of "large" numbers (as with numbers ending 11-99 in Maltese).</td> 331 </tr> 332 <tr> 333 <td>{@code other}</td><td>When the language does not require special treatment of the given quantity (as with all numbers in Chinese, or 42 in English).</td> 334 </tr> 335 </table> 336 </dd> 337 </dl> 338 </dd> 339 340 </dl> 341 </dd> <!-- end elements --> 342 343 <dt>example:</dt> 344 <dd>XML file saved at {@code res/values/strings.xml}:</p> 345 <pre> 346 <?xml version="1.0" encoding="utf-8"?> 347 <resources> 348 <plurals name="numberOfSongsAvailable"> 349 <item quantity="one">One song found.</item> 350 <item quantity="other">%d songs found.</item> 351 </plurals> 352 </resources> 353 </pre> 354 <p>XML file saved at {@code res/values-pl/strings.xml}:</p> 355 <pre> 356 <?xml version="1.0" encoding="utf-8"?> 357 <resources> 358 <plurals name="numberOfSongsAvailable"> 359 <item quantity="one">Znaleziono jedną piosenkę.</item> 360 <item quantity="few">Znaleziono %d piosenki.</item> 361 <item quantity="other">Znaleziono %d piosenek.</item> 362 </plurals> 363 </resources> 364 </pre> 365 <p>Java code:</p> 366 <pre> 367 int count = getNumberOfsongsAvailable(); 368 Resources res = {@link android.content.Context#getResources()}; 369 String songsFound = res.<a 370 href="{@docRoot}reference/android/content/res/Resources.html#getQuantityString(int, int, java.lang.Object...)" 371 >getQuantityString</a>(R.plurals.numberOfSongsAvailable, count, count); 372 </pre> 373 374 <p>When using the <a 375 href="{@docRoot}reference/android/content/res/Resources.html#getQuantityString(int, int, java.lang.Object...)">{@code 376 getQuantityString()}</a> method, you need to pass the {@code count} twice if your string includes 377 <a href="#FormattingAndStyling">string formatting</a> with a number. For example, for the string 378 {@code %d songs found}, the first {@code count} parameter selects the appropriate plural string and 379 the second {@code count} parameter is inserted into the {@code %d} placeholder. If your plural 380 strings do not include string formatting, you don't need to pass the third parameter to {@link 381 android.content.res.Resources#getQuantityString(int,int) getQuantityString}.</p> 382 </dd> <!-- end example --> 383 384 </dl> 385 386 387 388 389 390 391 392 393 <h2 id="FormattingAndStyling">Formatting and Styling</h2> 394 395 <p>Here are a few important things you should know about how to properly 396 format and style your string resources.</p> 397 398 399 <h3>Escaping apostrophes and quotes</h3> 400 401 <p>If you have an apostrophe or a quote in your string, you must either escape it or enclose the 402 whole string in the other type of enclosing quotes. For example, here are some stings that 403 do and don't work:</p> 404 405 <pre> 406 <string name="good_example">"This'll work"</string> 407 <string name="good_example_2">This\'ll also work</string> 408 <string name="bad_example">This doesn't work</string> 409 <string name="bad_example_2">XML encodings don&apos;t work</string> 410 </pre> 411 412 413 <h3>Formatting strings</h3> 414 415 <p>If you need to format your strings using <a 416 href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 417 java.lang.Object...)">{@code String.format(String, Object...)}</a>, 418 then you can do so by putting 419 your format arguments in the string resource. For example, with the following resource:</p> 420 421 <pre> 422 <string name="welcome_messages">Hello, %1$s! You have %2$d new messages.</string> 423 </pre> 424 425 <p>In this example, the format string has two arguments: {@code %1$s} is a string and {@code %2$d} 426 is a decimal number. You can format the string with arguments from your application like this:</p> 427 428 <pre> 429 Resources res = {@link android.content.Context#getResources()}; 430 String text = String.<a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 431 java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), username, mailCount); 432 </pre> 433 434 435 436 <h3>Styling with HTML markup</h3> 437 438 <p>You can add styling to your strings with HTML markup. For example:</p> 439 <pre> 440 <?xml version="1.0" encoding="utf-8"?> 441 <resources> 442 <string name="welcome">Welcome to <b>Android</b>!</string> 443 </resources> 444 </pre> 445 <p>Supported HTML elements include:</p> 446 <ul> 447 <li>{@code <b>} for <b>bold</b> text.</li> 448 <li>{@code <i>} for <i>italic</i> text.</li> 449 <li>{@code <u>} for <u>underline</u> text.</li> 450 </ul> 451 452 <p>Sometimes you may want to create a styled text resource that is also used as a format 453 string. Normally, this won't work because the <a 454 href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 455 java.lang.Object...)">{@code String.format(String, Object...)}</a> 456 method will strip all the style 457 information from the string. The work-around to this is to write the HTML tags with escaped 458 entities, which are then recovered with {@link android.text.Html#fromHtml(String)}, 459 after the formatting takes place. For example:</p> 460 461 <ol> 462 <li>Store your styled text resource as an HTML-escaped string: 463 <pre> 464 <resources> 465 <string name="welcome_messages">Hello, %1$s! You have &lt;b>%2$d new messages&lt;/b>.</string> 466 </resources> 467 </pre> 468 <p>In this formatted string, a {@code <b>} element is added. Notice that the opening bracket is 469 HTML-escaped, using the {@code &lt;} notation.</p> 470 </li> 471 <li>Then format the string as usual, but also call {@link android.text.Html#fromHtml} to 472 convert the HTML text into styled text: 473 <pre> 474 Resources res = {@link android.content.Context#getResources()}; 475 String text = String.<a 476 href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 477 java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), username, mailCount); 478 CharSequence styledText = Html.fromHtml(text); 479 </pre> 480 </li> 481 </ol> 482 483 <p>Because the {@link android.text.Html#fromHtml} method will format all HTML entities, be sure to 484 escape any possible HTML characters in the strings you use with the formatted text, using 485 {@link android.text.TextUtils#htmlEncode}. For instance, if you'll be passing a string argument to 486 <a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 487 java.lang.Object...)">{@code String.format()}</a> that may contain characters such as 488 "<" or "&", then they must be escaped before formatting, so that when the formatted string 489 is passed through {@link android.text.Html#fromHtml}, the characters come out the way they were 490 originally written. For example:</p> 491 <pre> 492 String escapedUsername = TextUtil.{@link android.text.TextUtils#htmlEncode htmlEncode}(username); 493 494 Resources res = {@link android.content.Context#getResources()}; 495 String text = String.<a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String, 496 java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), escapedUsername, mailCount); 497 CharSequence styledText = Html.fromHtml(text); 498 </pre> 499 500 501 502
