From 1ad636c31501b1f407a3bf504d14689c1d5c7f5a Mon Sep 17 00:00:00 2001 From: Elliott Hughes Date: Thu, 1 Jul 2010 16:51:48 -0700 Subject: Defer to ICU's knowledge of language-specific grammatical quantity rules. Also improve the documentation to make it a little less unclear what this is all about. In particular, explain why the original submitter's complaint about "zero" never being used in English, is expected behavior. Bug: 2663392 Change-Id: Iade3b4f5c549ce01a95fd0e7e5c6ea394178eda3 --- .../html/guide/topics/resources/string-resource.jd | 67 +++++++++++++++++----- 1 file changed, 53 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/html/guide/topics/resources/string-resource.jd b/docs/html/guide/topics/resources/string-resource.jd index 81c5d55..2db38f1 100644 --- a/docs/html/guide/topics/resources/string-resource.jd +++ b/docs/html/guide/topics/resources/string-resource.jd @@ -12,8 +12,8 @@ your application with strings:

XML resource that provides a single string.
String Array
XML resource that provides an array of strings.
-
Plurals
-
XML resource that carries different strings for different pluralizations +
Quantity Strings (Plurals)
+
XML resource that carries different strings for different quantities of the same word or phrase.
@@ -218,13 +218,30 @@ getStringArray}(R.array.planets_array); -

Plurals

+

Quantity Strings (Plurals)

-

A pair of strings that each provide a different plural form of the same word or phrase, -which you can collectively reference from the application. When you request the plurals -resource using a method such as {@link android.content.res.Resources#getQuantityString(int,int) -getQuantityString()}, you must pass a "count", which will determine the plural form you -require and return that string to you.

+

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 +{@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", et cetera). +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 (et cetera) 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 {@code name} attribute (not the name of the XML @@ -251,7 +268,7 @@ In Java: R.plurals.plural_name <plurals name="plural_name"> <item - quantity=["one" | "other"] + quantity=["zero" | "one" | "two" | "few" | "many" | "other"] >text_string</item> </plurals> </resources> @@ -285,16 +302,27 @@ Styling, below, for information about to properly style and format your stri

attributes:

quantity
-
Keyword. A value indicating the case in which this string should be used. Valid -values: +
Keyword. A value indicating when this string should be used. Valid +values, with non-exhaustive examples in parentheses: - + + + + + + + + + + - + + + +
ValueDescription
{@code one}When there is one (a singular string).{@code zero}When the language requires special treatment of the number 0 (as in Arabic).
{@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 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).
{@code other}When the quantity is anything other than one (a plural -string, but also used when the count is zero).{@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.
@@ -315,6 +343,17 @@ string, but also used when the count is zero). </plurals> </resources> +

XML file saved at {@code res/values-pl/strings.xml}:

+
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <plurals name="numberOfSongsAvailable">
+        <item quantity="one">Znaleziono jedną piosenkę.</item>
+        <item quantity="few">Znaleziono %d piosenki.</item>
+        <item quantity="other">Znaleziono %d piosenek.</item>
+    </plurals>
+</resources>
+

Java code:

 int count = getNumberOfsongsAvailable();
-- 
cgit v1.1