Opened 3 years ago

Closed 3 years ago

Last modified 3 years ago

#21650 closed Cleanup/optimization (fixed)

Usage example in i18n docs is bad advice for plurals

Reported by: Ned Batchelder Owned by: nobody
Component: Documentation Version: 1.6
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description (last modified by Tim Graham)

This example in the i18n docs:

Lets see a slightly more complex usage example::

    from django.utils.translation import ungettext
    from myapp.models import Report

    count = Report.objects.count()
    if count == 1:
        name = Report._meta.verbose_name
    else:
        name = Report._meta.verbose_name_plural

    text = ungettext(
            'There is %(count)d %(name)s available.',
            'There are %(count)d %(name)s available.',
            count
    ) % {
        'count': count,
        'name': name
    }

Here we choose between two forms of name (singular and plural) based on whether the count is 1 or not. That is the rule in English, but not in other languages. The whole point of ungettext is to defer the logic that performs the mapping from number to text, since it depends on the language.

Unfortunately, I think the only solution is to use more stilted language:

text = ungettext(
    'There is %(count)d %(name)s object available.',
    'There are %(count)d %(name)s objects available.',
    count
) % {
    'count': count,
    'name': Report._meta.verbose_name,
}

and ignore the verbose_name_plural altogether.

Attachments (2)

21650.diff (2.6 KB) - added by Tim Graham 3 years ago.
21650.2.diff (3.2 KB) - added by Tim Graham 3 years ago.

Download all attachments as: .zip

Change History (14)

comment:1 Changed 3 years ago by Claude Paroz

Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/optimization

+1, the count == 1 (and more generally the verbose_name_plural concept, see also #11688) is totally English-centered.

comment:2 Changed 3 years ago by Ned Batchelder

Just to clarify: this ticket is merely about the example in the docs. While the issue in #11688 is true (models' support for singular and plural is English-centric and simplistic), all I'm pointing out here is that the i18n docs could at least not fall into the same trap and suggest a comparison to 1 as the correct way to support plurals.

comment:3 Changed 3 years ago by Claude Paroz

I suggest to simply remove that example in the docs, because if we remove the verbose_name/plural stuff in it, it doesn't bring anything new to the discussion compared to the previous example. Opinion?

comment:4 Changed 3 years ago by Ned Batchelder

My one counter to that might be: Change this example to an explanation of why it isn't a good idea:

Note that pluralization is complicated, and works differently in other languages.
Comparing count to 1 isn't always the correct rule.  This code looks sophisticated, 
but will produce the wrong results for other languages: 

    ....     

Don't try to implement your own singular-or-plural logic, it won't be correct.

comment:5 Changed 3 years ago by Tim Graham

Description: modified (diff)

I don't use i18n, but Ned's suggest seems reasonable to me. Claude, what do you think? My only question would be what modifications to make to the note that follows. Currently it says, "When using this technique", and my understanding is that we'd be changing things to say not to use this technique. I think the note still has value though as it's linked to from elsewhere.

comment:6 Changed 3 years ago by Claude Paroz

Sure, but you know I'm not the most skilled writer for English documentation. Feel free to go ahead.

Changed 3 years ago by Tim Graham

Attachment: 21650.diff added

comment:7 Changed 3 years ago by Tim Graham

Has patch: set

comment:8 Changed 3 years ago by Claude Paroz

Thanks, that looks good. However, I'd like to see somewhere the %(name)s object/%(name)s objects trick that Ned suggested. Even if it might produce suboptimal strings in English, it's often the only proper way to handle i18n in a right manner.

Changed 3 years ago by Tim Graham

Attachment: 21650.2.diff added

comment:9 Changed 3 years ago by Claude Paroz

Fine for me. Ned?

comment:10 Changed 3 years ago by Ned Batchelder

Looks great, thanks!

comment:11 Changed 3 years ago by Tim Graham <timograham@…>

Resolution: fixed
Status: newclosed

In 85270ef3f5bf96b556e697bc5a46bf925ec4be21:

Fixed #21650 -- Corrected bad advice for plural translation.

Thanks nedbatchelder and claudep.

comment:12 Changed 3 years ago by Tim Graham <timograham@…>

In 3b79fbabcdfefa6c5734a9645be4ffee02e4a270:

[1.6.x] Fixed #21650 -- Corrected bad advice for plural translation.

Thanks nedbatchelder and claudep.

Backport of 85270ef3f5 from master

Note: See TracTickets for help on using tickets.
Back to Top