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