####################
Internationalization
####################


*****************
Multilingual URLs
*****************

If you use more than one language, django CMS urls need
to be referenced via :func:`~django.conf.urls.i18n.i18n_patterns`. For more information about this see the
official django `documentation`_.

Main `urls.py` example::

    from django.conf import settings
    from django.conf.urls.defaults import patterns, include, url
    from django.contrib import admin
    from django.conf.urls.i18n import i18n_patterns
    from django.contrib.staticfiles.urls import staticfiles_urlpatterns

    admin.autodiscover()

    urlpatterns = patterns('',
        url(r'^jsi18n/(?P<packages>\S+?)/$', 'django.views.i18n.javascript_catalog'),
    )

    urlpatterns += staticfiles_urlpatterns()

    urlpatterns += i18n_patterns('',
        url(r'^admin/', include(admin.site.urls)),
        url(r'^', include('cms.urls')), # <--------- include the django cms urls via i18n_patterns
    )


.. _documentation: https://docs.djangoproject.com/en/dev/topics/i18n/translation/#internationalization-in-url-patterns

***************
Language Cookie
***************

By default if someone visits a page at `http://www.mysite.fr/` django determines the language as follow:

- language in url
- language in session
- language in cookie
- language in from browser
- LANGUAGE_CODE from settings

No if i have a German browser and visit a page that is only English and French, it will choose the language that is
in LANGUAGE_CODE. If this is English but i only speak French i have to switch the language. No if after sometime
i visit the page again. The page will display in English again and I have to switch again. The same is for every
link that points to `/` will switch to English again. To fix this behavior the cms ships with a middleware:

    `cms.middleware.language.LanguageCookieMiddleware`

add this to you middleware settings fix this.

****************
Language Chooser
****************

The :ttag:`language_chooser` template tag will display a language chooser for the
current page. You can modify the template in ``menu/language_chooser.html`` or
provide your own template if necessary.

Example:

.. code-block:: html+django

    {% load menu_tags %}
    {% language_chooser "myapp/language_chooser.html" %}


*****************
page_language_url
*****************

This template tag returns the URL of the current page in another language.

Example:

.. code-block:: html+django

    {% page_language_url "de" %}


******************
hide_unstranslated
******************

If you add a default directive to your :setting:`CMS_LANGUAGES` with a :setting:`hide_unstranslated` to ``False``
all pages will be displayed in all languages even if they are
not translated yet.

If `hide_untranslated`  is ``True`` in your :setting:`CMS_LANGUAGES`
and you are on a page that doesn't yet have an English translation and you view
the German version then the language chooser will redirect to ``/``. The same
goes for urls that are not handled by the cms and display a language chooser.

********************************************
Automated slug generation unicode characters
********************************************

If your site has languages which use non-ASCII character sets, you might want
to enable :setting:`CMS_UNIHANDECODE_HOST` and :setting:`CMS_UNIHANDECODE_VERSION`
to get automated slugs for those languages too.