Clarify documentation for format_plural()

http://api.drupal.org/api/function/format_plural/7

see also #425434: format_plural: some languages use singular form for zero, but this is not reflected in Drupal

No. In the signature of format_plural(), $singular and $plural are the *English* forms. You use @count or "1" in the $singular, as you want. It doesn't matter at all for translations.

This is because the plural string "$singular-$plural" is translated into n-plural forms (where n is language dependent), that are no direct translations of either $singular or $plural.

Edit: I was wrong here: you *have to* use "1", not "@count" in the singular form.

This is a real problem, actually.

The way that format_plural() works is that it queries locale_get_plural() to find out whether the number $count is considered to be singular or plural for the language being used, and then it uses either the singular or plural format.

However, this will really not work for all languages. For instance, in Russian, there are different words used for 1, 2-4, and 5 or more of something. See
http://en.wikipedia.org/wiki/Grammatical_number
http://en.wikipedia.org/wiki/Dual_%28grammatical_number%29#The_dual_in_t...

So the whole idea of having singular/plural just doesn't apply to all languages... This is a code/locale issue, not documentation. Although if we stick to the function continuing to behave as it currently does, I agree that the documentation and examples for the singular string should contain @count rather than 1.

Ummmm... Really?

I'm just looking at the function code at http://api.drupal.org/api/function/format_plural/7

If $count is 1, it just does t($singular), which seems to be non-controversial.

Otherwise, it is calling locale_get_plural($count) to get an index. But then it is just calling either t($singular) if the return value is 0, or t($plural) if the return value is 1, or t($plural) with @count replaced with @count[5], e.g., if locale_get_plural() returns the number 5.

I don't see how that is allowing translators to translate "1 new message"/"@count new messages" from English into "0 nouveau message"/"1 nouveau message"/"@count nouveax messages" for French (and pardon me if my French is not quite correct)? Or for Russian into the equivalent of "0 newzeroform messagezeroform"/"1 newoneform messageoneform"/"2-4 newsmallform messaagesmallform"/"5+ newsmallform messagesmallform"?

Please enlighten... and how should we reform the doc anyway?

The confusion comes from the way the plural forms are stored in _locale_import_one_string():

• $singular (aka 1 comment) is the source string of the plural form 0
• $plural (aka @count comments) is the source string of the plural form 1
• preg_replace('/(@count)/', "\\1[$key]", $plural) (aka @count[2] comments, @count[3] comments, @count[4] comments, ...) are the source strings of the plural forms 2, 3, 4, etc.

I agree that in French there should be a separate plural form for the case where $count = 0. The docs specifically state 'Do not use @count in the singular string.', meaning that the singular string should specifically contain the number 1 and is only useful in the case that $count = 1. Related issue: #30876: Bug with plural forms.

Also, we need an easy way to explain to translators what a string like '@count[2] new messages' represents. It's not intuitive to know that it means "'0 new messages', in French".

The French plural formula is nplurals=2; plural=(n>1), which is exactly what it is supposed to be (form 0 is $count = 0 or 1, form 1 is everything else).

In that case, shouldn't the PHPdocs change?

If the singular form is going to be used in more than one case, then the string SHOULD use @count. We can't expect translators to just know that "sometimes, the number '1' in strings should be replaced by '@count'". :S

Also note that translators *never see* the @count[2] new messages. This is only how Drupal internally (and artificially) stores the source strings of plural forms.

Then how are these translations submitted?

The reason for putting 1 in the English singular strings was mentioned way back in #4. The singular and plural forms have to be different in order for them to be translated at all. Usually this isn't a problem because of verb conjugation, but it can play havoc with abbreviations like "1 min" vs. "@count min".

French translators (and other languages that use singular forms for other numbers) just need to know to use @count. If there's a documentation issue, that's where it is, not with format_plural().

Could someone answer the question in #15, I don't understand that either:

Also note that translators *never see* the @count[2] new messages. This is only how Drupal internally (and artificially) stores the source strings of plural forms.

Then how are these translations submitted?