MODX Multilingual - Setting up Babel and have a website with multiple languages

Posted on Dec 28, 2011 by Menno Pietersen

Video Tutorial: Basic MODx template setup image

In this tutorial I will show you how to setup a multilingual MODX Revolution website using the exellent Babel package.



Creating a Multilingual website

It can be very tricky to create a Multilingual website no matter wich framework or CMS you use. As always doing it in MODX is not that difficult.

Our goal: We want one website with three supported languages and a nice, SEO friendly, URL for each language

  • English - http://your-website-url.com
  • Dutch http://your-website-url.com/nl/
  • German - http://your-website-url.com/de/

These websites will be very easy to manage from within one MODX manager and creating/managing translations of pages should be a breeze.


What you need

For this tutorial you will need:

  • MODX Revolution (2.1 or higher) installed
  • Access to your root folder (.htaccess or ht.access file)
  • Babel 2.2.4-pl package, get it here or you can get it from within the MODX Manager

Usefull links:


Step #1 - Setting up .htaccess

In the root of your website you will find a ht.acces file, create a backup, open it in a text-editor and rename it to .htaccess

In your .htaccess file, check that the 'RewriteBase' line is correct. If your website is installed ion the root of your domain use:

				RewriteEngine On
						RewriteBase /
					

If your website is installed in a sub-folder Use:

				RewriteEngine On
						RewriteBase /your-sub-folder/
					

Make sure you are rewriting the url under # Rewrite www.domain.com -> domain.com -- used with SEO Strict URLs plugin. Use:

				# Rewrite www.domain.com -> domain.com -- used with SEO Strict URLs plugin
						RewriteCond %{HTTP_HOST} .
						RewriteCond %{HTTP_HOST} !^your-website-url\.com [NC]
						RewriteRule (.*) http://your-website-url.com/$1 [R=301,L]
					

Next add to you .htaccess file (just below # The Friendly URLs part, replace the existing code of the Friendly URLs) the following:

				
						# redirect all requests to /de/favicon.ico and /nl/favicon.ico
						# to /favicon.ico
						RewriteCond %{REQUEST_FILENAME} !-d
						RewriteCond %{REQUEST_FILENAME} !-f
						RewriteRule ^(en|nl|de)/favicon.ico$ favicon.ico [L,QSA]
						  
						# redirect all requests to /de/assets* and /nl/assets* to /assets*
						RewriteCond %{REQUEST_FILENAME} !-d
						RewriteCond %{REQUEST_FILENAME} !-f
						RewriteRule ^(en|nl|de)/assets(.*)$ assets$2 [L,QSA]
						 
						# redirect all other requests to /de/* and /nl/*
						# to index.php and set the cultureKey parameter
						RewriteCond %{REQUEST_FILENAME} !-f
						RewriteCond %{REQUEST_FILENAME} !-d
						RewriteRule ^(en|nl|de)?/?(.*)$ index.php?cultureKey=$1&q=$2 [L,QSA]
					

Don't forget to change the your-website-url in the domain rewrite rule!

In this example I have three languages, Dutch (nl), German (de) and the default English (web). If you have other/different languages make sure you change the language codes (de|nl) accordingly. Example for Spanish, German, French and English (default): (sp|du|fr)

Now you can upload your .htaccess file to your website root. (remove any old ht.access file you might find)


Step #2 - Creating your contexts

In the MODX Manager you will need to create a context for each of you languages.

Go to: System > Contexts and click on Create New.

Under Context Key enter the name of your language, I used Nederlands for Dutch and Deutsch for German.

Next right-click on your new context and select Update context. Click on the Context settings tab and click on Add new.

For each of your languages you will need to add four settings.

Add to the default 'web' context:

For the Web context I added:

Lexicon name: web (is already default)
Base URL
  • Key: base_url
  • Name: Base URL
  • Area Lexicon Entry: language
  • Value: /
Culture key
  • Key: cultureKey
  • Name: Culture key
  • Area Lexicon Entry: language
  • Value: en
Site start
  • Key: site_start
  • Name: Site start
  • Area Lexicon Entry: language
  • Value: 1
Site URL
  • Key: site_url
  • Name: Site URL
  • Area Lexicon Entry: language
  • Value: http://your-website-url.com/

Add the Dutch 'Nederlands' context:

Lexicon name: Nederlands
Base URL
  • Key: base_url
  • Name: Base URL
  • Area Lexicon Entry: language
  • Value: /nl/
Culture key
  • Key: cultureKey
  • Name: Culture key
  • Area Lexicon Entry: language
  • Value: nl
Site start
  • Key: site_start
  • Name: Site start
  • Area Lexicon Entry: language
  • Value: 'the ID of the language homepage' (we will update this later)
Site URL
  • Key: site_url
  • Name: Site URL
  • Area Lexicon Entry: language
  • Value: http://your-website-url.com/nl/

Add the German 'Deutsch' context:

Lexicon name: Deutsch
Base URL
  • Key: base_url
  • Name: Base URL
  • Area Lexicon Entry: language
  • Value: /de/
Culture key
  • Key: cultureKey
  • Name: Culture key
  • Area Lexicon Entry: language
  • Value: de
Site start
  • Key: site_start
  • Name: Site start
  • Area Lexicon Entry: language
  • Value: 'the ID of the language homepage' (we will update this later)
Site URL
  • Key: site_url
  • Name: Site URL
  • Area Lexicon Entry: language
  • Value: http://your-website-url.com/de/

If you need more languages you can repeat the process.


Step #3 - Creating a 'gateway' plugin

We will need to create a basic plugin to assign the correct context.

In the MODX Manager go to Elements and click on the New Plugin icon.

Name the plugin gateway and add the following Plugin code (change the names and contect titles if you have other languages):

				<?php
							if($modx->context->get('key') != "mgr"){
								/* grab the current langauge from the cultureKey request var */
								switch ($_REQUEST['cultureKey']) {
									case 'nl':
										/* switch the context */
										$modx->switchContext('Nederlands');
										break;
									case 'de':
										/* switch the context */
										$modx->switchContext('Deutsch');
										break;
									default:
										/* Set the default context here */
										$modx->switchContext('web');
										break;
								}
								/* unset GET var to avoid
								 * appending cultureKey=xy to URLs by other components */
								unset($_GET['cultureKey']);
							}
						?>
					

This gateway plugin will need to be activated by a OnHandleRequest, to do this go to the System Events tab, scroll down to the OnHandleRequest line and enable this.

Save the gateway plugin.


Step #4 - Installing Babel

Almost there! We now can install the Babel package.

In the MODX Manager go to System > Package Management click on Download Extras and search for babel. Once found, download the Babel package and click Finish.

Now we can install Babel, click on Install and a flighbox will pop up. Click I Agree and Next twice till you get to the Setup Options. Here you should see your contexts already filled in under Context Keys (comma-separated): if not, please add them now. (mine are: web,Deutsch,Nederlands)

Leave the other settings default.


Step #5 - Creating Multilingual content

Finally we need some links to change the language. Babel has a easy solution for this: BabelLinks.

Just add the following code to your template where you want the language switch to appear:

<ul>[[BabelLinks]]</ul>

We should be all done!

Go to the Resources tab, you should see all your contexts listed under the main 'web' context.

If you click on a resource under 'web', you will see a new options on top for each of your languages. Simply mouseover the language to add a translated version of this page!


Step #6 - All done!

Hope this helped, good luck with your Multilingual MODX Revolution website.