django-localeurl / docs / setup.rst


This section describes how to install the localeurl application in your Django project.


The localeurl application requires Django 1.0 or higher.


Setup consists of installing the middleware and adding 'localeurl' to the installed applications list.

  1. 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. It must also come after django.contrib.sessions.middleware.SessionMiddleware if you plan using the session fallback (see LOCALEURL_USE_SESSION below).

  2. Add 'localeurl' to settings.INSTALLED_APPS. Because the application needs to replace the standard urlresolvers.reverse function, it is important to place it at the top of the list:

  3. If you want to use the view, include the localeurl URLconf module in your project:

    urlpatterns = patterns('',
        (r'^localeurl/', include('localeurl.urls')),
  4. Make sure settings.LANGUAGE_CODE or its root language is in settings.LANGUAGES. For example, if LANGUAGE_CODE == 'en-us' then LANGUAGES must contain either 'en-us' or 'en'. If you have not changed either option you do not have to do anything.


The application can be configured by editing the project's file.


A tuple of regular expressions matching paths that will not be redirected to add the language prefix. For example, a site with a language selection splash page would add '^/$' as a locale independent path match.


Whether paths starting with settings.MEDIA_URL (if it is a path, i.e. not a full URL) are considered to be locale-independent.
Whether paths starting with settings.STATIC_URL (if it is a path, i.e. not a full URL) are considered to be locale-independent.
Whether to add the prefix for the default language (settings.LANGUAGE_CODE). For example, if LANGUAGE_CODE == 'en' then the path /about/ will be passed to the URL resolver unchanged and /en/about/ will be redirected to /about/.
Whether to check the Accept-Language header from the browser as an intermediate fallback in case no locale is specified in the URL. (The default behavior, preserved for backwards compatibility, is to fallback directly to settings.LANGUAGE_CODE).

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.

Whether to use a permanent redirect (301 status code) or temporary redirect (302) when redirecting users from the no-locale version of a URL to the default locale (or the locale specified in their Accept-Language header if LOCALEURL_USE_ACCEPT_LANGUAGE is True). If Accept-Language is not used, these redirects will never change (as long as the default locale never changes), so 301 (the default) is a fine choice. If you use Accept-Language you may want to consider switching this to False, as the redirect will then be dependent on the user's Accept-Language header.