Plurals

Plurals, also known as quantity strings, are string resources that carry alternate strings for pluralization. Imagine you want to display a text with the number of cakes ordered. The text may be: "2 cakes ordered", or "1 cake ordered". Note that the word "cake" changes depending on the quantity of the cakes. Plurals come in handy in this situation. Using them, you will be able to select the correct form of a string based on a quantity.

In this topic, you will learn how to use plurals in your Android apps to display a grammatically correct string in relation to quantity.

Plural resources

Plurals, being value resources, can be combined with other string resources in the res/values/strings.xml file. You can also create a separate XML file, provided that it is placed in the res/values directory.

To create a plurals resource, you first declare an element with the tag plurals. The element contains a name attribute used to reference the resource. Inside the element there are several child elements with the tag item. Each item element has a quantity attribute that takes in a specific set of keywords used to link it to a quantity class.

Here is an example of the implementation of a plurals resource for our earlier example with cakes:

<resources>
    <plurals name="numberOfCakesOrdered">
        <item quantity="one">%d cake ordered</item>
        <item quantity="other">%d cakes ordered</item>
    </plurals>
</resources>

Note that, as with other resources, plurals should also be enclosed with the root element <resources>.

The quantity attribute

The example above is a simple singular and plural case in English. The quantity one represents a singular case where the quantity is of the value 1. other represents the plural case where the quantity is any other value (including 0) except 1.

The case above only applies to English and some other languages with the same grammatical rules of pluralization. Other languages play by different rules; that's why Android supports more class quantities. The complete list supported by Android is zero, one, two, few, many, and other.

The selection of the appropriate string is completely based on the grammatical rules of the associated language. For instance, in English, Spanish, and other languages that have similar grammatical rules, zero is ignored. That is because, grammatically, the quantity of 0 is treated the same way as other quantities except 1. For example: "0 contacts found", "1 contact found", and "2 contacts found".

Other languages have different rules:

• In Chinese and Korean, only other is used since the grammar of sentences is not affected by the quantity.
• In Russian, one represents not only the quantity of 1 but also 21, 31, 41, 51, 61, and so on. Basically, any number ending with 1 with the exception of those ending with 11. For example: "1 контакт", "21 контакт". few, many, and other are also used in Russian.
• In Irish, all class quantities are used except for zero. one is used for the quantity of 1, two used for the quantity of 2, which in Irish is given special treatment, few is used for a range of quantities (3~6), many (7~10), and other for the remaining quantities including 0.
• Other languages such as Arabic treat the quantity of 0 differently from other quantities, so zero is used in their cases.

Since we cannot exhaustively list every language and its grammatical rules, the rules Android mainly uses can be found here: Language Plural Rules.

Usage in code

Assume you have a plural resource in the res/values/strings.xml file:

<plurals name="notification">
    <item quantity="one">You have %d notification</item>
    <item quantity="other">You have %d notifications</item>
</plurals>

You can access it by using the getQuantityString() method from the Resources class:

val newMessages = 5
val notification = resources.getQuantityString(R.plurals.notification, newMessages, newMessages)

Plurals are referenced by the name provided in the name attribute of the plurals element. In the example above, to the variable notification, the string "You have 5 notifications" is assigned.

Note that the variable newMessages is passed twice as the second and third arguments. The second argument is used to pick the correct plural string based on the value it holds (so it's required for the function to work), whereas the rest of the arguments are used for formatting (only in cases where string formatting is used as in our example above).

Conclusion

Here is a brief summary of what you've learned in this topic:

• Plurals carry different strings for pluralization.
• They are simply value resources and can be mixed with other string resources or placed in their own XML file in the res/values directory.
• The correct plural string selection depends on the language in use since different languages have different grammar rules.
• Plurals can be accessed from code by using the getQuantityString() method, where the first argument is the plural resource ID, the second is used to select the correct plural string, and the following arguments are used for string formatting (if included).