docs/html/guide/topics/resources/string-resource.jd - platform/frameworks/base - Git at Google

 page.title=String Resources
 parent.title=Resource Types
 parent.link=available-resources.html
 @jd:body

 <p>A string resource provides text strings for your application
 with optional text styling and formatting. There are three types of resources that can provide
 your application with strings:</p>

 <dl>
   <dt><a href="#String">String</a></dt>
     <dd>XML resource that provides a single string.</dd>
   <dt><a href="#StringArray">String Array</a></dt>
     <dd>XML resource that provides an array of strings.</dd>
   <dt><a href="#Plurals">Quantity Strings (Plurals)</a></dt>
     <dd>XML resource that carries different strings for pluralization.</dd>
 </dl>

 <p>All strings are capable of applying some styling markup and formatting arguments. For
 information about styling and formatting strings, see the section about <a
 href="#FormattingAndStyling">Formatting and Styling</a>.</p>


 <h2 id="String">String</h2>

 <p>A single string that can be referenced from the application or from other resource files (such
 as an XML layout).</p>

 <p class="note"><strong>Note:</strong> A string is a simple resource that is referenced
 using the value provided in the {@code name} attribute (not the name of the XML file). So, you can
 combine string resources with other simple resources in the one XML file,
 under one {@code &lt;resources>} element.</p>

 <dl class="xml">

 <dt>file location:</dt>
 <dd><code>res/values/<em>filename</em>.xml</code><br/>
 The filename is arbitrary. The {@code &lt;string>} element's {@code name} will be used as the
 resource ID.</dd>

 <dt>compiled resource datatype:</dt>
 <dd>Resource pointer to a {@link java.lang.String}.</dd>

 <dt>resource reference:</dt>
 <dd>
 In Java: <code>R.string.<em>string_name</em></code><br/>
 In XML:<code>@string/<em>string_name</em></code>
 </dd>

 <dt>syntax:</dt>
 <dd>
 <pre class="stx">
 &lt;?xml version="1.0" encoding="utf-8"?>
 &lt;<a href="#string-resources-element">resources</a>>
     &lt;<a href="#string-element">string</a>
         name="<em>string_name</em>"
         &gt;<em>text_string</em>&lt;/string&gt;
 &lt;/resources>
 </pre>
 </dd>

 <dt>elements:</dt>
 <dd>
 <dl class="tag-list">

   <dt id="string-resources-element"><code>&lt;resources&gt;</code></dt>
     <dd><strong>Required.</strong> This must be the root node.
       <p>No attributes.</p>
     </dd>
   <dt id="string-element"><code>&lt;string&gt;</code></dt>
     <dd>A string, which can include styling tags. Beware that you must escape apostrophes and
 quotation marks. For more information about how to properly style and format your strings see <a
 href="#FormattingAndStyling">Formatting and Styling</a>, below.
       <p class="caps">attributes:</p>
       <dl class="atn-list">
         <dt><code>name</code></dt>
         <dd><em>String</em>. A name for the string. This name will be used as the resource
 ID.</dd>
       </dl>
     </dd>

 </dl>
 </dd> <!-- end  elements and attributes -->

 <dt>example:</dt>
 <dd>XML file saved at <code>res/values/strings.xml</code>:
 <pre>
 &lt;?xml version="1.0" encoding="utf-8"?>
 &lt;resources>
     &lt;string name="hello">Hello!&lt;/string>
 &lt;/resources>
 </pre>

   <p>This layout XML applies a string to a View:</p>
 <pre>
 &lt;TextView
     android:layout_width="fill_parent"
     android:layout_height="wrap_content"
     <strong>android:text="@string/hello"</strong> />
 </pre>

   <p>This application code retrieves a string:</p>
 <pre>
 String string = {@link android.content.Context#getString(int) getString}(R.string.hello);
 </pre>
 <p>You can use either {@link android.content.Context#getString(int)} or
 {@link android.content.Context#getText(int)} to retrieve a string. {@link
 android.content.Context#getText(int)} will retain any rich text styling applied to the string.</p>

 </dd> <!-- end example -->

 </dl>


 <h2 id="StringArray">String Array</h2>

 <p>An array of strings that can be referenced from the application.</p>

 <p class="note"><strong>Note:</strong> A string array is a simple resource that is referenced
 using the value provided in the {@code name} attribute (not the name of the XML file). As
 such, you can combine string array resources with other simple resources in the one XML file,
 under one {@code &lt;resources>} element.</p>

 <dl class="xml">

 <dt>file location:</dt>
 <dd><code>res/values/<em>filename</em>.xml</code><br/>
 The filename is arbitrary. The {@code &lt;string-array>} element's {@code name} will be used as the
 resource ID.</dd>

 <dt>compiled resource datatype:</dt>
 <dd>Resource pointer to an array of {@link java.lang.String}s.</dd>

 <dt>resource reference:</dt>
 <dd>
 In Java: <code>R.array.<em>string_array_name</em></code>
 </dd>

 <dt>syntax:</dt>
 <dd>
 <pre class="stx">
 &lt;?xml version="1.0" encoding="utf-8"?>
 &lt;<a href="#string-array-resources-element">resources</a>>
     &lt;<a href="#string-array-element">string-array</a>
         name="<em>string_array_name</em>">
         &lt;<a href="#string-array-item-element">item</a>
             &gt;<em>text_string</em>&lt;/item&gt;
     &lt;/string-array>
 &lt;/resources>
 </pre>
 </dd>

 <dt>elements:</dt>
 <dd>
 <dl class="tag-list">
   <dt id="string-array-resources-element"><code>&lt;resources&gt;</code></dt>
     <dd><strong>Required.</strong> This must be the root node.
       <p>No attributes.</p>
     </dd>
   <dt id="string-array-element"><code>&lt;string-array&gt;</code></dt>
     <dd>Defines an array of strings. Contains one or more {@code &lt;item>} elements.
       <p class="caps">attributes:</p>
       <dl class="atn-list">
         <dt><code>name</code></dt>
         <dd><em>String</em>. A name for the array. This name will be used as the resource
 ID to reference the array.</dd>
       </dl>

     </dd>
   <dt id="string-array-item-element"><code>&lt;item&gt;</code></dt>
     <dd>A string, which can include styling tags. The value can be a referenced to another
 string resource. Must be a child of a {@code &lt;string-array&gt;} element. Beware that you
 must escape apostrophes and
 quotation marks. See <a href="#FormattingAndStyling">Formatting and Styling</a>, below, for
 information about to properly style and format your strings.
       <p>No attributes.</p>
     </dd>
 </dl>
 </dd> <!-- end  elements -->

 <dt>example:</dt>
 <dd>XML file saved at <code>res/values/strings.xml</code>:
 <pre>
 &lt;?xml version="1.0" encoding="utf-8"?>
 &lt;resources>
     &lt;string-array name="planets_array">
         &lt;item>Mercury&lt;/item>
         &lt;item>Venus&lt;/item>
         &lt;item>Earth&lt;/item>
         &lt;item>Mars&lt;/item>
     &lt;/string-array>
 &lt;/resources>
 </pre>

   <p>This application code retrieves a string array:</p>
 <pre>
 Resources res = {@link android.content.Context#getResources()};
 String[] planets = res.{@link android.content.res.Resources#getStringArray(int)
 getStringArray}(R.array.planets_array);
 </pre>
 </dd> <!-- end example -->

 </dl>


 <h2 id="Plurals">Quantity Strings (Plurals)</h2>

 <p>Different languages have different rules for grammatical agreement with quantity. In English,
 for example, the quantity 1 is a special case. We write "1 book", but for any other quantity we'd
 write "<i>n</i> books". This distinction between singular and plural is very common, but other
 languages make finer distinctions. The full set supported by Android is <code>zero</code>,
 <code>one</code>, <code>two</code>, <code>few</code>, <code>many</code>, and <code>other</code>.

 <p>The rules for deciding which case to use for a given language and quantity can be very complex,
 so Android provides you with methods such as
 {@link android.content.res.Resources#getQuantityString(int,int) getQuantityString()} to select
 the appropriate resource for you.

 <p>Although historically called "quantity strings" (and still called that in API), quantity
 strings should <i>only</i> be used for plurals. It would be a mistake to use quantity strings to
 implement something like Gmail's "Inbox" versus "Inbox (12)" when there are unread messages, for
 example. It might seem convenient to use quantity strings instead of an {@code if} statement,
 but it's important to note that some languages (such as Chinese) don't make these grammatical
 distinctions at all, so you'll always get the <code>other</code> string.

 <p>The selection of which string to use is made solely based on grammatical <i>necessity</i>.
 In English, a string for <code>zero</code> will be ignored even if the quantity is 0, because 0
 isn't grammatically different from 2, or any other number except 1 ("zero books", "one book",
 "two books", and so on).

 <p>Don't be misled either by the fact that, say, <code>two</code> sounds like it could only apply to
 the quantity 2: a language may require that 2, 12, 102 (and so on) are all treated like one
 another but differently to other quantities. Rely on your translator to know what distinctions
 their language actually insists upon.

 <p>It's often possible to avoid quantity strings by using quantity-neutral formulations such as
 "Books: 1". This will make your life and your translators' lives easier, if it's a style that's
 in keeping with your application.

 <p class="note"><strong>Note:</strong> A plurals collection is a simple resource that is
 referenced using the value provided in the {@code name} attribute (not the name of the XML
 file). As such, you can combine plurals resources with other simple resources in the one
 XML file, under one {@code &lt;resources>} element.</p>

 <dl class="xml">

 <dt>file location:</dt>
 <dd><code>res/values/<em>filename</em>.xml</code><br/>
 The filename is arbitrary. The {@code &lt;plurals>} element's {@code name} will be used as the
 resource ID.</dd>

 <dt>resource reference:</dt>
 <dd>
 In Java: <code>R.plurals.<em>plural_name</em></code>
 </dd>

 <dt>syntax:</dt>
 <dd>
 <pre class="stx">
 &lt;?xml version="1.0" encoding="utf-8"?>
 &lt;<a href="#plurals-resources-element">resources</a>>
     &lt;<a href="#plurals-element">plurals</a>
         name="<em>plural_name</em>">
         &lt;<a href="#plurals-item-element">item</a>
             quantity=["zero" | "one" | "two" | "few" | "many" | "other"]
             &gt;<em>text_string</em>&lt;/item>
     &lt;/plurals>
 &lt;/resources>
 </pre>
 </dd>

 <dt>elements:</dt>
 <dd>
 <dl class="tag-list">

   <dt id="plurals-resources-element"><code>&lt;resources&gt;</code></dt>
     <dd><strong>Required.</strong> This must be the root node.
       <p>No attributes.</p>
     </dd>
   <dt id="plurals-element"><code>&lt;plurals&gt;</code></dt>
     <dd>A collection of strings, of which, one string is provided depending on the amount of
 something. Contains one or more {@code &lt;item>} elements.
       <p class="caps">attributes:</p>
       <dl class="atn-list">
         <dt><code>name</code></dt>
         <dd><em>String</em>. A name for the pair of strings. This name will be used as the
 resource ID.</dd>
       </dl>

     </dd>
   <dt id="plurals-item-element"><code>&lt;item&gt;</code></dt>
     <dd>A plural or singular string. The value can be a referenced to another
 string resource. Must be a child of a {@code &lt;plurals&gt;} element. Beware that you must
 escape apostrophes and quotation marks. See <a href="#FormattingAndStyling">Formatting and
 Styling</a>, below, for information about to properly style and format your strings.
       <p class="caps">attributes:</p>
       <dl class="atn-list">
         <dt><code>quantity</code></dt>
         <dd><em>Keyword</em>. A value indicating when this string should be used. Valid
 values, with non-exhaustive examples in parentheses:
           <table>
             <tr><th>Value</th><th>Description</th></tr>
             <tr>
               <td>{@code zero}</td><td>When the language requires special treatment of the number 0 (as in Arabic).</td>
             </tr>
             <tr>
               <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>
             </tr>
             <tr>
               <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>
             </tr>
             <tr>
               <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>
             </tr>
             <tr>
               <td>{@code many}</td><td>When the language requires special treatment of "large" numbers (as with numbers ending 11-99 in Maltese).</td>
             </tr>
             <tr>
               <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>
             </tr>
           </table>
         </dd>
       </dl>
     </dd>

 </dl>
 </dd> <!-- end elements -->

 <dt>example:</dt>
 <dd>XML file saved at {@code res/values/strings.xml}:</p>
 <pre>
 &lt;?xml version="1.0" encoding="utf-8"?>
 &lt;resources>
     &lt;plurals name="numberOfSongsAvailable">
         &lt;item quantity="one">One song found.&lt;/item>
         &lt;item quantity="other">%d songs found.&lt;/item>
     &lt;/plurals>
 &lt;/resources>
 </pre>
     <p>XML file saved at {@code res/values-pl/strings.xml}:</p>
 <pre>
 &lt;?xml version="1.0" encoding="utf-8"?>
 &lt;resources>
     &lt;plurals name="numberOfSongsAvailable">
         &lt;item quantity="one">Znaleziono jedn&#x0105; piosenk&#x0119;.&lt;/item>
         &lt;item quantity="few">Znaleziono %d piosenki.&lt;/item>
         &lt;item quantity="other">Znaleziono %d piosenek.&lt;/item>
     &lt;/plurals>
 &lt;/resources>
 </pre>
     <p>Java code:</p>
 <pre>
 int count = getNumberOfsongsAvailable();
 Resources res = {@link android.content.Context#getResources()};
 String songsFound = res.<a
 href="{@docRoot}reference/android/content/res/Resources.html#getQuantityString(int, int, java.lang.Object...)"
 >getQuantityString</a>(R.plurals.numberOfSongsAvailable, count, count);
 </pre>

 <p>When using the <a
 href="{@docRoot}reference/android/content/res/Resources.html#getQuantityString(int, int, java.lang.Object...)">{@code
 getQuantityString()}</a> method, you need to pass the {@code count} twice if your string includes
 <a href="#FormattingAndStyling">string formatting</a> with a number. For example, for the string
 {@code %d songs found}, the first {@code count} parameter selects the appropriate plural string and
 the second {@code count} parameter is inserted into the {@code %d} placeholder. If your plural
 strings do not include string formatting, you don't need to pass the third parameter to {@link
 android.content.res.Resources#getQuantityString(int,int) getQuantityString}.</p>
 </dd> <!-- end example -->

 </dl>


 <h2 id="FormattingAndStyling">Formatting and Styling</h2>

 <p>Here are a few important things you should know about how to properly
 format and style your string resources.</p>


 <h3>Escaping apostrophes and quotes</h3>

 <p>If you have an apostrophe or a quote in your string, you must either escape it or enclose the
 whole string in the other type of enclosing quotes. For example, here are some stings that
 do and don't work:</p>

 <pre>
 &lt;string name="good_example">"This'll work"&lt;/string>
 &lt;string name="good_example_2">This\'ll also work&lt;/string>
 &lt;string name="bad_example">This doesn't work&lt;/string>
 &lt;string name="bad_example_2">XML encodings don&amp;apos;t work&lt;/string>
 </pre>


 <h3>Formatting strings</h3>

 <p>If you need to format your strings using <a
 href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
 java.lang.Object...)">{@code String.format(String, Object...)}</a>,
 then you can do so by putting
 your format arguments in the string resource. For example, with the following resource:</p>

 <pre>
 &lt;string name="welcome_messages">Hello, %1$s! You have %2$d new messages.&lt;/string>
 </pre>

 <p>In this example, the format string has two arguments: {@code %1$s} is a string and {@code %2$d}
 is a decimal number. You can format the string with arguments from your application like this:</p>

 <pre>
 Resources res = {@link android.content.Context#getResources()};
 String text = String.<a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
 java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), username, mailCount);
 </pre>


 <h3>Styling with HTML markup</h3>

 <p>You can add styling to your strings with HTML markup. For example:</p>
 <pre>
 &lt;?xml version="1.0" encoding="utf-8"?>
 &lt;resources>
     &lt;string name="welcome">Welcome to &lt;b>Android&lt;/b>!&lt;/string>
 &lt;/resources>
 </pre>
 <p>Supported HTML elements include:</p>
 <ul>
   <li>{@code &lt;b>} for <b>bold</b> text.</li>
   <li>{@code &lt;i>} for <i>italic</i> text.</li>
   <li>{@code &lt;u>} for <u>underline</u> text.</li>
 </ul>

 <p>Sometimes you may want to create a styled text resource that is also used as a format
 string. Normally, this won't work because the <a
 href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
 java.lang.Object...)">{@code String.format(String, Object...)}</a>
 method will strip all the style
 information from the string. The work-around to this is to write the HTML tags with escaped
 entities, which are then recovered with {@link android.text.Html#fromHtml(String)},
 after the formatting takes place. For example:</p>

 <ol>
   <li>Store your styled text resource as an HTML-escaped string:
 <pre>
 &lt;resources&gt;
   &lt;string name="welcome_messages"&gt;Hello, %1$s! You have &amp;lt;b>%2$d new messages&amp;lt;/b>.&lt;/string>
 &lt;/resources&gt;
 </pre>
 <p>In this formatted string, a {@code &lt;b>} element is added. Notice that the opening bracket is
 HTML-escaped, using the {@code &amp;lt;} notation.</p>
   </li>
   <li>Then format the string as usual, but also call {@link android.text.Html#fromHtml} to
 convert the HTML text into styled text:
 <pre>
 Resources res = {@link android.content.Context#getResources()};
 String text = String.<a
 href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
 java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), username, mailCount);
 CharSequence styledText = Html.fromHtml(text);
 </pre>
   </li>
 </ol>

 <p>Because the {@link android.text.Html#fromHtml} method will format all HTML entities, be sure to
 escape any possible HTML characters in the strings you use with the formatted text, using
 {@link android.text.TextUtils#htmlEncode}. For instance, if you'll be passing a string argument to
 <a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
 java.lang.Object...)">{@code String.format()}</a> that may contain characters such as
 "&lt;" or "&amp;", then they must be escaped before formatting, so that when the formatted string
 is passed through {@link android.text.Html#fromHtml}, the characters come out the way they were
 originally written. For example:</p>
 <pre>
 String escapedUsername = TextUtil.{@link android.text.TextUtils#htmlEncode htmlEncode}(username);

 Resources res = {@link android.content.Context#getResources()};
 String text = String.<a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
 java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), escapedUsername, mailCount);
 CharSequence styledText = Html.fromHtml(text);
 </pre>
	page.title=String Resources
	parent.title=Resource Types
	parent.link=available-resources.html
	@jd:body

	<p>A string resource provides text strings for your application
	with optional text styling and formatting. There are three types of resources that can provide
	your application with strings:</p>

	<dl>
	<dt><a href="#String">String</a></dt>
	<dd>XML resource that provides a single string.</dd>
	<dt><a href="#StringArray">String Array</a></dt>
	<dd>XML resource that provides an array of strings.</dd>
	<dt><a href="#Plurals">Quantity Strings (Plurals)</a></dt>
	<dd>XML resource that carries different strings for pluralization.</dd>
	</dl>

	<p>All strings are capable of applying some styling markup and formatting arguments. For
	information about styling and formatting strings, see the section about <a
	href="#FormattingAndStyling">Formatting and Styling</a>.</p>




	<h2 id="String">String</h2>

	<p>A single string that can be referenced from the application or from other resource files (such
	as an XML layout).</p>

	<p class="note"><strong>Note:</strong> A string is a simple resource that is referenced
	using the value provided in the {@code name} attribute (not the name of the XML file). So, you can
	combine string resources with other simple resources in the one XML file,
	under one {@code <resources>} element.</p>

	<dl class="xml">

	<dt>file location:</dt>
	<dd><code>res/values/<em>filename</em>.xml</code><br/>
	The filename is arbitrary. The {@code <string>} element's {@code name} will be used as the
	resource ID.</dd>

	<dt>compiled resource datatype:</dt>
	<dd>Resource pointer to a {@link java.lang.String}.</dd>

	<dt>resource reference:</dt>
	<dd>
	In Java: <code>R.string.<em>string_name</em></code><br/>
	In XML:<code>@string/<em>string_name</em></code>
	</dd>

	<dt>syntax:</dt>
	<dd>
	<pre class="stx">
	<?xml version="1.0" encoding="utf-8"?>
	<<a href="#string-resources-element">resources</a>>
	<<a href="#string-element">string</a>
	name="<em>string_name</em>"
	><em>text_string</em></string>
	</resources>
	</pre>
	</dd>

	<dt>elements:</dt>
	<dd>
	<dl class="tag-list">

	<dt id="string-resources-element"><code><resources></code></dt>
	<dd><strong>Required.</strong> This must be the root node.
	<p>No attributes.</p>
	</dd>
	<dt id="string-element"><code><string></code></dt>
	<dd>A string, which can include styling tags. Beware that you must escape apostrophes and
	quotation marks. For more information about how to properly style and format your strings see <a
	href="#FormattingAndStyling">Formatting and Styling</a>, below.
	<p class="caps">attributes:</p>
	<dl class="atn-list">
	<dt><code>name</code></dt>
	<dd><em>String</em>. A name for the string. This name will be used as the resource
	ID.</dd>
	</dl>
	</dd>

	</dl>
	</dd> <!-- end elements and attributes -->

	<dt>example:</dt>
	<dd>XML file saved at <code>res/values/strings.xml</code>:
	<pre>
	<?xml version="1.0" encoding="utf-8"?>
	<resources>
	<string name="hello">Hello!</string>
	</resources>
	</pre>

	<p>This layout XML applies a string to a View:</p>
	<pre>
	<TextView
	android:layout_width="fill_parent"
	android:layout_height="wrap_content"
	<strong>android:text="@string/hello"</strong> />
	</pre>

	<p>This application code retrieves a string:</p>
	<pre>
	String string = {@link android.content.Context#getString(int) getString}(R.string.hello);
	</pre>
	<p>You can use either {@link android.content.Context#getString(int)} or
	{@link android.content.Context#getText(int)} to retrieve a string. {@link
	android.content.Context#getText(int)} will retain any rich text styling applied to the string.</p>

	</dd> <!-- end example -->

	</dl>









	<h2 id="StringArray">String Array</h2>

	<p>An array of strings that can be referenced from the application.</p>

	<p class="note"><strong>Note:</strong> A string array is a simple resource that is referenced
	using the value provided in the {@code name} attribute (not the name of the XML file). As
	such, you can combine string array resources with other simple resources in the one XML file,
	under one {@code <resources>} element.</p>

	<dl class="xml">

	<dt>file location:</dt>
	<dd><code>res/values/<em>filename</em>.xml</code><br/>
	The filename is arbitrary. The {@code <string-array>} element's {@code name} will be used as the
	resource ID.</dd>

	<dt>compiled resource datatype:</dt>
	<dd>Resource pointer to an array of {@link java.lang.String}s.</dd>

	<dt>resource reference:</dt>
	<dd>
	In Java: <code>R.array.<em>string_array_name</em></code>
	</dd>

	<dt>syntax:</dt>
	<dd>
	<pre class="stx">
	<?xml version="1.0" encoding="utf-8"?>
	<<a href="#string-array-resources-element">resources</a>>
	<<a href="#string-array-element">string-array</a>
	name="<em>string_array_name</em>">
	<<a href="#string-array-item-element">item</a>
	><em>text_string</em></item>
	</string-array>
	</resources>
	</pre>
	</dd>

	<dt>elements:</dt>
	<dd>
	<dl class="tag-list">
	<dt id="string-array-resources-element"><code><resources></code></dt>
	<dd><strong>Required.</strong> This must be the root node.
	<p>No attributes.</p>
	</dd>
	<dt id="string-array-element"><code><string-array></code></dt>
	<dd>Defines an array of strings. Contains one or more {@code <item>} elements.
	<p class="caps">attributes:</p>
	<dl class="atn-list">
	<dt><code>name</code></dt>
	<dd><em>String</em>. A name for the array. This name will be used as the resource
	ID to reference the array.</dd>
	</dl>

	</dd>
	<dt id="string-array-item-element"><code><item></code></dt>
	<dd>A string, which can include styling tags. The value can be a referenced to another
	string resource. Must be a child of a {@code <string-array>} element. Beware that you
	must escape apostrophes and
	quotation marks. See <a href="#FormattingAndStyling">Formatting and Styling</a>, below, for
	information about to properly style and format your strings.
	<p>No attributes.</p>
	</dd>
	</dl>
	</dd> <!-- end elements -->

	<dt>example:</dt>
	<dd>XML file saved at <code>res/values/strings.xml</code>:
	<pre>
	<?xml version="1.0" encoding="utf-8"?>
	<resources>
	<string-array name="planets_array">
	<item>Mercury</item>
	<item>Venus</item>
	<item>Earth</item>
	<item>Mars</item>
	</string-array>
	</resources>
	</pre>

	<p>This application code retrieves a string array:</p>
	<pre>
	Resources res = {@link android.content.Context#getResources()};
	String[] planets = res.{@link android.content.res.Resources#getStringArray(int)
	getStringArray}(R.array.planets_array);
	</pre>
	</dd> <!-- end example -->

	</dl>







	<h2 id="Plurals">Quantity Strings (Plurals)</h2>

	<p>Different languages have different rules for grammatical agreement with quantity. In English,
	for example, the quantity 1 is a special case. We write "1 book", but for any other quantity we'd
	write "<i>n</i> books". This distinction between singular and plural is very common, but other
	languages make finer distinctions. The full set supported by Android is <code>zero</code>,
	<code>one</code>, <code>two</code>, <code>few</code>, <code>many</code>, and <code>other</code>.

	<p>The rules for deciding which case to use for a given language and quantity can be very complex,
	so Android provides you with methods such as
	{@link android.content.res.Resources#getQuantityString(int,int) getQuantityString()} to select
	the appropriate resource for you.

	<p>Although historically called "quantity strings" (and still called that in API), quantity
	strings should <i>only</i> be used for plurals. It would be a mistake to use quantity strings to
	implement something like Gmail's "Inbox" versus "Inbox (12)" when there are unread messages, for
	example. It might seem convenient to use quantity strings instead of an {@code if} statement,
	but it's important to note that some languages (such as Chinese) don't make these grammatical
	distinctions at all, so you'll always get the <code>other</code> string.

	<p>The selection of which string to use is made solely based on grammatical <i>necessity</i>.
	In English, a string for <code>zero</code> will be ignored even if the quantity is 0, because 0
	isn't grammatically different from 2, or any other number except 1 ("zero books", "one book",
	"two books", and so on).

	<p>Don't be misled either by the fact that, say, <code>two</code> sounds like it could only apply to
	the quantity 2: a language may require that 2, 12, 102 (and so on) are all treated like one
	another but differently to other quantities. Rely on your translator to know what distinctions
	their language actually insists upon.

	<p>It's often possible to avoid quantity strings by using quantity-neutral formulations such as
	"Books: 1". This will make your life and your translators' lives easier, if it's a style that's
	in keeping with your application.

	<p class="note"><strong>Note:</strong> A plurals collection is a simple resource that is
	referenced using the value provided in the {@code name} attribute (not the name of the XML
	file). As such, you can combine plurals resources with other simple resources in the one
	XML file, under one {@code <resources>} element.</p>

	<dl class="xml">

	<dt>file location:</dt>
	<dd><code>res/values/<em>filename</em>.xml</code><br/>
	The filename is arbitrary. The {@code <plurals>} element's {@code name} will be used as the
	resource ID.</dd>

	<dt>resource reference:</dt>
	<dd>
	In Java: <code>R.plurals.<em>plural_name</em></code>
	</dd>

	<dt>syntax:</dt>
	<dd>
	<pre class="stx">
	<?xml version="1.0" encoding="utf-8"?>
	<<a href="#plurals-resources-element">resources</a>>
	<<a href="#plurals-element">plurals</a>
	name="<em>plural_name</em>">
	<<a href="#plurals-item-element">item</a>
	quantity=["zero" \| "one" \| "two" \| "few" \| "many" \| "other"]
	><em>text_string</em></item>
	</plurals>
	</resources>
	</pre>
	</dd>

	<dt>elements:</dt>
	<dd>
	<dl class="tag-list">

	<dt id="plurals-resources-element"><code><resources></code></dt>
	<dd><strong>Required.</strong> This must be the root node.
	<p>No attributes.</p>
	</dd>
	<dt id="plurals-element"><code><plurals></code></dt>
	<dd>A collection of strings, of which, one string is provided depending on the amount of
	something. Contains one or more {@code <item>} elements.
	<p class="caps">attributes:</p>
	<dl class="atn-list">
	<dt><code>name</code></dt>
	<dd><em>String</em>. A name for the pair of strings. This name will be used as the
	resource ID.</dd>
	</dl>

	</dd>
	<dt id="plurals-item-element"><code><item></code></dt>
	<dd>A plural or singular string. The value can be a referenced to another
	string resource. Must be a child of a {@code <plurals>} element. Beware that you must
	escape apostrophes and quotation marks. See <a href="#FormattingAndStyling">Formatting and
	Styling</a>, below, for information about to properly style and format your strings.
	<p class="caps">attributes:</p>
	<dl class="atn-list">
	<dt><code>quantity</code></dt>
	<dd><em>Keyword</em>. A value indicating when this string should be used. Valid
	values, with non-exhaustive examples in parentheses:
	<table>
	<tr><th>Value</th><th>Description</th></tr>
	<tr>
	<td>{@code zero}</td><td>When the language requires special treatment of the number 0 (as in Arabic).</td>
	</tr>
	<tr>
	<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>
	</tr>
	<tr>
	<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>
	</tr>
	<tr>
	<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>
	</tr>
	<tr>
	<td>{@code many}</td><td>When the language requires special treatment of "large" numbers (as with numbers ending 11-99 in Maltese).</td>
	</tr>
	<tr>
	<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>
	</tr>
	</table>
	</dd>
	</dl>
	</dd>

	</dl>
	</dd> <!-- end elements -->

	<dt>example:</dt>
	<dd>XML file saved at {@code res/values/strings.xml}:</p>
	<pre>
	<?xml version="1.0" encoding="utf-8"?>
	<resources>
	<plurals name="numberOfSongsAvailable">
	<item quantity="one">One song found.</item>
	<item quantity="other">%d songs found.</item>
	</plurals>
	</resources>
	</pre>
	<p>XML file saved at {@code res/values-pl/strings.xml}:</p>
	<pre>
	<?xml version="1.0" encoding="utf-8"?>
	<resources>
	<plurals name="numberOfSongsAvailable">
	<item quantity="one">Znaleziono jedną piosenkę.</item>
	<item quantity="few">Znaleziono %d piosenki.</item>
	<item quantity="other">Znaleziono %d piosenek.</item>
	</plurals>
	</resources>
	</pre>
	<p>Java code:</p>
	<pre>
	int count = getNumberOfsongsAvailable();
	Resources res = {@link android.content.Context#getResources()};
	String songsFound = res.<a
	href="{@docRoot}reference/android/content/res/Resources.html#getQuantityString(int, int, java.lang.Object...)"
	>getQuantityString</a>(R.plurals.numberOfSongsAvailable, count, count);
	</pre>

	<p>When using the <a
	href="{@docRoot}reference/android/content/res/Resources.html#getQuantityString(int, int, java.lang.Object...)">{@code
	getQuantityString()}</a> method, you need to pass the {@code count} twice if your string includes
	<a href="#FormattingAndStyling">string formatting</a> with a number. For example, for the string
	{@code %d songs found}, the first {@code count} parameter selects the appropriate plural string and
	the second {@code count} parameter is inserted into the {@code %d} placeholder. If your plural
	strings do not include string formatting, you don't need to pass the third parameter to {@link
	android.content.res.Resources#getQuantityString(int,int) getQuantityString}.</p>
	</dd> <!-- end example -->

	</dl>








	<h2 id="FormattingAndStyling">Formatting and Styling</h2>

	<p>Here are a few important things you should know about how to properly
	format and style your string resources.</p>


	<h3>Escaping apostrophes and quotes</h3>

	<p>If you have an apostrophe or a quote in your string, you must either escape it or enclose the
	whole string in the other type of enclosing quotes. For example, here are some stings that
	do and don't work:</p>

	<pre>
	<string name="good_example">"This'll work"</string>
	<string name="good_example_2">This\'ll also work</string>
	<string name="bad_example">This doesn't work</string>
	<string name="bad_example_2">XML encodings don&apos;t work</string>
	</pre>


	<h3>Formatting strings</h3>

	<p>If you need to format your strings using <a
	href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
	java.lang.Object...)">{@code String.format(String, Object...)}</a>,
	then you can do so by putting
	your format arguments in the string resource. For example, with the following resource:</p>

	<pre>
	<string name="welcome_messages">Hello, %1$s! You have %2$d new messages.</string>
	</pre>

	<p>In this example, the format string has two arguments: {@code %1$s} is a string and {@code %2$d}
	is a decimal number. You can format the string with arguments from your application like this:</p>

	<pre>
	Resources res = {@link android.content.Context#getResources()};
	String text = String.<a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
	java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), username, mailCount);
	</pre>



	<h3>Styling with HTML markup</h3>

	<p>You can add styling to your strings with HTML markup. For example:</p>
	<pre>
	<?xml version="1.0" encoding="utf-8"?>
	<resources>
	<string name="welcome">Welcome to <b>Android</b>!</string>
	</resources>
	</pre>
	<p>Supported HTML elements include:</p>
	<ul>
	<li>{@code <b>} for <b>bold</b> text.</li>
	<li>{@code <i>} for <i>italic</i> text.</li>
	<li>{@code <u>} for <u>underline</u> text.</li>
	</ul>

	<p>Sometimes you may want to create a styled text resource that is also used as a format
	string. Normally, this won't work because the <a
	href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
	java.lang.Object...)">{@code String.format(String, Object...)}</a>
	method will strip all the style
	information from the string. The work-around to this is to write the HTML tags with escaped
	entities, which are then recovered with {@link android.text.Html#fromHtml(String)},
	after the formatting takes place. For example:</p>

	<ol>
	<li>Store your styled text resource as an HTML-escaped string:
	<pre>
	<resources>
	<string name="welcome_messages">Hello, %1$s! You have &lt;b>%2$d new messages&lt;/b>.</string>
	</resources>
	</pre>
	<p>In this formatted string, a {@code <b>} element is added. Notice that the opening bracket is
	HTML-escaped, using the {@code &lt;} notation.</p>
	</li>
	<li>Then format the string as usual, but also call {@link android.text.Html#fromHtml} to
	convert the HTML text into styled text:
	<pre>
	Resources res = {@link android.content.Context#getResources()};
	String text = String.<a
	href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
	java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), username, mailCount);
	CharSequence styledText = Html.fromHtml(text);
	</pre>
	</li>
	</ol>

	<p>Because the {@link android.text.Html#fromHtml} method will format all HTML entities, be sure to
	escape any possible HTML characters in the strings you use with the formatted text, using
	{@link android.text.TextUtils#htmlEncode}. For instance, if you'll be passing a string argument to
	<a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
	java.lang.Object...)">{@code String.format()}</a> that may contain characters such as
	"<" or "&", then they must be escaped before formatting, so that when the formatted string
	is passed through {@link android.text.Html#fromHtml}, the characters come out the way they were
	originally written. For example:</p>
	<pre>
	String escapedUsername = TextUtil.{@link android.text.TextUtils#htmlEncode htmlEncode}(username);

	Resources res = {@link android.content.Context#getResources()};
	String text = String.<a href="{@docRoot}reference/java/lang/String.html#format(java.lang.String,
	java.lang.Object...)">format</a>(res.getString(R.string.welcome_messages), escapedUsername, mailCount);
	CharSequence styledText = Html.fromHtml(text);
	</pre>