Commit 12ff1623 authored by Bernardo Pires's avatar Bernardo Pires Committed by Baptiste Mispelon
Browse files

[1.5.x] Fixed #21372 -- Corrected docs regarding translating LANGUAGES. 

Corrected LANGUAGES documentation on how to translate language
names. Now using django.utils.translation.ugettext_lazy instead
of a dummy gettext() function.

Thanks to Salvatore for the report.

Backport of 8bc350b3 from master.

Conflicts:
	docs/topics/i18n/translation.txt
parent 1669a438

docs/ref/settings.txt

+7 −17
Original line number Diff line number Diff line
@@ -1279,29 +1279,19 @@ This specifies which languages are available for language selection. See 
Generally, the default value should suffice. Only set this setting if you want

to restrict language selection to a subset of the Django-provided languages.



If you define a custom :setting:`LANGUAGES` setting, it's OK to mark the

languages as translation strings (as in the default value referred to above)

-- but use a "dummy" ``gettext()`` function, not the one in

``django.utils.translation``. You should *never* import

``django.utils.translation`` from within your settings file, because that

module in itself depends on the settings, and that would cause a circular

import.

If you define a custom :setting:`LANGUAGES` setting, you can mark the

language names as translation strings using the

:func:`~django.utils.translation.ugettext_lazy` function.



The solution is to use a "dummy" ``gettext()`` function. Here's a sample

settings file::

Here's a sample settings file::



    gettext = lambda s: s

    from django.utils.translation import ugettext_lazy as _



    LANGUAGES = (

        ('de', gettext('German')),

        ('en', gettext('English')),

        ('de', _('German')),

        ('en', _('English')),

    )



With this arrangement, ``django-admin.py makemessages`` will still find and

mark these strings for translation, but the translation won't happen at

runtime -- so you'll have to remember to wrap the languages in the *real*

``gettext()`` in any code that uses :setting:`LANGUAGES` at runtime.



.. setting:: LOCALE_PATHS



LOCALE_PATHS

docs/topics/i18n/translation.txt

+7 −17
Original line number Diff line number Diff line
@@ -1604,29 +1604,19 @@ Notes: 
  en-us).



* If you define a custom :setting:`LANGUAGES` setting, as explained in the

  previous bullet, it's OK to mark the languages as translation strings

  -- but use a "dummy" ``ugettext()`` function, not the one in

  ``django.utils.translation``. You should *never* import

  ``django.utils.translation`` from within your settings file, because that

  module in itself depends on the settings, and that would cause a circular

  import.

  previous bullet, you can mark the language names as translation strings

  -- but use :func:`~django.utils.translation.ugettext_lazy` instead of

  :func:`~django.utils.translation.ugettext` to avoid a circular import.



  The solution is to use a "dummy" ``ugettext()`` function. Here's a sample

  settings file::

  Here's a sample settings file::



      ugettext = lambda s: s

      from django.utils.translation import ugettext_lazy as _



      LANGUAGES = (

          ('de', ugettext('German')),

          ('en', ugettext('English')),

          ('de', _('German')),

          ('en', _('English')),

      )



  With this arrangement, :djadmin:`django-admin.py makemessages <makemessages>`

  will still find and mark these strings for translation, but the translation

  won't happen at runtime -- so you'll have to remember to wrap the languages in

  the *real* ``ugettext()`` in any code that uses :setting:`LANGUAGES` at

  runtime.



* The ``LocaleMiddleware`` can only select languages for which there is a

  Django-provided base translation. If you want to provide translations

  for your application that aren't already in the set of translations