Multi-Site Language Configuration

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 Session's Language

There are two recommended methods to modify the page or content language of a given user session:

• The use of rules provides the highest degree of granularity and control; using rules can permit the adjustment of language version on the basis of a variety of conditions — including the user's browser language, country, etc.
• The use of vanity URL is a simple way to adjust a URI to include appropriate paths or parameters to control the active language version.

In either case, the mere addition of the language_id parameter to the URL suffices to select a language for the page.

Note that language versions are determined and loaded before a given page is rendered. As such, session parameters set via Velocity code are not able to alter the language version.

Rewriting URLs by Filter

In addition to the above methods, it's also possible to set a language by defining URLRewrite behaviors with the built-in UrlRewriteFilter.

For example, the following rewrite specification sets 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 definition 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 filters, 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.

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.