Refs #15902 -- Deprecated storing user's language in the session.

4 files changed, 27 insertions, 16 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 27dafd7b96..02935c01a2 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -24,6 +24,9 @@ details on these changes.
   ``ugettext_noop()``, ``ungettext()``, and ``ungettext_lazy()`` will be
   removed.
 
+* ``django.views.i18n.set_language()`` will no longer set the user language in
+  ``request.session`` (key ``django.utils.translation.LANGUAGE_SESSION_KEY``).
+
 .. _deprecation-removed-in-3.1:
 
 3.1
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index cd7c7aca63..2becfea269 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -1106,3 +1106,8 @@ functions without the ``u``.
 
     Session key under which the active language for the current session is
     stored.
+
+    .. deprecated:: 3.0
+
+        The language won't be stored in the session in Django 4.0. Use the
+        :setting:`LANGUAGE_COOKIE_NAME` cookie instead.
diff --git a/docs/releases/3.0.txt b/docs/releases/3.0.txt
index b2e6b479e7..f036969c92 100644
--- a/docs/releases/3.0.txt
+++ b/docs/releases/3.0.txt
@@ -302,6 +302,11 @@ Miscellaneous
 * ``ContentType.__str__()`` now includes the model's ``app_label`` to
   disambiguate model's with the same name in different apps.
 
+* Because accessing the language in the session rather than in the cookie is
+  deprecated, ``LocaleMiddleware`` no longer looks for the user's language in
+  the session and :func:`django.contrib.auth.logout` no longer preserves the
+  session's language after logout.
+
 .. _deprecated-features-3.0:
 
 Features deprecated in 3.0
@@ -332,6 +337,11 @@ Miscellaneous
   :func:`~django.utils.translation.ngettext`, and
   :func:`~django.utils.translation.ngettext_lazy`.
 
+* To limit creation of sessions and hence favor some caching strategies,
+  :func:`django.views.i18n.set_language` will stop setting the user's language
+  in the session in Django 4.0. Since Django 2.1, the language is always stored
+  in the :setting:`LANGUAGE_COOKIE_NAME` cookie.
+
 .. _removed-features-3.0:
 
 Features removed in 3.0
diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt
index 3b09e41617..00338100f9 100644
--- a/docs/topics/i18n/translation.txt
+++ b/docs/topics/i18n/translation.txt
@@ -1824,28 +1824,24 @@ You may want to set the active language for the current session explicitly. Perh
 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::
+session in a cookie, set the :setting:`LANGUAGE_COOKIE_NAME` cookie on the
+response::
 
+    from django.conf import settings
+    from django.http import HttpResponse
     from django.utils import translation
     user_language = 'fr'
     translation.activate(user_language)
-    request.session[translation.LANGUAGE_SESSION_KEY] = user_language
+    response = HttpResponse(...)
+    response.set_cookie(settings.LANGUAGE_COOKIE_NAME, 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
+changes the language for this thread, and setting the cookie 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::
+.. versionchanged:: 3.0
 
-    from django.conf import settings
-    from django.http import HttpResponse
-    from django.utils import translation
-    user_language = 'fr'
-    translation.activate(user_language)
-    response = HttpResponse(...)
-    response.set_cookie(settings.LANGUAGE_COOKIE_NAME, user_language)
+    In older versions, you could set the language in the current session.
 
 Using translations outside views and templates
 ----------------------------------------------
@@ -1980,9 +1976,6 @@ 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 the :data:`~django.utils.translation.LANGUAGE_SESSION_KEY`
-  key in the current user's session.
-
 * Failing that, it looks for a cookie.
 
   The name of the cookie used is set by the :setting:`LANGUAGE_COOKIE_NAME`