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
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
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
- file location:
The filename is arbitrary. The
namewill be used as the resource ID.
- resource reference:
- In Java:
- Required. This must be the root node.No attributes.
- A collection of strings, of which, one string is provided depending on the amount of something. Contains one or more
- String. A name for the pair of strings. This name will be used as the resource ID.
- 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.
- Keyword. A value indicating when this string should be used. Valid values, with non-exhaustive examples in parentheses:
When the language requires special treatment of the number 0 (as in Arabic).
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).
When the language requires special treatment of numbers like two (as with 2 in Welsh, or 102 in Slovenian).
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).
When the language requires special treatment of “large” numbers (as with numbers ending 11-99 in Maltese).
When the language does not require special treatment of the given quantity (as with all numbers in Chinese, or 42 in English).
- XML file saved at
<?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>
XML file saved at
<?xml version="1.0" encoding="utf-8"?> <resources> <plurals name="numberOfSongsAvailable"> <item quantity="one">Znaleziono %d piosenkę.</item> <item quantity="few">Znaleziono %d piosenki.</item> <item quantity="other">Znaleziono %d piosenek.</item> </plurals> </resources>
int count = getNumberOfsongsAvailable(); Resources res =
getResources(); String songsFound = res.getQuantityString(R.plurals.numberOfSongsAvailable, count, count);
When using the
getQuantityString()method, you need to pass the
counttwice if your string includes string formatting with a number. For example, for the string
%d songs found, the first
countparameter selects the appropriate plural string and the second
countparameter is inserted into the
%dplaceholder. If your plural strings do not include string formatting, you don’t need to pass the third parameter to
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:
<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't work</string>
If you need to format your strings using
String.format(String, Object...), then you can do so by putting your format arguments in the string resource. For example, with the following resource:
<string name="welcome_messages">Hello, %1$s! You have %2$d new messages.</string>
In this example, the format string has two arguments:
%1$s is a string and
%2$d is a decimal number. You can format the string with arguments from your application like this:
Resources res =
getResources(); String text = String.format(res.getString(R.string.welcome_messages), username, mailCount);