How to serve multiple languages¶

If you used django CMS quickstart to start your project, you’ll find that it’s already set up for serving multilingual content. Our installation guide also does the same.

This guide specifically describes the steps required to enable multilingual support, in case you need to it manually.

Multilingual URLs¶

If you use more than one language, django CMS urls, including the admin URLS, need to be referenced via i18n_patterns(). For more information about this see the official Django documentation on the subject.

Here’s a full example of urls.py:

fromdjango.conf.urls.i18nimport i18n_patterns
fromdjango.contribimport admin
fromdjango.contrib.staticfiles.urlsimport staticfiles_urlpatterns
fromdjango.urlsimport include, path
fromdjango.views.i18nimport JavaScriptCatalog
admin.autodiscover()
urlpatterns = i18n_patterns(
 re_path('jsi18n/', JavaScriptCatalog.as_view(), name='javascript-catalog'),
)
urlpatterns += staticfiles_urlpatterns()
# note the django CMS URLs included via i18n_patterns
urlpatterns += i18n_patterns(
 path('admin/', include(admin.site.urls)),
 path('', include('cms.urls')),
)

Monolingual URLs¶

Of course, if you want only monolingual URLs, without a language code, simply don’t use i18n_patterns():

urlpatterns += [
 path('admin', admin.site.urls),
 path('', include('cms.urls')),
]

Store the user’s language preference¶

The user’s preferred language is maintained through a browsing session. So that django CMS remembers the user’s preference in subsequent sessions, it must be stored in a cookie. To enable this, cms.middleware.language.LanguageCookieMiddleware must be added to the project’s MIDDLEWARE setting.

See How django CMS determines which language to serve for more information about how this works.

Working in templates¶

Display a language chooser in the page¶

The 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:

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

If you are in an apphook and have a detail view of an object you can set an object to the toolbar in your view. The cms will call get_absolute_url in the corresponding language for the language chooser:

Example:

class AnswerView(DetailView):
 def get(self, *args, **kwargs):
 self.object = self.get_object()
 if hasattr(self.request, 'toolbar'):
 self.request.toolbar.set_object(self.object)
 response = super().get(*args, **kwargs)
 return response

With this you can more easily control what url will be returned on the language chooser.

Note

If you have a multilingual objects be sure that you return the right url if you don’t have a translation for this language in get_absolute_url

Get the URL of the current page for a different language¶

The page_language_url returns the URL of the current page in another language.

Example:

{% page_language_url "de" %}

Configuring language-handling behaviour¶

CMS_LANGUAGES describes the all options available for determining how django CMS serves content across multiple languages.

You can override django-cms’s language resolution by setting request.LANGUAGE_CODE in your own middleware. Common use cases include:

Serving different languages based on domains (e.g., example.com → English, example.de → German):

classDomainLanguageMiddleware:
 def__init__(self, get_response):
 self.get_response = get_response
 def__call__(self, request):
 host = request.get_host().split(':')[0]
 if host.endswith('.de'):
 request.LANGUAGE_CODE = 'de'
 elif host.endswith('.fr'):
 request.LANGUAGE_CODE = 'fr'
 return self.get_response(request)

Setting language based on user preferences or geolocation
Implementing custom language negotiation logic

You can customize the default language for each site using the CMS_LANGUAGES setting.