All strings are capable of applying some styling markup and formatting arguments. For
information about styling and formatting strings, see the section about Formatting and Styling.

String

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

Note: A string is a simple resource that is referenced
using the value provided in the 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 <resources> element.

file location:

res/values/filename.xml
The filename is arbitrary. The <string> element's name will be used as the
resource ID.

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 Formatting and Styling, below.

attributes:

name

String. A name for the string. This name will be used as the resource
ID.

String Array

An array of strings that can be referenced from the application.

Note: A string array is a simple resource that is referenced
using the value provided in the 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 <resources> element.

file location:

res/values/filename.xml
The filename is arbitrary. The <string-array> element's name will be used as the
resource ID.

String. A name for the array. This name will be used as the resource
ID to reference the array.

<item>

A string, which can include styling tags. The value can be a reference to another
string resource. Must be a child of a <string-array> element. Beware that you
must escape apostrophes and
quotation marks. See Formatting and Styling, below, for
information about to properly style and format your strings.

Quantity Strings (Plurals)

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 "n books". This distinction between singular and plural is very common, but other
languages make finer distinctions. The full set supported by Android is zero,
one, two, few, many, and other.

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
getQuantityString() to select
the appropriate resource for you.

Although historically called "quantity strings" (and still called that in API), quantity
strings should only 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 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 other string.

The selection of which string to use is made solely based on grammatical necessity.
In English, a string for zero 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). Conversely, in Korean only the other string will
ever be used.

Don't be misled either by the fact that, say, two 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.

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.

Note: A plurals collection is a simple resource that is
referenced using the value provided in the 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 <resources> element.

file location:

res/values/filename.xml
The filename is arbitrary. The <plurals> element's name will be used as the
resource ID.

A collection of strings, of which, one string is provided depending on the amount of
something. Contains one or more <item> elements.

attributes:

name

String. A name for the pair of strings. This name will be used as the
resource ID.

<item>

A plural or singular string. The value can be a reference to another
string resource. Must be a child of a <plurals> element. Beware that you must
escape apostrophes and quotation marks. See Formatting and
Styling, below, for information about to properly style and format your strings.

attributes:

quantity

Keyword. A value indicating when this string should be used. Valid
values, with non-exhaustive examples in parentheses:

Value

Description

zero

When the language requires special treatment of the number 0 (as in Arabic).

one

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).

two

When the language requires special treatment of numbers like two (as with 2 in Welsh, or 102 in Slovenian).

few

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).

many

When the language requires special treatment of "large" numbers (as with numbers ending 11-99 in Maltese).

other

When the language does not require special treatment of the given quantity (as with all numbers in Chinese, or 42 in English).

example:

XML file saved at res/values/strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
<plurals name="numberOfSongsAvailable">
<!--
As a developer, you should always supply "one" and "other"
strings. Your translators will know which strings are actually
needed for their language. Always include %d in "one" because
translators will need to use %d for languages where "one"
doesn't mean 1 (as explained above).
-->
<item quantity="one">%d song found.</item>
<item quantity="other">%d songs found.</item>
</plurals>
</resources>

When using the getQuantityString() method, you need to pass the count twice if your string includes
string formatting with a number. For example, for the string
%d songs found, the first count parameter selects the appropriate plural string and
the second count parameter is inserted into the %d placeholder. If your plural
strings do not include string formatting, you don't need to pass the third parameter to getQuantityString.

Formatting and Styling

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

Escaping apostrophes and quotes

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:

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 String.format(String, Object...)
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 fromHtml(String),
after the formatting takes place. For example:

Store your styled text resource as an HTML-escaped string:

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

In this formatted string, a <b> element is added. Notice that the opening bracket is
HTML-escaped, using the &lt; notation.

Then format the string as usual, but also call fromHtml(String) to
convert the HTML text into styled text:

Because the fromHtml(String) method will format all HTML entities, be sure to
escape any possible HTML characters in the strings you use with the formatted text, using
htmlEncode(String). For instance, if you'll be passing a string argument to
String.format() that may contain characters such as
"<" or "&", then they must be escaped before formatting, so that when the formatted string
is passed through fromHtml(String), the characters come out the way they were
originally written. For example:

You can use the following helper methods to set up much of the work
of creating spannable text:

/**
* Returns a CharSequence that concatenates the specified array of CharSequence
* objects and then applies a list of zero or more tags to the entire range.
*
* @param content an array of character sequences to apply a style to
* @param tags the styled span objects to apply to the content
* such as android.text.style.StyleSpan
*
*/
private static CharSequence apply(CharSequence[] content, Object... tags) {
SpannableStringBuilder text = new SpannableStringBuilder();
openTags(text, tags);
for (CharSequence item : content) {
text.append(item);
}
closeTags(text, tags);
return text;
}
/**
* Iterates over an array of tags and applies them to the beginning of the specified
* Spannable object so that future text appended to the text will have the styling
* applied to it. Do not call this method directly.
*/
private static void openTags(Spannable text, Object[] tags) {
for (Object tag : tags) {
text.setSpan(tag, 0, 0, Spannable.SPAN_MARK_MARK);
}
}
/**
* "Closes" the specified tags on a Spannable by updating the spans to be
* endpoint-exclusive so that future text appended to the end will not take
* on the same styling. Do not call this method directly.
*/
private static void closeTags(Spannable text, Object[] tags) {
int len = text.length();
for (Object tag : tags) {
if (len > 0) {
text.setSpan(tag, 0, len, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
} else {
text.removeSpan(tag);
}
}
}

The following bold, italic, and color
methods show you how to call the helper methods to apply
styles defined in the android.text.style package. You
can create similar methods to do other types of text styling.