← Back to branch summary

~ubuntu-branches/debian/squeeze/python-django/squeeze

« back to all changes in this revision

Viewing changes to docs/topics/i18n.txt

  • Committer: Bazaar Package Importer
  • Author(s): Chris Lamb, Chris Lamb, David Spreen, Sandro Tosi
  • Date: 2008-11-19 21:31:00 UTC
  • mfrom: (1.2.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20081119213100-gp0lqhxl1qxa6dgl
Tags: 1.0.2-1
http://bugs.debian.org/505783
http://bugs.debian.org/497886
[ Chris Lamb ]
* New upstream bugfix release. Closes: #505783
* Add myself to Uploaders with ACK from Brett.

[ David Spreen ]
* Remove python-pysqlite2 from Recommends because Python 2.5 includes
  sqlite library used by Django. Closes: 497886

[ Sandro Tosi ]
* debian/control
  - switch Vcs-Browser field to viewsvn

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/topics/i18n.txt
131
131
specified with Python's standard named-string interpolation syntax. Example::
132
132
 
133
133
    def my_view(request, m, d):
134
 
        output = _('Today is %(month)s, %s(day)s.') % {'month': m, 'day': d}
 
134
        output = _('Today is %(month)s, %(day)s.') % {'month': m, 'day': d}
135
135
        return HttpResponse(output)
136
136
 
137
137
This technique lets language-specific translations reorder the placeholder
174
174
 
175
175
In this example, ``ugettext_lazy()`` stores a lazy reference to the string --
176
176
not the actual translation. The translation itself will be done when the string
177
 
is used in a string context, such as template rendering on the Django admin site.
 
177
is used in a string context, such as template rendering on the Django admin
 
178
site.
 
179
 
 
180
The result of a ``ugettext_lazy()`` call can be used wherever you would use a
 
181
unicode string (an object with type ``unicode``) in Python. If you try to use
 
182
it where a bytestring (a ``str`` object) is expected, things will not work as
 
183
expected, since a ``ugettext_lazy()`` object doesn't know how to convert
 
184
itself to a bytestring.  You can't use a unicode string inside a bytestring,
 
185
either, so this is consistent with normal Python behavior. For example::
 
186
 
 
187
    # This is fine: putting a unicode proxy into a unicode string.
 
188
    u"Hello %s" % ugettext_lazy("people")
 
189
 
 
190
    # This will not work, since you cannot insert a unicode object
 
191
    # into a bytestring (nor can you insert our unicode proxy there)
 
192
    "Hello %s" % ugettext_lazy("people")
 
193
 
 
194
If you ever see output that looks like ``"hello
 
195
<django.utils.functional...>"``, you have tried to insert the result of
 
196
``ugettext_lazy()`` into a bytestring. That's a bug in your code.
178
197
 
179
198
If you don't like the verbose name ``ugettext_lazy``, you can just alias it as
180
199
``_`` (underscore), like so::
184
203
    class MyThing(models.Model):
185
204
        name = models.CharField(help_text=_('This is the help text'))
186
205
 
187
 
Always use lazy translations in :ref:`Django models <topics-db-models>`. It's a
188
 
good idea to add translations for the field names and table names, too. This
189
 
means writing explicit ``verbose_name`` and ``verbose_name_plural`` options in
190
 
the ``Meta`` class, though::
 
206
Always use lazy translations in :ref:`Django models <topics-db-models>`.
 
207
Field names and table names should be marked for translation (otherwise, they
 
208
won't be translated in the admin interface). This means writing explicit
 
209
``verbose_name`` and ``verbose_name_plural`` options in the ``Meta`` class,
 
210
though, rather than relying on Django's default determination of
 
211
``verbose_name`` and ``verbose_name_plural`` by looking at the model's class
 
212
name::
191
213
 
192
214
    from django.utils.translation import ugettext_lazy as _
193
215
 
276
298
      currently active locale).
277
299
 
278
300
    * ``LANGUAGE_CODE`` is the current user's preferred language, as a string.
279
 
      Example: ``en-us``. (See "How language preference is discovered", below.)
280
 
      
 
301
      Example: ``en-us``. (See :ref:`how-django-discovers-language-preference`,
 
302
      below.)
 
303
 
281
304
    * ``LANGUAGE_BIDI`` is the current locale's direction. If True, it's a
282
305
      right-to-left language, e.g.: Hebrew, Arabic. If False it's a
283
306
      left-to-right language, e.g.: English, French, German etc.
395
418
    application) and English strings (from Django itself). If you want to
396
419
    support a locale for your application that is not already part of
397
420
    Django, you'll need to make at least a minimal translation of the Django
398
 
    core. See the relevant :ref:LocaleMiddleware note`<locale-middleware-notes>`
 
421
    core. See the relevant :ref:`LocaleMiddleware note<locale-middleware-notes>`
399
422
    for more details.
400
423
 
401
424
Message files
492
515
      out empty, so it's your responsibility to change it. Make sure you keep
493
516
      the quotes around your translation.
494
517
    * As a convenience, each message includes, in the form of a comment line
495
 
      prefixed with ``#`` and locted above the ``msgid`` line, the filename and
 
518
      prefixed with ``#`` and located above the ``msgid`` line, the filename and
496
519
      line number from which the translation string was gleaned.
497
520
 
498
521
Long messages are a special case. There, the first string directly after the
544
567
   ``django-admin compilemessages`` works see `gettext on Windows`_ for more
545
568
   information.
546
569
 
 
570
.. _how-django-discovers-language-preference:
 
571
 
547
572
3. How Django discovers language preference
548
573
===========================================
549
574
 
591
616
 
592
617
    * First, it looks for a ``django_language`` key in the current user's
593
618
      session.
594
 
    
 
619
 
595
620
    * Failing that, it looks for a cookie.
596
 
    
 
621
 
597
622
      .. versionchanged:: 1.0
598
 
    
 
623
 
599
624
      In Django version 0.96 and before, the cookie's name is hard-coded to
600
625
      ``django_language``. In Django 1,0, The cookie name is set by the
601
626
      ``LANGUAGE_COOKIE_NAME`` setting. (The default name is
602
627
      ``django_language``.)
603
 
    
 
628
 
604
629
    * Failing that, it looks at the ``Accept-Language`` HTTP header. This
605
630
      header is sent by your browser and tells the server which language(s) you
606
631
      prefer, in order by priority. Django tries each language in the header
607
632
      until it finds one with available translations.
608
 
    
 
633
 
609
634
    * Failing that, it uses the global ``LANGUAGE_CODE`` setting.
610
635
 
611
636
.. _locale-middleware-notes:
615
640
    * In each of these places, the language preference is expected to be in the
616
641
      standard language format, as a string. For example, Brazilian Portuguese
617
642
      is ``pt-br``.
618
 
    
 
643
 
619
644
    * If a base language is available but the sublanguage specified is not,
620
645
      Django uses the base language. For example, if a user specifies ``de-at``
621
646
      (Austrian German) but Django only has ``de`` available, Django uses
622
647
      ``de``.
623
 
    
 
648
 
624
649
    * Only languages listed in the :setting:`LANGUAGES` setting can be selected.
625
650
      If you want to restrict the language selection to a subset of provided
626
651
      languages (because your application doesn't provide all those languages),
761
786
 
762
787
The easiest way out is to store applications that are not part of the project
763
788
(and so carry their own translations) outside the project tree. That way,
764
 
 
765
789
``django-admin.py makemessages`` on the project level will only translate
766
790
strings that are connected to your explicit project and not strings that are
767
791
distributed independently.
782
806
parameter set in request. If session support is enabled, the view
783
807
saves the language choice in the user's session. Otherwise, it saves the
784
808
language choice in a cookie that is by default named ``django_language``.
785
 
(The name can be changed through the ``LANGUAGE_COOKIE_NAME`` setting if you're
786
 
using the Django development version.)
 
809
(The name can be changed through the ``LANGUAGE_COOKIE_NAME`` setting.)
787
810
 
788
811
After setting the language choice, Django redirects the user, following this
789
812
algorithm:
971
994
      * In the ``System variables`` list, click ``Path``, click ``Edit``
972
995
      * Add ``;C:\Program Files\gettext-utils\bin`` at the end of the
973
996
        ``Variable value`` field
 
997
 
 
998
You may also use ``gettext`` binaries you have obtained elsewhere, so long as 
 
999
the ``xgettext --version`` command works properly. Some version 0.14.4 binaries
 
1000
have been found to not support this command. Do not attempt to use Django 
 
1001
translation utilities with a ``gettext`` package if the command ``xgettext
 
1002
--version`` entered at a Windows command prompt causes a popup window saying
 
1003
"xgettext.exe has generated errors and will be closed by Windows".