XRouting is a simple plugin that handles requests for different contexts in MODX. It automatically switches the context based on a (sub)domain or subfolder. ContextRouter or GatewayManager are similar extras, but neither of them can handle the routing based on domains and folders at the same time. In this tutorial you'll learn how you can setup XRouting for a multilingual website with subfolders for each language.
XRouting is available for free and can be installed through the MODX Package Management or downloaded here.
How XRouting works
XRouting uses context settings for it's routing. That's why you should add at least the http_host, base_url and site_url context settings to each context. To make your multilingual website actually work you should also add context settings like cultureKey, site_start and error_page.
Assuming that you're creating a website that is translated into English, French and German, with a single domain and a subfolder for each language – so the English website would be available under http://company.org/en/. In that case you should leave the default web context and create a new context for each language.
Please make sure that each context contains at least 1 Resource that is set as site_start in the context settings.
At this point your resource tree should look similar to the one in this image.
About the context settings
To understand the context settings you should first make sure to know the anatomy of a URL. The image below shows which part is the protocol, the hostname and the path.
Based on this it's pretty straight forward to set the MODX context settings for XRouting. The http_host setting is just the hostname (Important: when used with XRouting always remove the "www." because it's added automatically). The base_url setting is your base path of your website. For a normal project this would just be single slash. In the case of a multilingual website with subfolders for each language, it's the name of the subfolder. Make sure your base_path settings starts and ends with a slash! The site_url setting in MODX is just the combination of the default protocol, the http_host setting and the base_url setting.
Your context settings for the english context should look similar to those in the image above. Your context settings for your French and German context would be similar, besides that the base_url, site_url and cultureKey should reflect the different language string and your site_start would be the ID of the homepage resource in that context.
One important thing is that all your http_host settings must not include "www."! Otherwise XRouting won't find the correct context when it's comparing the hosts. But no worries, XRouting handels the www subdomain automatically.
If you have already installed XRouting and open your website at http://company.org/en/ you should already see the English homepage.
What you also need
In order to finish your multilingual website you might want to redirect your visitors from the main domain company.org to a specific language version. This could be done by a snippet in the resource in the web context, that automatically redirects the user based on it's browser language or by a simple weblink that is set as the global site_start in the web context and that redirects to the default language.
In order to let visitors switch between languages I recommend the Babel extra, which is just about to reach the 3.0 version. With Babel you can link your translations from the MODX Manager and with a simple snippet in your template you can add the links to the other languages to the front-end. This is how the Babel snippet call could look like:
[[BabelLinks?
&tpl=`babelLanguageTabs`
&showCurrent=`1`
&includeUnlinked=`1`
]]Got issues?
XRouting can be found on Github, where you can also open issues if you have any problems or you can contribute by opening a pull request.