Installation¶
This section describes how to install the localeurl application in your Django project.
Setup¶
Setup consists of installing the middleware and adding 'localeurl'
to the installed applications list.
Add
'localeurl.middleware.LocaleURLMiddleware'
tosettings.MIDDLEWARE_CLASSES
. It must come before'django.middleware.common.CommonMiddleware'
orsettings.APPEND_SLASH
will not work. Make sure Django’s built-inLocaleMiddleware
is not in yourMIDDLEWARE_CLASSES
setting;LocaleURLMiddleware
replaces it and the two will not work together. It must also come afterdjango.contrib.sessions.middleware.SessionMiddleware
if you plan using the session fallback (seeLOCALEURL_USE_SESSION
below).Add
'localeurl'
tosettings.INSTALLED_APPS
. Because the application needs to replace the standardurlresolvers.reverse
function, it is important to place it at the top of the list:INSTALLED_APPS = ( 'localeurl', ... )
If you want to use the view, include the localeurl URLconf module in your project:
urlpatterns = patterns('', ... (r'^localeurl/', include('localeurl.urls')), ... )
Make sure
settings.LANGUAGE_CODE
or its root language is insettings.LANGUAGES
. For example, ifLANGUAGE_CODE == 'en-us'
thenLANGUAGES
must contain either'en-us'
or'en'
. If you have not changed either option you do not have to do anything.
Configuration¶
The application can be configured by editing the project’s settings.py
file.
LOCALE_INDEPENDENT_PATHS
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.Example:
LOCALE_INDEPENDENT_PATHS = ( r'^/$', r'^/games/', r'^/ajax/', )
LOCALE_INDEPENDENT_MEDIA_URL
(default:True
)- Whether paths starting with
settings.MEDIA_URL
(if it is a path, i.e. not a full URL) are considered to be locale-independent. LOCALE_INDEPENDENT_STATIC_URL
(default:True
)- Whether paths starting with
settings.STATIC_URL
(if it is a path, i.e. not a full URL) are considered to be locale-independent. PREFIX_DEFAULT_LOCALE
(default:True
)- Whether to add the prefix for the default language
(
settings.LANGUAGE_CODE
). For example, ifLANGUAGE_CODE == 'en'
then the path/about/
will be passed to the URL resolver unchanged and/en/about/
will be redirected to/about/
. LOCALEURL_USE_ACCEPT_LANGUAGE
(default:False
)- 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 tosettings.LANGUAGE_CODE
).
LOCALEURL_USE_SESSION
(default: False
)
Whether to check for a user-selected locale in the Django session as a fallback in case no locale is specified in the URL. If
True
, thechange_locale
view will save the chosen locale to the user’s session under thedjango_language
session key. When used and available, the session locale takes precedence over theAccept-Language
header fallback (seeLOCALEURL_USE_ACCEPT_LANGUAGE
above).A localized URL still takes precedence over a locale in the user’s session. Following a localized link such as one generated using the
chlocale
filter won’t switch the session’sdjango_language
; only thechange_locale
view will.To use this feature, sessions must be in use, and
django.contrib.sessions.middleware.SessionMiddleware
must come beforelocaleurl.middleware.LocaleURLMiddleware
insettings.MIDDLEWARE_CLASSES
.
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
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 toFalse
, as the redirect will then be dependent on the user’s Accept-Language header.