From 0cd016741dd57b10f974756b30c9ba8b5d537d08 Mon Sep 17 00:00:00 2001 From: Elliott Hughes Date: Tue, 25 Sep 2012 16:15:35 -0700 Subject: Attempt to clarify how pluralization actually works. Many languages are very unlike English. Bug: 7229680 Change-Id: I3a2b9d10ee7d92b0a0bc47d81bd372fd8ce6ba19 --- .../html/guide/topics/resources/string-resource.jd | 24 ++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/html/guide/topics/resources/string-resource.jd b/docs/html/guide/topics/resources/string-resource.jd index 5f5484ee42bb..da410a4cecc3 100644 --- a/docs/html/guide/topics/resources/string-resource.jd +++ b/docs/html/guide/topics/resources/string-resource.jd @@ -13,8 +13,7 @@ your application with strings:

String Array
XML resource that provides an array of strings.
Quantity Strings (Plurals)
-
XML resource that carries different strings for different quantities - of the same word or phrase.
+
XML resource that carries different strings for pluralization.

All strings are capable of applying some styling markup and formatting arguments. For @@ -231,10 +230,19 @@ so Android provides you with methods such as {@link android.content.res.Resources#getQuantityString(int,int) getQuantityString()} to select the appropriate resource for you. -

Note that the selection is made based on grammatical necessity. A string for zero -in English 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). -Don't be misled either by the fact that, say, two sounds like it could only apply to +

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 {@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 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). + +

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. @@ -313,7 +321,7 @@ values, with non-exhaustive examples in parentheses: {@code 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). - {@code two}When the language requires special treatment of numbers like two (as in Welsh). + {@code two}When the language requires special treatment of numbers like two (as with 2 in Welsh, or 102 in Slovenian). {@code 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). @@ -322,7 +330,7 @@ values, with non-exhaustive examples in parentheses: {@code many}When the language requires special treatment of "large" numbers (as with numbers ending 11-99 in Maltese). - {@code other}When the language does not require special treatment of the given quantity. + {@code other}When the language does not require special treatment of the given quantity (as with all numbers in Chinese, or 42 in English). -- cgit v1.2.3-59-g8ed1b