Commits

Alex Marandon committed 587336f

Add doc on USE_SESSION written by Sylvain Fourmanoit

  • Participants
  • Parent commits 2750a84

Comments (0)

Files changed (2)

 #. Add ``'localeurl.middleware.LocaleURLMiddleware'`` to
    ``settings.MIDDLEWARE_CLASSES``. It must come *before*
    ``'django.middleware.common.CommonMiddleware'`` or ``settings.APPEND_SLASH``
-   will not work. Make sure Django's built-in ``LocaleMiddleware`` is **not**
-   in your ``MIDDLEWARE_CLASSES`` setting; ``LocaleURLMiddleware`` replaces it
-   and the two will not work together.
+   will not work. Make sure Django's built-in ``LocaleMiddleware`` is **not** in
+   your ``MIDDLEWARE_CLASSES`` setting; ``LocaleURLMiddleware`` replaces it and
+   the two will not work together. It must also come after
+   ``django.contrib.sessions.middleware.SessionMiddleware`` if you plan using
+   the session fallback (see ``LOCALEURL_USE_SESSION`` below). 
 
 #. Add ``'localeurl'`` to ``settings.INSTALLED_APPS``. Because the application
    needs to replace the standard ``urlresolvers.reverse`` function, it is
   URL. (The default behavior, preserved for backwards compatibility,
   is to fallback directly to ``settings.LANGUAGE_CODE``).
 
+``LOCALEURL_USE_SESSION`` (default: ``False``)
+  Whether to check the availability of a user-selected locale in the Django
+  session as a fallback in case no locale is specified in the URL. If set to
+  ``True``, the locale will be saved to the session every time the
+  ``change_locale`` view is invoked, under the ``locale`` key. When used and
+  available, the session locale takes precedence over the ``Accepted-Language``
+  fallback (see ``LOCALEURL_USE_ACCEPT_LANGUAGE`` above). It's safe to change
+  the ``locale`` key in the session from any external view (from a user
+  preferences for instance), and the change will be picked up by ``locale-url``.
+  It's also possible to write a `middleware`_ to have a more
+  complicated ``locale`` setup policy if you have special needs, such as setting
+  ``locale`` from a field in the current user profile. 
+
+  Finally, it's important to understand than just following a localized link
+  such as one generated using the ``chlocale`` filter won't switch the session's
+  ``locale``: only calling the ``change_locale`` view will.
+
+  To use this feature, `sessions`_ must be in use, and
+  ``django.contrib.sessions.middleware.SessionMiddleware`` must come *before*
+  ``localeurl.middleware.LocaleURLMiddleware`` in
+  ``settings.MIDDLEWARE_CLASSES``.
+
+.. _`sessions` : http://docs.djangoproject.com/en/dev/topics/http/sessions/
+.. _`middleware` : https://docs.djangoproject.com/en/dev/topics/http/middleware/
+
+
 ``LOCALE_REDIRECT_PERMANENT`` (default: ``True``)
   Whether to use a permanent redirect (301 status code) or temporary
   redirect (302) when redirecting users from the no-locale version of a URL
 as ``django.middleware.locale.LocaleMiddleware``) or from
 ``settings.LANGUAGE_CODE``. So a request for ``/about/`` would be redirected to
 ``/fr/about/`` if French is the default language. (This behavior can be changed
-using ``settings.PREFIX_DEFAULT_LOCALE``.)
+using ``settings.PREFIX_DEFAULT_LOCALE``.) Determination of the default locale
+can also take into account the ``Accept-Language`` browser header (see
+``settings.LOCALURL_USE_ACCEPT_LANGUAGE``), or a previously user-selected locale
+(see ``settings.LOCALURL_USE_SESSION``, and the ``change_locale`` view below).
 
 Templates
 =========
 
 .. _`redirect view`: http://docs.djangoproject.com/en/dev/topics/i18n/#the-set-language-redirect-view
 
+When ``settings.LOCALURL_USE_SESSION`` is set to ``True`` (default is
+``False``), It also records the user-selected locale to the current Django
+session. The last selected locale will then be used as the default locale when
+redirecting from paths missing a locale prefix.
+
 Example
 -------