Site Translations

Below is a description of how the site is translated and how those translations are managed for both existing languages and adding new ones.

Architecture Overview

To translated the site into multiple languages, multiple copies of the site are created and managed using the existing mutli-tenancy features in Mezzanine:

Pages are considered to be the same on each site if they have the same slug/URL.


Pages in locale’s other than english must have the same slug. That is the existing URLs (/learn/, /market/, etc) on the front end are the same across sites. The slug sets up the relationship between pages on different locales. If there is a page specific to a locale that does not appear in english, it does not need to share the slug.

The site/language to used is detected by the browser’s Accept-Language header or the django_language cookie which can be set using the language selection in the site footer. The admin also uses localized URLs to detect the current site/language. See the Django documentation for a more verbose description of this detection process

For Admins/Developers

The set of available languages is determined by the LANGUAGES setting but simply adding a new language here is not sufficient for creating a new language version. As previously noted, each language will have its own Site record from django.contrib.sites and corresponding CMS content for that site. When a new language needs to be added, a new site record and a copy of the current CMS content needs to be made. This is handled via the build_language_sites management command:

python build_language_sites <language-code>
# Adding French (fr)
python build_language_sites fr
# Adding all languages defined in the LANGUAGES setting
python build_language_sites --all

By default this will copy all of the CMS content (Pages, Forms, Links) from the English site for any new site which is created. This can be skipped via the --skip-content option. However, this is not recommended because there is currently nothing in place to copy content for an existing site. When testing/developing locally you can easily reset the site content for a non-default language by deleting the site in the admin which will cascade to delete all of the CMS content. Re-running the management command will create a fresh copy for the language.

For non-superusers, Mezzanine has a concept of site permissions. That is users can be staff for one or more sites. Since languages are handled as separate sites it is possible to restrict users to only a single language/site admin. However, if translators don’t have access to the English version of the site they won’t be able to view the original content for making translation updates. Care should be taken to ensure that content authors have sufficient site permissions for their translations. Site permissions can be managed in the User admin.

The language switching is enabled/disabled via a django-waffle flag. This flag can be created on the command line via:

python flag language-switching --staff --create

By default this flag will be disabled unless the flag is created. That can be configured with the WAFFLE_FLAG_DEFAULT setting. For more information on managing feature flags, see the django-waffle documentation

For Translators

When logging into the admin you can select the language you would like to see. Once in the admin you can change this language at any time using the selector in the upper right-hand corner. When content is updated on the English version of the site, TODO items will be created under the “Translations” header. This will give a brief description of what was updated so that the translated content can be updated. When viewing a translated page (non-English site version), there will be a link on the upper right-hand side to open a popup window with the English version to aid the translation.

Non CMS Translations

Non CMS content (text marked for translation in code and templates) is translateable via Rosetta