Multilingual Site Considerations and Set Up

Last Updated: Dec 8, 2021
documentation for the dotCMS Content Management System

There are a number of different ways to implement multilingual content, and the earlier you plan your multilingual implementation, the easier it will be to manage the translation and transition.

There are four basic approaches to provide multilingual content:

ApproachDescription
Translate contentHave a single site and content, and translate pages and content into each supported language. dotCMS will automatically serve the appropriate language version of content to the user, based on their language preference.
Translate sections of a single siteCreate separate folders within dotCMS for each language, and create content for each supported language within the appropriate language folder.
Create separate sites for each languageWithin a single dotCMS instance, create separate sites for each supported language.
Separate dotCMS instances for each languageRun separate instances of dotCMS for each supported language.

Each of these approaches has advantages and limitations.

Translated content

The simplest way to support multilingual content is to create a single site and common content for that site, and then translate this common content into each new language you wish to support. This allows you to create your site and content in the default language, and then translate content at whatever pace you want, to make the content available in other languages.

When a user accesses content, by default dotCMS will attempt to deliver a version of that content in the user's preferred language. If a version of the content doesn't exist in the preferred language, dotCMS may display the default language version of that content instead (based on your Default Language Fall-through settings).

If you expect to have content which is the same (but just translated) in each language, this is both the simplest and the recommended approach. However this approach doesn't work as well if you expect to have a large amount of content which is not just translated, but actually different for each of your supported languages.

Translated sections of a single site

If you expect to have different content in each language (rather than just direct translations of the same content), you can create separate sections of a single site which contains the content for each different language. Typically this is done by creating separate top-level folders within the site, but this can also be done by having separate Content Types and other objects (Themes, Templates, etc.).

Notes:

  • If you expect to have content which is directly translated in different languages, this approach may not work as well, since it requires you to create separate content for each content item.
  • You can also simulate this approach using redirects.
    • If you create a single site and content architecture (see above), you can use redirects to make it appear that you have different sections of your site.
    • For example, you could create a single page named /page-name, translate it into Spanish, and then use Vanity URLs to translate URLs referencing /es-sp/page-name to /page-name?language_id=2.
    • This allows you to manage your content and translations in a simple manner, but also provide simple paths which specify the language.

Language Configuration Options

The following language properties can be configured via static configuration plugin, to change the behavior of the following multilingual features:

Default Backend Language

By default, the back-end interface is set to English, however, the following properties can be changed via plugin to change the default language to any of the other supported language versions:

#### LANGUAGE AND CODING INFO
CHARSET = text/html;charset=UTF-8
DEFAULT_LANGUAGE_COUNTRY = United States
DEFAULT_LANGUAGE = en_US
DEFAULT_LANGUAGE_CODE = en
DEFAULT_LANGUAGE_STR = English
DEFAULT_LANGUAGE_COUNTRY_CODE = US

Currently supported languages include: English, Spanish, Italian, French, German, Chinese, Dutch, Russian, Finnish

Language Fall-thru Options

dotCMS provides “fall-thru” options for certain types of dotCMS content/objects. If the content/object does not exist in the current language being used to browse the site, then dotCMS can be configured to display the default language version of the object instead of displaying nothing. See the System Language Properties and Default Language Fall-thru Configuration documentation for more information.

The following multilingual documentation links have been arranged both by order of importance and follow a logically sequential order in which they should be read to properly plan and implement multilingual sites.

Planning Your Language Configuration

There are many different ways to configure dotCMS to handle multilingual content and multilingual sites. Each method has advantages and disadvantages depending on how you plan to create and manage your multilingual content, especially in relation to how easy it is to share content among different languages.

Common Multilingal Configurations

The following are the most common ways customers set up dotCMS to serve multiple different language versions.

MethodCharacteristicsSeparates Languages by
Content Versioning
(Default)
  • A single Site and folder structure is used for all content.
  • Different language versions of each content are created as translations are available.
    • Different language versions of the same content use the same URL.
    • The appropriate language version of content is displayed automatically.
  • Content Versions
Content Versioning
with URL Rewriting
  • A single Site and folder structure is used for all content.
  • Different language versions of each content are created as translations are available.
    • Different language versions of the same content use the same URL.
    • The appropriate language version of content is displayed automatically.
  • URLs are rewritten to make it appear to users that there are different URL paths for each language.
    • Vanity URLs and Rules can be used to identify and remember the user's choice of language.
  • Content Versions
  • URL Paths
Folder Separation
  • A single Site is used for all content.
  • Each language version is contained in a separate folder.
    • Each language folder may have different subfolders and Permissions.
  • A separate content item must be created for each language.
  • Content which is intended to be shared must be explicitly selected or queried for.
  • Folders
Site Separation
  • Each language is contained in a separate Site in the same dotCMS instance.
    • Each language Site may have different folder structures, display elements, and Permissions.
  • A separate content item must be created for each language.
  • Content which is intended to be shared must be explicitly selected or queried for.
    • Content which is intended to be shared must be accessed from a different Site, or stored on the System Host.
  • Sites

Advantages and Disadvantages

The following summarizes some of the advantages and disadvantages of using each of these methods to manage multilingual sites:

MethodAdvantagesDisadvantagesFall-
Through
Effort to
Share
Effort to
Manage
Content Versioning
  • Allows you to translate content slowly, and display untranslated content for content which has not yet been translated.
  • Limited control over what untranslated content is available in each language.
  • Not clear from the URL which language you're viewing.
  • Taxonomies can not be separated per Language.
YesMinimalMinimal
Content Versioning
with URL Rewriting
  • Allows you to translate content slowly, and display untranslated content for content which has not yet been translated.
  • The URL indicates the language being viewed.
  • Rules can be used to automatically set the language from the URL.
  • Limited control over what untranslated content is available in each language.
  • Taxonomies can not be separated per Language.
YesMinimalLow
Folder Separation
  • Full control over what content is available in each language.
  • The URL indicates the language being viewed.
  • Rules can be used to automatically set the language from the URL.
  • Permissions can be different for each language.
  • Low risk of accidental content sharing.
  • Requires explicit copying of each content to each language.
  • Requires explicit references to shared and untranslated content.
  • Requires careful management of shared resources (e.g. Templates, Containers, Widgets).
  • Taxonomies can not be separated per Language.
NoModerateModerate
Site Separation
  • Full control over what content is available in each language.
  • The URL indicates the language being viewed.
  • Rules can be used to automatically set the language from the URL.
  • Permissions can be different for each language.
  • Easy to create completely different look and feel for each language.
  • No risk of accidental content sharing.
  • Taxonomies can be either shared or separated per Language.
  • Requires explicit copying of each content to each language.
  • Requires explicit references to shared and untranslated content.
NoSignificantHigh

On this page

×

We Dig Feedback

Selected excerpt:

×