Code

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

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

Documentation patch for this ticket

Line 
1diff -r 1b2c5120d366 docs/topics/i18n.txt
2--- a/docs/topics/i18n.txt      Wed Jun 24 11:04:18 2009 -0300
3+++ b/docs/topics/i18n.txt      Wed Jun 24 20:37:08 2009 -0300
4@@ -223,7 +223,12 @@
5 ~~~~~~~~~~~~~
6 
7 Use the function ``django.utils.translation.ungettext()`` to specify pluralized
8-messages. Example::
9+messages.
10+
11+``ungettext`` takes three arguments: the singular translation string, the plural
12+translation string and the number of objects.
13+
14+Example::
15 
16     from django.utils.translation import ungettext
17     def hello_world(request, count):
18@@ -232,9 +237,70 @@
19         }
20         return HttpResponse(page)
21 
22-``ungettext`` takes three arguments: the singular translation string, the plural
23-translation string and the number of objects (which is passed to the
24-translation languages as the ``count`` variable).
25+This function is useful when your need you Django application to be localizable
26+to languages where the number and complexity of `plural forms
27+<http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>`_ is
28+greater than the two forms used in English ('object' for the singular and
29+'objects' for all the cases where ``count`` is different from zero, irrespective
30+of its value.)
31+
32+In this example the number of objects is passed to the translation languages as
33+the ``count`` variable.
34+
35+Lets see a slightly more complex usage example::
36+
37+    from django.utils.translation import ungettext
38+
39+    count = Report.objects.count()
40+    if count == 1:
41+        name = Report._meta.verbose_name
42+    else:
43+        name = Report._meta.verbose_name_plural
44+
45+    text = ungettext(
46+            'There is %(count)d %(name)s available.',
47+            'There are %(count)d %(name)s available.',
48+            count
49+    ) % {
50+        'count': count,
51+        'name': name
52+    }
53+
54+Here we reuse localizable, hopefully already translated literals (contained in
55+the ``verbose_name`` and ``verbose_name_plural`` model ``Meta`` options) for
56+other parts of the sentence so all of it is consistently based on the
57+cardinality of the elements at play.
58+
59+.. _pluralization-var-notes:
60+
61+.. note::
62+
63+    When using this technique, make sure you use a single name for every
64+    extrapolated variable included in the literal. In the example above note how
65+    we used the ``name`` Python variable in both translation strings. This
66+    example would fail::
67+
68+        from django.utils.translation import ungettext
69+        from myapp.models import Report
70+
71+        count = Report.objects.count()
72+        if count == 1:
73+        else:
74+        d = {
75+            'count': count,
76+            'name': Report._meta.verbose_name
77+            'plural_name': Report._meta.verbose_name_plural
78+        }
79+        text = ungettext(
80+                'There is %(count)d %(name)s available.',
81+                'There are %(count)d %(plural_name)s available.',
82+                count
83+        ) % d
84+
85+    You would get a ``a format specification for argument 'name', as in
86+    'msgstr[0]', doesn't exist in 'msgid'`` error when running
87+    ``django-admin.py compilemessages`` or a Python ``KeyError`` exception at
88+    runtime.
89 
90 In template code
91 ----------------
92@@ -256,6 +322,8 @@
93 content that will require translation in the future::
94 
95     <title>{% trans "myvar" noop %}</title>
96+
97+Internally, inline translations use an ``ugettext`` call.
98 
99 It's not possible to mix a template variable inside a string within ``{% trans
100 %}``. If your translations require strings with variables (placeholders), use
101@@ -288,8 +356,11 @@
102     There are {{ counter }} {{ name }} objects.
103     {% endblocktrans %}
104 
105-Internally, all block and inline translations use the appropriate
106-``ugettext`` / ``ungettext`` call.
107+When you use the pluralization feature and bind additional values to local
108+variables apart from the counter value that selects the translated literal to be
109+used, have in mind that the ``blocktrans`` construct is internally converted
110+to an ``ungettext`` call. This means the same :ref:`notes
111+<pluralization-var-notes>` apply.
112 
113 Each ``RequestContext`` has access to three translation-specific variables:
114