Ticket #21650: 21650.2.diff

File 21650.2.diff, 3.2 KB (added by Tim Graham, 11 years ago)
  • docs/topics/i18n/translation.txt

    diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt
    index cc4c24d..0202a88 100644
    a b For example::  
    206206In this example the number of objects is passed to the translation
    207207languages as the ``count`` variable.
    208208
    209 Lets see a slightly more complex usage example::
     209Note that pluralization is complicated and works differently in each language.
     210Comparing ``count`` to 1 isn't always the correct rule. This code looks
     211sophisticated, but will produce the wrong results for some languages::
    210212
    211213    from django.utils.translation import ungettext
    212214    from myapp.models import Report
    Lets see a slightly more complex usage example::  
    218220        name = Report._meta.verbose_name_plural
    219221
    220222    text = ungettext(
    221             'There is %(count)d %(name)s available.',
    222             'There are %(count)d %(name)s available.',
    223             count
     223        'There is %(count)d %(name)s available.',
     224        'There are %(count)d %(name)s available.',
     225        count
    224226    ) % {
    225227        'count': count,
    226228        'name': name
    227229    }
    228230
    229 Here we reuse localizable, hopefully already translated literals (contained in
    230 the ``verbose_name`` and ``verbose_name_plural`` model ``Meta`` options) for
    231 other parts of the sentence so all of it is consistently based on the
    232 cardinality of the elements at play.
     231Don't try to implement your own singular-or-plural logic, it won't be correct.
     232In a case like this, consider something like the following::
     233
     234    text = ungettext(
     235        'There is %(count)d %(name)s object available.',
     236        'There are %(count)d %(name)s objects available.',
     237        count
     238    ) % {
     239        'count': count,
     240        'name': Report._meta.verbose_name,
     241    }
    233242
    234243.. _pluralization-var-notes:
    235244
    236245.. note::
    237246
    238     When using this technique, make sure you use a single name for every
    239     extrapolated variable included in the literal. In the example above note how
    240     we used the ``name`` Python variable in both translation strings. This
    241     example would fail::
     247    When using ``ungettext()``, make sure you use a single name for every
     248    extrapolated variable included in the literal. In the examples above, note
     249    how we used the ``name`` Python variable in both translation strings. This
     250    example, besides being incorrect in some languages as noted above, would
     251    fail::
    242252
    243         from django.utils.translation import ungettext
    244         from myapp.models import Report
    245 
    246         count = Report.objects.count()
    247         d = {
    248             'count': count,
     253        text = ungettext(
     254            'There is %(count)d %(name)s available.',
     255            'There are %(count)d %(plural_name)s available.',
     256            count
     257        ) % {
     258            'count': Report.objects.count(),
    249259            'name': Report._meta.verbose_name,
    250260            'plural_name': Report._meta.verbose_name_plural
    251261        }
    252         text = ungettext(
    253                 'There is %(count)d %(name)s available.',
    254                 'There are %(count)d %(plural_name)s available.',
    255                 count
    256         ) % d
    257262
    258263    You would get an error when running :djadmin:`django-admin.py
    259264    compilemessages <compilemessages>`::
Back to Top