Multilingual Best Practices

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

Main Methods for Implementing Multilingual Content

There are many different ways to implement multilingual content in dotCMS, each of which has advantages and disadvantages depending on your content and workflow. The following are the most common methods of implementing multilingual content:

There is no single best way to implement multilingual content in dotCMS; each of the above methods has been implemented by multiple dotCMS customers, and which method is best for your site will depend on a number of factors, including but not limited to the following:

  • The type and quantity of content you have (and will ultimately need) in each language.
  • The similarities and differences your content has in different languages.
  • How you plan to perform translation of your content.
  • How you plan to deploy and manage your sites.

The following sections discuss each of these methods in more detail.

Single Set of Content, Multiple Language Versions of each Content

All content in dotCMS can be made to be multi-lingual by simply creating a new version of any existing content in a different language. When you create content in a new language, both the original content and the content in the new language can be live (published) at the same time, and dotCMS will automatically select the appropriate language content based on the language selected by the user.

When you implement multilingual content by maintaining all language versions of content on the same dotCMS site and in the same content location,

Default Language Fall-Through Configuration

Single Site, Different Section of the Site for each Language

One common method of handling multilingual content is to create a different top-level folder for each language the site will support.

To implement this method, all Content Types which you wish to create multilingual versions for must include a Host or Folder field. Then, when each content item is created, you must select the appropriate folder for the language you've chosen for the content.

Note that you can not create different versions of the same content in different folders; when you change the value of the Host or Folder field for any content item, it changes the Host or Folder field for all versions of that content, including versions of the content in other languages.

URL Rewrite Rules

Once you have separated content for different languages in different folders, you can display a user content in the appropriate language by directing them to the appropriate top-level folder; for example, content with a URL that begins with /en/ will display the English language version of the content, while content accessed with a URL that begins with /fr/ may display the French language version of the content.

Since there are many different ways a user may select a language preference, you may wish to automatically redirect users to the appropriate

Note that you can also use URL rewrite rules to make it appear as though your multilingual content is in different top-level folders, even if it's actually all in the same location. To do this you can create URL rewrite rules that match the appropriate URL that would match an appropriate top-level language folder (e.g. /en/*), and rewrite the request to set an appropriate header or URL parameter to specify the language of the content to return.


Single dotCMS Instance, Separate Site for each Language

Sharing Content and Linking to Content in the Default Language

Limitation: Single Default Language

The main limitation to having separate dotCMS sites for each language within the same dotCMS instance is that you can only specify one Default Language for each dotCMS instance; so, for example, even if you have separate sites for English and French content, you still can only have one language - either English or French - as the default language for both sites.

If you would like to have a different Default Language for each site, you may wish to consider having each language site on it's own dotCMS instance, since this would allow you to set the default language for each site separately.

Separate dotCMS Instance for each Language

Default Language Configuration

Limitation: Sharing Content Among Sites

Planning for Future Translations

If currently you have a main site in a single language, but plan to translate and provide your content in another language in the future, it is helpful to understand that each of the above methods

One of the main advantages of having content in all languages on a single dotCMS site is that it allows you to translate “as-you-go”. You can configure your site so that if content does not exist in the language the user prefers, the version of content in the default language can be displayed instead. This allows you to build and display your content in your default language, and translate content over time.

As a contrast, if you have multiple sites on the same dotCMS instance (each displaying a different language), or different dotCMS sites for each language, these separate sites must contain all content before you can launch the site and provide your content in a different language. The advantage of these approaches, however, is that it is easier to test and validate your content in different languages if it is not displayed in

MethodFall-through to
Default Language
Default to
Local Language
Same Content, Multiple Language VersionsYesYesPossible**Highest
Single Site, Multiple Language SectionsPossible*Possible*Possible**Normal
Single dotCMS Instance, Separate Site for each LanguagePossible*Possible*Possible**Higher
Separate dotCMS Instance for each LanguageN/ANo***YesNormal

* = Requires copying the original content to the new section or site, then translating it in-place. ** = Can be implemented with custom Velocity coding. *** = Once a site is moved to another instance, new content on the original site must be manually copied to the new site to be available.

These methods are listed in order from the simplest and most straight-forward to the more sophisticated. Therefore, if you are not sure how you wish to implement multilingual content on your site, we recommend that you start with the first method and build to the other methods as needed:

  • Begin by building your site in a single language, and then translating portions of your content as needed.
  • Later, if you find the need for greater separation of your content, you can copy the content to another section of your site or another site within the same dotCMS instance.
  • Still later, if you have the need to set up separate language sites with their own default languages, you can move those sites to separate dotCMS instances.

On this page


We Dig Feedback

Selected excerpt: