[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 8bc350b38516d8c3a14aed113dd3402b9375b75c from master.

Conflicts:
	docs/topics/i18n/translation.txt

2 files changed, 14 insertions, 34 deletions

diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index c085ea2505..0f04629e87 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -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
diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt
index b87abeb1bf..106b8c5720 100644
--- a/docs/topics/i18n/translation.txt
+++ b/docs/topics/i18n/translation.txt
@@ -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