How to use Android quantity strings (plurals)

Question

You don't need to set the "formatted" attribute for any of those items. When using quantity strings, there are only three possibilities:

1. the resource string is plain text and does not contain any parameters
2. the resource string contains only one parameter (most likely the quantity); use %d or whatever format you need
3. the resource string contains multiple parameters; all parameters have to be explicitly accessed by their position, for example %1$d

As for the getQuantityString method, there are two overloads: one with only the resource id and the quantity, and one with an additional Object... formatArgs parameter.

For case 1., you can use the getQuantityString(@PluralsRes int id, int quantity) method.

For all other cases, i. e. if you have any parameters, you need the getQuantityString(@PluralsRes int id, int quantity, Object... formatArgs) overload. Note: all parameters have to be present in the parameter array. That means, if the resource string displays the quantity, the quantity variable will be passed twice to the function.

That is because the quantity parameter of the method itself is not considered when resolving the positional parameters of your resource string.

So if these are your resources,

<resources>
    <plurals name="test0">
        <item quantity="one">Test ok</item>
        <item quantity="other">Tests ok</item>
    </plurals>
    <plurals name="test1">
        <item quantity="one">%d test ok</item>
        <item quantity="other">%d tests ok</item>
    </plurals>
    <plurals name="test2">
        <item quantity="one">%2$s: %1$d test ok</item>
        <item quantity="other">%2$s: %1$d tests ok</item>
    </plurals>
    <plurals name="test3">
        <item quantity="one">%3$s: %1$d test out of %2$d ok</item>
        <item quantity="other">%3$s: %1$d tests out of %2$d ok</item>
    </plurals>
</resources>

then the appropriate calls to getQuantityString are:

int success = 1;
int total = 10;
String group = "Group name";

getResources().getQuantityString(R.plurals.test0, success)
// Test ok
getResources().getQuantityString(R.plurals.test1, success, success)
// 1 test ok
getResources().getQuantityString(R.plurals.test2, success, success, group)
// Group name: 1 test ok
getResources().getQuantityString(R.plurals.test3, success, success, total, group)
// Group name: 1 test out of 10 ok

success = 5;
getResources().getQuantityString(R.plurals.test0, success)
// Tests ok
getResources().getQuantityString(R.plurals.test1, success, success)
// 5 tests ok
getResources().getQuantityString(R.plurals.test2, success, success, group)
// Group name: 5 tests ok
getResources().getQuantityString(R.plurals.test3, success, success, total, group)
// Group name: 5 tests out of 10 ok

---

Quantity classes: understanding the quantity parameter

As stated above, the key is to understand that the quantity parameter of getQuantityString is not used to replace the placeholders like %d or %1$d. Instead, it is used to determine the appropriate item from the plurals itself, in combination with the locale of the resource file.

Beware however that this is a less direct mapping than the attribute's name and its possible values (zero, one, two, few, many, other) might suggest. For example, providing an additional <item quantity="zero"> will not work (at least not in English), even if the value of the quantity parameter is 0.

The reason is that the way plurals work in Android is by the concept of quantity classes. A quantity class is a set of quantity values that have the same grammatical rules in a given language. This crucially means that

• which quantity classes are used, and
• which numeric values are mapped to them

is dependent on the locale the respective resource file is for.

It is important to understand that both questions are decided only by grammatical necessity. Here are some examples:

• In Chinese or Korean, only other is used, because in these languages sentences don't grammatically differ based on the given quantity.
• In English, there's two classes: one for the literal value 1, and other for all other values including 0.
• In Irish, 1 is mapped to one, 2 is mapped to two, 3-6 is few, 7-10 is many, 0 and 11+ is other.
• In Slovenian, the value 1 and all values ending in 01 are mapped to one (1, 101, 3001, ...). 2 and values ending in 02 are mapped to two (2, 302, 1002, ...). 3, 4 and values ending in 03 or 04 are mapped to few (3, 4, 6004, ...). Anything else is other (0, 11, 48, 312, ...).
• In Polish, 5-19 and values ending in 05-19 are mapped to many (5, 12, 216, 4711, ...). Values ending in 2, 3 or 4 including 2-4 themselves are mapped to few (3, 42, 103, 12035374, ...). This respects however that 12, 13 and 14 are exceptions from this rule because they are mapped to many. (Side note: yes, grammatically speaking, 5 is many while 12035374 is few.)
• Armenian is like English, with the exception that the value 0 is also mapped to one, because that's how their grammar works. You can see from this example that the quantity class one doesn't even necessarily represent just one-ish numbers.

As you can see, it can get fairly complicated to determine the correct quantity class. That's why getQuantityString already does that for you, based on the quantity parameter and the resource file's locale. The rules Android (mostly) plays by are defined in the Language Plural Rules of the Unicode Common Locale Data Repository. That is also where the names of the quantity classes come from.

All that means that the set of quantity classes needed to translate any quantity string can differ from language to language (Chinese just needs other, English needs one and other, Irish needs all but zero, etc.). Within one language however, all plurals should each have the same number of items covering all quantity classes necessary for that particular language.

Conclusion

A call to getQuantityString can be understood like this:

int success = 5;
int total = 10;
String group = "Group name";

getResources().getQuantityString(R.plurals.test3, success, success, total, group)
//                               \_____________/  \_____/  \___________________/
//                                      |            |               |
//         id: used to get the plurals resource      |               |
//   quantity: used to determine the appropriate quantity class      |
// formatArgs: used to positionally replace the placeholders %1, %2 and %3

The quantity parameter's value of "5" will mean the used item will be the one with the quantity class other from Chinese, Korean, English, Slovenian and Armenian resource files, few for Irish, and many for Polish.

---

There are two special cases I'd also briefly mention:

Non-integer quantities

Basically, the chosen class depends on language-specific rules again. It is neither universal how a class is chosen, nor guaranteed that any class required to cover all rules for integers is also used for any non-integers. Here are a few examples:

• For English, any value with decimals will always map to other.
• For Slovenian, any value with decimals will always map to few.
• For Irish, the choice depends on the integer part.
• For Polish, in contrast to the complex rules for integers, non-integers are always mapped to other like in English.

Note: This is how it should be according to the Language Plural Rules. Alas, Android has no readily available method for float or double at the moment.

Multiple quantities in one string

If your display text has multiple quantities, e. g. %d match(es) found in %d file(s)., split it into three separate resources:

1. %d match(es) (plurals item)
2. %d file(s) (plurals item)
3. %1$s found in %2$s. (ordinary parameterized strings item)

You can then make the appropriate calls to getQuantityString for 1 and 2, and then another one to getString for the third, with the first two readily localized strings as formatArgs.

The reason is to allow translators to switch the parameter order in the third resource, should the language require it. E.g., if the only valid syntax in a hypothetical language was In %d file(s) it found %d match(es)., the translator could translate the plurals as usual, and then translate the third resource as In %2$s it found %1$s. to account for the swapped order.