Added note to docs/settings.txt and docs/i18n.txt about not importing from django.utils.translation in the settings file

git-svn-id: http://code.djangoproject.com/svn/django/trunk@3318 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 22 insertions, 0 deletions

diff --git a/docs/settings.txt b/docs/settings.txt
index 9e1c6b529b..5b75e29172 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -501,6 +501,28 @@ specifies which languages are available for language selection. See the
 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 ``LANGUAGES`` setting, it's OK to mark the languages as
+translation strings (as in the default value displayed 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.
+
+The solution is to use a "dummy" ``gettext()`` function. Here's a sample
+settings file::
+
+    gettext = lambda s: s
+
+    LANGUAGES = (
+        ('de', gettext('German')),
+        ('en', gettext('English')),
+    )
+
+With this arrangement, ``make-messages.py`` 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 ``LANGUAGES`` at runtime.
+
 MANAGERS
 --------