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

1 files changed, 36 insertions, 4 deletions

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.