Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

[1.3.X] Added a few cross references to the i18n docs and documented …

…pgettext and colleagues.

Backport from trunk (r16403).

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.3.X@16404 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit eb96665b7a176224d7287e50cd710708cb24d6ef 1 parent 4f215cf
Jannis Leidel authored June 15, 2011
57  docs/ref/utils.txt
@@ -315,6 +315,48 @@ Atom1Feed
315 315
 
316 316
     Spec: http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html
317 317
 
  318
+``django.utils.functional``
  319
+===========================
  320
+
  321
+.. module:: django.utils.functional
  322
+    :synopsis: Functional programming tools.
  323
+
  324
+.. function:: allow_lazy(func, *resultclasses)
  325
+
  326
+    Django offers many utility functions (particularly in ``django.utils``) that
  327
+    take a string as their first argument and do something to that string. These
  328
+    functions are used by template filters as well as directly in other code.
  329
+
  330
+    If you write your own similar functions and deal with translations, you'll
  331
+    face the problem of what to do when the first argument is a lazy translation
  332
+    object. You don't want to convert it to a string immediately, because you might
  333
+    be using this function outside of a view (and hence the current thread's locale
  334
+    setting will not be correct).
  335
+
  336
+    For cases like this, use the ``django.utils.functional.allow_lazy()``
  337
+    decorator. It modifies the function so that *if* it's called with a lazy
  338
+    translation as the first argument, the function evaluation is delayed until it
  339
+    needs to be converted to a string.
  340
+
  341
+    For example::
  342
+
  343
+        from django.utils.functional import allow_lazy
  344
+
  345
+        def fancy_utility_function(s, ...):
  346
+            # Do some conversion on string 's'
  347
+            ...
  348
+        fancy_utility_function = allow_lazy(fancy_utility_function, unicode)
  349
+
  350
+    The ``allow_lazy()`` decorator takes, in addition to the function to decorate,
  351
+    a number of extra arguments (``*args``) specifying the type(s) that the
  352
+    original function can return. Usually, it's enough to include ``unicode`` here
  353
+    and ensure that your function returns only Unicode strings.
  354
+
  355
+    Using this decorator means you can write your function and assume that the
  356
+    input is a proper string, then add support for lazy translation objects at the
  357
+    end.
  358
+
  359
+
318 360
 ``django.utils.http``
319 361
 =====================
320 362
 
@@ -428,14 +470,23 @@ For a complete discussion on the usage of the following see the
428 470
 
429 471
     Translates ``message`` and returns it in a unicode string
430 472
 
  473
+.. function:: pgettext(context, message)
  474
+
  475
+    Translates ``message`` given the ``context`` and returns
  476
+    it in a unicode string.
  477
+
  478
+    For more information, see :ref:`contextual-markers`.
  479
+
431 480
 .. function:: gettext_lazy(message)
432 481
 .. function:: ugettext_lazy(message)
  482
+.. function:: pgettext_lazy(context, message)
433 483
 
434 484
     Same as the non-lazy versions above, but using lazy execution.
435 485
 
436 486
     See :ref:`lazy translations documentation <lazy-translations>`.
437 487
 
438 488
 .. function:: gettext_noop(message)
  489
+.. function:: ugettext_noop(message)
439 490
 
440 491
     Marks strings for translation but doesn't translate them now. This can be
441 492
     used to store strings in global variables that should stay in the base
@@ -452,8 +503,14 @@ For a complete discussion on the usage of the following see the
452 503
     Translates ``singular`` and ``plural`` and returns the appropriate string
453 504
     based on ``number`` in a unicode string.
454 505
 
  506
+.. function:: npgettext(context, singular, plural, number)
  507
+
  508
+    Translates ``singular`` and ``plural`` and returns the appropriate string
  509
+    based on ``number`` and the ``context`` in a unicode string.
  510
+
455 511
 .. function:: ngettext_lazy(singular, plural, number)
456 512
 .. function:: ungettext_lazy(singular, plural, number)
  513
+.. function:: npgettext_lazy(singular, plural, number)
457 514
 
458 515
     Same as the non-lazy versions above, but using lazy execution.
459 516
 
111  docs/topics/i18n/internationalization.txt
@@ -2,6 +2,8 @@
2 2
 Internationalization
3 3
 ====================
4 4
 
  5
+.. module:: django.utils.translation
  6
+
5 7
 Overview
6 8
 ========
7 9
 
@@ -24,19 +26,22 @@ Specifying translation strings: In Python code
24 26
 Standard translation
25 27
 --------------------
26 28
 
27  
-Specify a translation string by using the function ``ugettext()``. It's
28  
-convention to import this as a shorter alias, ``_``, to save typing.
  29
+Specify a translation string by using the function
  30
+:func:`~django.utils.translation.ugettext`. It's convention to import this
  31
+as a shorter alias, ``_``, to save typing.
29 32
 
30 33
 .. note::
31 34
     Python's standard library ``gettext`` module installs ``_()`` into the
32 35
     global namespace, as an alias for ``gettext()``. In Django, we have chosen
33 36
     not to follow this practice, for a couple of reasons:
34 37
 
35  
-      1. For international character set (Unicode) support, ``ugettext()`` is
36  
-         more useful than ``gettext()``. Sometimes, you should be using
37  
-         ``ugettext_lazy()`` as the default translation method for a particular
38  
-         file. Without ``_()`` in the global namespace, the developer has to
39  
-         think about which is the most appropriate translation function.
  38
+      1. For international character set (Unicode) support,
  39
+         :func:`~django.utils.translation.ugettext` is more useful than
  40
+         ``gettext()``. Sometimes, you should be using
  41
+         :func:`~django.utils.translation.ugettext_lazy` as the default
  42
+         translation method for a particular file. Without ``_()`` in the
  43
+         global namespace, the developer has to think about which is the
  44
+         most appropriate translation function.
40 45
 
41 46
       2. The underscore character (``_``) is used to represent "the previous
42 47
          result" in Python's interactive shell and doctest tests. Installing a
@@ -127,20 +132,20 @@ displayed by most translation tools.
127 132
 Marking strings as no-op
128 133
 ------------------------
129 134
 
130  
-Use the function ``django.utils.translation.ugettext_noop()`` to mark a string
131  
-as a translation string without translating it. The string is later translated
132  
-from a variable.
  135
+Use the function :func:`django.utils.translation.ugettext_noop()` to mark a
  136
+string as a translation string without translating it. The string is later
  137
+translated from a variable.
133 138
 
134 139
 Use this if you have constant strings that should be stored in the source
135  
-language because they are exchanged over systems or users -- such as strings in
136  
-a database -- but should be translated at the last possible point in time, such
137  
-as when the string is presented to the user.
  140
+language because they are exchanged over systems or users -- such as strings
  141
+in a database -- but should be translated at the last possible point in time,
  142
+such as when the string is presented to the user.
138 143
 
139 144
 Pluralization
140 145
 -------------
141 146
 
142  
-Use the function ``django.utils.translation.ungettext()`` to specify pluralized
143  
-messages.
  147
+Use the function :func:`django.utils.translation.ungettext()` to specify
  148
+pluralized messages.
144 149
 
145 150
 ``ungettext`` takes three arguments: the singular translation string, the plural
146 151
 translation string and the number of objects.
@@ -155,14 +160,18 @@ of its value.)
155 160
 For example::
156 161
 
157 162
     from django.utils.translation import ungettext
  163
+
158 164
     def hello_world(request, count):
159  
-        page = ungettext('there is %(count)d object', 'there are %(count)d objects', count) % {
  165
+        page = ungettext(
  166
+            'there is %(count)d object',
  167
+            'there are %(count)d objects',
  168
+        count) % {
160 169
             'count': count,
161 170
         }
162 171
         return HttpResponse(page)
163 172
 
164  
-In this example the number of objects is passed to the translation languages as
165  
-the ``count`` variable.
  173
+In this example the number of objects is passed to the translation
  174
+languages as the ``count`` variable.
166 175
 
167 176
 Lets see a slightly more complex usage example::
168 177
 
@@ -226,8 +235,8 @@ Contextual markers
226 235
 Sometimes words have several meanings, such as ``"May"`` in English, which
227 236
 refers to a month name and to a verb. To enable translators to translate
228 237
 these words correctly in different contexts, you can use the
229  
-``django.utils.translation.pgettext()`` function, or the
230  
-``django.utils.translation.npgettext()`` function if the string needs
  238
+:func:`django.utils.translation.pgettext()` function, or the
  239
+:func:`django.utils.translation.npgettext()` function if the string needs
231 240
 pluralization. Both take a context string as the first variable.
232 241
 
233 242
 In the resulting .po file, the string will then appear as often as there are
@@ -241,6 +250,14 @@ For example::
241 250
 
242 251
     month = pgettext("month name", "May")
243 252
 
  253
+or::
  254
+
  255
+    from django.utils.translation import pgettext_lazy
  256
+
  257
+    class MyThing(models.Model):
  258
+        name = models.CharField(help_text=pgettext_lazy(
  259
+            'help text for MyThing model', 'This is the help text'))
  260
+
244 261
 will appear in the .po file as:
245 262
 
246 263
 .. code-block:: po
@@ -254,7 +271,7 @@ will appear in the .po file as:
254 271
 Lazy translation
255 272
 ----------------
256 273
 
257  
-Use the function ``django.utils.translation.ugettext_lazy()`` to translate
  274
+Use the function :func:`django.utils.translation.ugettext_lazy()` to translate
258 275
 strings lazily -- when the value is accessed rather than when the
259 276
 ``ugettext_lazy()`` function is called.
260 277
 
@@ -308,6 +325,7 @@ name::
308 325
 
309 326
     class MyThing(models.Model):
310 327
         name = models.CharField(_('name'), help_text=_('This is the help text'))
  328
+
311 329
         class Meta:
312 330
             verbose_name = _('my thing')
313 331
             verbose_name_plural = _('mythings')
@@ -360,9 +378,9 @@ Joining strings: string_concat()
360 378
 
361 379
 Standard Python string joins (``''.join([...])``) will not work on lists
362 380
 containing lazy translation objects. Instead, you can use
363  
-``django.utils.translation.string_concat()``, which creates a lazy object that
364  
-concatenates its contents *and* converts them to strings only when the result
365  
-is included in a string. For example::
  381
+:func:`django.utils.translation.string_concat()`, which creates a lazy object
  382
+that concatenates its contents *and* converts them to strings only when the
  383
+result is included in a string. For example::
366 384
 
367 385
     from django.utils.translation import string_concat
368 386
     ...
@@ -374,47 +392,13 @@ In this case, the lazy translations in ``result`` will only be converted to
374 392
 strings when ``result`` itself is used in a string (usually at template
375 393
 rendering time).
376 394
 
377  
-The allow_lazy() decorator
378  
-~~~~~~~~~~~~~~~~~~~~~~~~~~
379  
-
380  
-Django offers many utility functions (particularly in ``django.utils``) that
381  
-take a string as their first argument and do something to that string. These
382  
-functions are used by template filters as well as directly in other code.
383  
-
384  
-If you write your own similar functions and deal with translations, you'll
385  
-face the problem of what to do when the first argument is a lazy translation
386  
-object. You don't want to convert it to a string immediately, because you might
387  
-be using this function outside of a view (and hence the current thread's locale
388  
-setting will not be correct).
389  
-
390  
-For cases like this, use the ``django.utils.functional.allow_lazy()``
391  
-decorator. It modifies the function so that *if* it's called with a lazy
392  
-translation as the first argument, the function evaluation is delayed until it
393  
-needs to be converted to a string.
394  
-
395  
-For example::
396  
-
397  
-    from django.utils.functional import allow_lazy
398  
-
399  
-    def fancy_utility_function(s, ...):
400  
-        # Do some conversion on string 's'
401  
-        ...
402  
-    fancy_utility_function = allow_lazy(fancy_utility_function, unicode)
403  
-
404  
-The ``allow_lazy()`` decorator takes, in addition to the function to decorate,
405  
-a number of extra arguments (``*args``) specifying the type(s) that the
406  
-original function can return. Usually, it's enough to include ``unicode`` here
407  
-and ensure that your function returns only Unicode strings.
  395
+Localized names of languages
  396
+============================
408 397
 
409  
-Using this decorator means you can write your function and assume that the
410  
-input is a proper string, then add support for lazy translation objects at the
411  
-end.
  398
+.. function:: get_language_info
412 399
 
413 400
 .. versionadded:: 1.3
414 401
 
415  
-Localized names of languages
416  
-============================
417  
-
418 402
 The ``get_language_info()`` function provides detailed information about
419 403
 languages::
420 404
 
@@ -456,7 +440,8 @@ require translation in the future::
456 440
 
457 441
     <title>{% trans "myvar" noop %}</title>
458 442
 
459  
-Internally, inline translations use an ``ugettext`` call.
  443
+Internally, inline translations use an
  444
+:func:`~django.utils.translation.ugettext` call.
460 445
 
461 446
 In case a template var (``myvar`` above) is passed to the tag, the tag will
462 447
 first resolve such variable to a string at run-time and then look up that
@@ -777,7 +762,7 @@ The ``set_language`` redirect view
777 762
 
778 763
 .. function:: set_language(request)
779 764
 
780  
-As a convenience, Django comes with a view, :meth:`django.views.i18n.set_language`,
  765
+As a convenience, Django comes with a view, :func:`django.views.i18n.set_language`,
781 766
 that sets a user's language preference and redirects back to the previous page.
782 767
 
783 768
 Activate this view by adding the following line to your URLconf::

0 notes on commit eb96665

Please sign in to comment.
Something went wrong with that request. Please try again.