Multilingual Websites with MODx and Babel

In the official documentation of the Babel Extra I’ve only provided a short summary of how to setup your MODx contexts for a multilingual website and referred to an outdated tutorial. Many Babel users contacted me or posted an issue on GitHub because they had some troubles with Babel. Most of these troubles were not related to Babel itself but have been caused by setting up the contexts incorrectly. With this small tutorial I want to support you in configuring your multilingual websites with MODx and Babel.

Important: I've described a more SEO-friendly approach in a new article which you may want to read, too.

First of all I want to thank digital butter for their great tutorial which explains how to setup a multilingual website with MODx. I referred to their tutorial in the official documentation. However, since there have been made some changes to the access control system of MODx you have to apply some more steps to setup your multilingual website correctly.

In this article I’ll simply list all the steps necessary to setup your multilingual site in a very basic way. I won’t provide as much details as the guys from digital butter did. There are already some helpful resources available on the web where you can obtain additional information:

Step by Step Instructions

Ok. If you have worked through the documents listed above and installed a new clean MODx environment you should be ready to setup your multilingual website.

I’ll go through all the necessary steps by configuring an example website which will be available in three languages: English, German and French. The English site will be available via the German site via and the French one via

  1. Create your contexts for each language:
    The default web context will be used for the English site, a de context for the German and a fr for the French site:
    create a context for each language
  2. Configure language specific settings of all your contexts: site_url and cultureKey.
    • web context: site_url:, cultureKey: en
    • de context: site_url:, cultureKey: de
    • fr context: site_url: cultureKey: fr
    create language specific settings for each context
  3. Grant the "Load Only" access policy for all your contexts to the anonymous group to let your users load the contexts:
    grant access to contexts
  4. Create a gateway plugin which listens to the "OnHandleRequest" event to load the context and set the correct cultureKey:
    if($modx->context->get('key') != "mgr"){
    	//grab the current domain from the http_host option
    	switch ($modx->getOption('http_host')) {
    		case '':
    			//switch the context
    			//set the cultureKey
    			$modx->setOption('cultureKey', 'de');
    		case '':
    			$modx->setOption('cultureKey', 'fr');
    			// Set the default language/context here
    			$modx->setOption('cultureKey', 'en');
  5. Install the Babel Extra via package management.

Now you should be able to create documents and link translations via Babel in your MODx manager. For information about how to use the MODx lexicon feauture you may take a look at the tutorial at digital butter or official documentation.

Common Mistakes

In order to avoid mistakes during setting up your contexts here are some common mistakes which have been made by users who requested my help:

Babel does not display the correct language of a context

You may have forgotten to configure the cultureKey setting in the specific context. Babel uses this setting to determine the language of a context.

Babel does not display all links to translated documents in the front-end

You may have forgotten to grant the "Load Only" access policy for your visitors to the specific contexts. Or you may have forgotten to flush the permissions.

The site is always displayed in the same language

Check your gateway plugin and make sure it works properly. When using the code from above be sure that the http_host setting is not set in your context settings. Otherwise your gateway plugin won’t be able to determine the requestested URL.

Further Help

Important: I've described a more SEO-friendly approach in a new article which you may want to read, too.

If you’re still having problem regarding your multilingual site and Babel have a look at the closed issues on GitHub. If you can’t find a solution there, feel free to post a new issue. We try to help you and incorporate your feedback to improve Babel.