1. Patrick Samson
  2. django-robot-locale

Source

django-robot-locale / docs / quickstart.rst

Quick start guide

Requisites and dependances

Python version >= 2.6

Reasons :

  • use of str.format()

Installation

Get the code from the repository, which is hosted at Bitbucket.

You have two main ways to obtain the latest code and documentation:

With the version control software Mercurial installed, get a local copy by typing:

hg clone http://bitbucket.org/psam/django-robot-locale/

Or download a copy of the package, which is available in several compressed formats, either from the Download tab or from the get source menu option.

In both case, make sure the directory is accessible from the Python import path.

Configuration

Add robot_locale to the INSTALLED_APPS setting of your project.

Add robot_locale.middleware.RobotLocaleMiddleware to the MIDDLEWARE_CLASSES setting of your project.

Caution: Order is important.

Make sure you place the RobotLocaleMiddleware after the django.middleware.locale.LocaleMiddleware if you use it. This is needed because the Django's middleware will act as a usual default setter and the RobotLocaleMiddleware, if necessary, will supersede the language setting.

There is no need to run a manage.py syncdb, since this application has no model.

Optional settings

You may specify some additional configuration options in your settings.py:

ROBOT_LOCALE_LANGUAGES

The list of language codes to be considered by the application.

Defaults to: settings.LANGUAGE_CODE + any language code available under the locale/ directory of the project.

ROBOT_LOCALE_SETLANG_ENDS

A suffix as a string or a tuple of suffixes. When a POST to a URL ending with such a suffix returns a redirect response, the possible language prefix will be erased from the location.

Defaults to: /setlang/, the pattern in django.conf.urls.i18n

ROBOT_LOCALE_EXCLUDES

Declaration of some URLs that will remain untouched.

Reduced syntax: If the value is not a dictionary, it will be considered as the exact entry of the dictionary of the full syntax.

Full syntax: A dictionary with two keys:

  • exact for an exact match
  • start for matching the start of the URL

Each value may be a string or an iterable of strings.

Examples:
'/'
('/', '/unique/')
{ 'start': '/someapp' }
{ 'exact': '/', 'start': ['/someprefix', '/someapp'] }

Defaults to: no exclusion.

For example, with '/', if a request to /en/somepage/ returns in its content <a href="/">Home</a>, it will not be converted to href="/en/", but preserved as href="/". So the further navigation will revert to the normal usual language detection, if any.

Usage

You have to give to robots an entry point as a localized URL for each target language. One point should be enough, it's up to the robot to explore the whole site further. There is no need to make the links available to the user. For human browsing, the set_language redirect view is more appropriate.

For example, put something like this somewhere in the root page of the site:

<div style="display: none">
{% for lang in LANGUAGES %}
<a href="/{{ lang.0 }}/">{% trans lang.1 %}</a>
{% endfor %}
</div>
Tip:

Suppose your visitor came on your site by following a localized URL obtained from a search engine. It may not be his favorite language, so it would be nice to offer the opportunity to escape from this never ending enforced language. There are two ways:

  • Make use of the set_language redirect view. But it may be inappropriate, or even too intrusive, to change some pages.
  • Define some neutral links, i.e. links leading to non-localized URLs. The top home page is a good candidate of that purpose. This goal is achieved with the ROBOT_LOCALE_EXCLUDES setting.

Sample

settings.py:

LANGUAGE_CODE = 'en'
gettext = lambda s: s
LANGUAGES = (
    ('en', gettext('English')),
    ('fr', gettext('French')),
)
MIDDLEWARE_CLASSES = (
    ...
    'django.middleware.locale.LocaleMiddleware',
    'robot_locale.middleware.RobotLocaleMiddleware',
    ...
)
INSTALLED_APPS = (
    ...
    'robot_locale',
    ...
)
ROBOT_LOCALE_EXCLUDES = '/' # allows a way to step out from the prefix loop

With this file system context:

mysite/
 |_ locale/
     |_ fr/
         |_ LC_MESSAGES/
             |_ django.mo

The considered language prefixes in URLs will be: /en and /fr, the same as with this optional setting:

ROBOT_LOCALE_LANGUAGES = ('en', 'fr')