Multi-Site Language Configuration

Last Updated: Aug 12, 2019
documentation for the dotCMS Content Management System

By default, dotCMS makes all language versions of pages and content available to all sites in a multi-site environment, and supports a single default language for all your sites. However you may wish to perform more sophisticated handling of languages, such as changing the display language depending on which site the user visits.

There are many ways to accomplish this type of functionality, and what methods you use will depend on your particular goals and requirements. The following methods can help you create the behavior you want for your site.

Changing the Language for the Session

Within a page, you can change the language for the user's session to a particular language by setting the `com.dotmarketing.htmlpage.language' property, as in the following example:

$request.getSession().setAttribute('com.dotmarketing.htmlpage.language',${DisplayLang})

Selecting the Language Based on the Page or Site

Once your pages are designed to be able to change the language in the user session, you can choose the language to display using the following methods.

Setting the Language in the URL

You can add a parameter to the URL to select a language to display the page in, as in the example code below. Note that this method must be combined with additional code to select the content of the appropriate language.

#if($UtilMethods.isSet($request.getParameter('DisplayLang')))
   #set($DisplayLang = $request.getParameter('DisplayLang'))
#end

Setting the Language Based on the Server Name or Domain

You may automatically select the display language based on the server name or domain using code similar to the following:

#if($request.getServerName().contains('.es'))
  #set($DisplayLang = '2')
#elseif($request.getServerName().contains('.fr')
  #set($DisplayLang = '3')
#end

Rewrite Rules

In addition to setting the language using Velocity parameters, it's also possible to set a language using URLRewrite rules with the built in UrlRewriteFilter.

For example, the following rewrite rules to set the language based on the path in the URL used to access pages in the products folder of the site:

<rule>
    <from>/products/(.*)$</from>
    <set name="com.dotmarketing.htmlpage.language">1</set>
    <set type="session" name="com.dotmarketing.htmlpage.language">1</set>
    <set name="CMS_FILTER_URLMAP_OVERRIDE">/products/$1</set>
</rule>
<rule>
    <from>/en/products/(.*)$</from>
    <set name="com.dotmarketing.htmlpage.language">1</set>
    <set type="session" name="com.dotmarketing.htmlpage.language">1</set>
    <set name="CMS_FILTER_URLMAP_OVERRIDE">/products/$1</set>
</rule>
<rule>
    <from>/es/products/(.*)$</from>
    <set name="com.dotmarketing.htmlpage.language">2</set>
    <set type="session" name="com.dotmarketing.htmlpage.language">2</set>
    <set name="CMS_FILTER_URLMAP_OVERRIDE">/products/$1</set>
</rule>

The following rules provide a more general solution, rewriting all pages in the site based on a language specified in the URL path:

<rule>
    <from>/es/(.*)$</from>
    <set name="com.dotmarketing.htmlpage.language">2</set>
    <set type="session" name="com.dotmarketing.htmlpage.language">2</set>
    <set name="CMS_FILTER_URLMAP_OVERRIDE">/$1</set>
</rule>
<rule>
    <from>/en/(.*)$</from>
    <set name="com.dotmarketing.htmlpage.language">1</set>
    <set type="session" name="com.dotmarketing.htmlpage.language">1</set>
    <set name="CMS_FILTER_URLMAP_OVERRIDE">/$1</set>
</rule>

Note: When using rewrite rules, links to folders without a trailing slash (e.g. /about-us) will be rewritten with a trailing slash (e.g. /about-us/). This doesn't have a practical effect on which page is displayed to the user (the index page in the folder will be displayed with or without the trailing slash), but will slightly modify the URL displayed in the user's browser.

For more information on how to select the language using rewrite rules, see the Set Language by Site or Folder topic in the dotCMS Codeshare, and the URL Rewrite Rules documentation.

Additional Helpful Tools

Here are a number of additional methods you may find useful when managing a multi-site, multilingual environment.

Finding the Language Code and Country Code

You can find the language and country code of your content with Velocity code similar to the following:

#set($CurrentLanguage  = $text.getLanguage(${currentLang}))
#set($LanguageCode     = $CurrentLanguage.getLanguageCode())
#set($CountryCode      = $CurrentLanguage.getCountryCode())

Querying Content in a Single Language Across Different Country Codes

In some cases, you may want a single search to pull content from multiple languages; for example, if you have English content on sites in the United States, Australia, and United Kingdom, you may want an English search to query content across all of these sites. To do this, you can add a query term specifying multiple language ids, similar to the following:

+languageId:(1 || 4 || 5)

Note that if you are setting the language using one of the methods above, you should always explicitly specify the language in all your queries, to ensure you're pulling the correct content for the selected language.

Host-Specific Language Variables

Language Variables in the core dotCMS release are non host-specific; when you define a Language Variable, it applies to all hosts. To create host-specific Language Variables, consider the Language Variable plugin from GeekyPlugins.com.

On this page

×

We Dig Feedback

Selected excerpt:

×