Fixed #22120 -- Documented persistent activation of languages and cleaned up language session key use

3 files changed, 47 insertions, 9 deletions

diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index 5313a1de19..15242f030f 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -937,6 +937,10 @@ For a complete discussion on the usage of the following see the
     so by translating the Django translation tags into standard gettext function
     invocations.
 
+.. data:: LANGUAGE_SESSION_KEY
+
+    Session key under which the active language for the current session is stored.
+
 .. _time-zone-selection-functions:
 
 ``django.utils.timezone``
diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt
index 400c5d0759..c7b545b501 100644
--- a/docs/releases/1.7.txt
+++ b/docs/releases/1.7.txt
@@ -537,11 +537,13 @@ Internationalization
   attribute allows you to customize the redirects issued by the middleware.
 
 * The :class:`~django.middleware.locale.LocaleMiddleware` now stores the user's
-  selected language with the session key ``_language``. Previously it was
-  stored with the key ``django_language``, but keys reserved for Django should
-  start with an underscore. For backwards compatibility ``django_language`` is
-  still read from in 1.7. Sessions will be migrated to the new ``_language``
-  key as they are written.
+  selected language with the session key ``_language``. This should only be
+  accessed using the :data:`~django.utils.translation.LANGUAGE_SESSION_KEY`
+  constant. Previously it was stored with the key ``django_language`` and the
+  ``LANGUAGE_SESSION_KEY`` constant did not exist, but keys reserved for Django
+  should start with an underscore. For backwards compatibility ``django_language``
+  is still read from in 1.7. Sessions will be migrated to the new key
+  as they are written.
 
 * The :ttag:`blocktrans` now supports a ``trimmed`` option. This
   option will remove newline characters from the beginning and the end of the
diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt
index 62729d55da..0a5fa925bc 100644
--- a/docs/topics/i18n/translation.txt
+++ b/docs/topics/i18n/translation.txt
@@ -1510,6 +1510,38 @@ Here's example HTML template code:
 In this example, Django looks up the URL of the page to which the user will be
 redirected in the ``redirect_to`` context variable.
 
+Explicitly setting the active language
+--------------------------------------
+
+.. highlightlang:: python
+
+You may want to set the active language for the current session explicitly. Perhaps
+a user's language preference is retrieved from another system, for example.
+You've already been introduced to :func:`django.utils.translation.activate()`. That
+applies to the current thread only. To persist the language for the entire
+session, also modify :data:`~django.utils.translation.LANGUAGE_SESSION_KEY`
+in the session::
+
+    from django.utils import translation
+    user_language = 'fr'
+    translation.activate(user_language)
+    request.session[translation.LANGUAGE_SESSION_KEY] = user_language
+
+You would typically want to use both: :func:`django.utils.translation.activate()`
+will change the language for this thread, and modifying the session makes this
+preference persist in future requests.
+
+If you are not using sessions, the language will persist in a cookie, whose name
+is configured in :setting:`LANGUAGE_COOKIE_NAME`. For example::
+
+    from django.utils import translation
+    from django import http
+    from django.conf import settings
+    user_language = 'fr'
+    translation.activate(user_language)
+    response = http.HttpResponse(...)
+    response.set_cookie(settings.LANGUAGE_COOKIE_NAME, user_language)
+
 Using translations outside views and templates
 ----------------------------------------------
 
@@ -1621,13 +1653,13 @@ following this algorithm:
   root URLconf. See :ref:`url-internationalization` for more information
   about the language prefix and how to internationalize URL patterns.
 
-* Failing that, it looks for a ``_language`` key in the current user's session.
+* Failing that, it looks for the :data:`~django.utils.translation.LANGUAGE_SESSION_KEY`
+  key in the current user's session.
 
   .. versionchanged:: 1.7
 
-      In previous versions, the key was named ``django_language`` but it was
-      renamed to start with an underscore to denote a Django reserved session
-      key.
+      In previous versions, the key was named ``django_language``, and the
+      ``LANGUAGE_SESSION_KEY`` constant did not exist.
 
 * Failing that, it looks for a cookie.