Ticket #10604: 10604-ungettext-additional-vars-name-warning.2.diff

File 10604-ungettext-additional-vars-name-warning.2.diff, 4.0 KB (added by ramiro, 6 years ago)

Smae patch with a code example fix. Thanks Alex Gaynor for noting it.

  • docs/topics/i18n.txt

    diff -r 1b2c5120d366 docs/topics/i18n.txt
    a b  
    223223~~~~~~~~~~~~~
    224224
    225225Use the function ``django.utils.translation.ungettext()`` to specify pluralized
    226 messages. Example::
     226messages.
     227
     228``ungettext`` takes three arguments: the singular translation string, the plural
     229translation string and the number of objects.
     230
     231This function is useful when your need you Django application to be localizable
     232to languages where the number and complexity of `plural forms
     233<http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>`_ is
     234greater than the two forms used in English ('object' for the singular and
     235'objects' for all the cases where ``count`` is different from zero, irrespective
     236of its value.)
     237
     238Example::
    227239
    228240    from django.utils.translation import ungettext
    229241    def hello_world(request, count):
     
    232244        }
    233245        return HttpResponse(page)
    234246
    235 ``ungettext`` takes three arguments: the singular translation string, the plural
    236 translation string and the number of objects (which is passed to the
    237 translation languages as the ``count`` variable).
     247In this example the number of objects is passed to the translation languages as
     248the ``count`` variable.
     249
     250Lets see a slightly more complex usage example::
     251
     252    from django.utils.translation import ungettext
     253
     254    count = Report.objects.count()
     255    if count == 1:
     256        name = Report._meta.verbose_name
     257    else:
     258        name = Report._meta.verbose_name_plural
     259
     260    text = ungettext(
     261            'There is %(count)d %(name)s available.',
     262            'There are %(count)d %(name)s available.',
     263            count
     264    ) % {
     265        'count': count,
     266        'name': name
     267    }
     268
     269Here we reuse localizable, hopefully already translated literals (contained in
     270the ``verbose_name`` and ``verbose_name_plural`` model ``Meta`` options) for
     271other parts of the sentence so all of it is consistently based on the
     272cardinality of the elements at play.
     273
     274.. _pluralization-var-notes:
     275
     276.. note::
     277
     278    When using this technique, make sure you use a single name for every
     279    extrapolated variable included in the literal. In the example above note how
     280    we used the ``name`` Python variable in both translation strings. This
     281    example would fail::
     282
     283        from django.utils.translation import ungettext
     284        from myapp.models import Report
     285
     286        count = Report.objects.count()
     287        d = {
     288            'count': count,
     289            'name': Report._meta.verbose_name
     290            'plural_name': Report._meta.verbose_name_plural
     291        }
     292        text = ungettext(
     293                'There is %(count)d %(name)s available.',
     294                'There are %(count)d %(plural_name)s available.',
     295                count
     296        ) % d
     297
     298    You would get a ``a format specification for argument 'name', as in
     299    'msgstr[0]', doesn't exist in 'msgid'`` error when running
     300    ``django-admin.py compilemessages`` or a ``KeyError`` Python exception at
     301    runtime.
    238302
    239303In template code
    240304----------------
     
    256320content that will require translation in the future::
    257321
    258322    <title>{% trans "myvar" noop %}</title>
     323
     324Internally, inline translations use an ``ugettext`` call.
    259325
    260326It's not possible to mix a template variable inside a string within ``{% trans
    261327%}``. If your translations require strings with variables (placeholders), use
     
    288354    There are {{ counter }} {{ name }} objects.
    289355    {% endblocktrans %}
    290356
    291 Internally, all block and inline translations use the appropriate
    292 ``ugettext`` / ``ungettext`` call.
     357When you use the pluralization feature and bind additional values to local
     358variables apart from the counter value that selects the translated literal to be
     359used, have in mind that the ``blocktrans`` construct is internally converted
     360to an ``ungettext`` call. This means the same :ref:`notes
     361<pluralization-var-notes>` apply.
    293362
    294363Each ``RequestContext`` has access to three translation-specific variables:
    295364
Back to Top