Implementing multilingual sites using dotCMS

Aug 03, 2012

As 2008 was coming to a close we were contracted by Aquent, one of the largest global talent agencies for creative staffing to implement their new website(s) using Dotcms. Although excited by this opportunity, we knew there would be hurdles implementing an easily manageable and maintainable deployment. With those hurdles behind us, the new Aquent website is delivered in 42 languages, some of them the same but localized for different countries.

Some of the challenges were:

  • Importing multi-lingual content.
  • Managing language property files through webdav.
  • Making sure templates would render UTF-8 characters properly
  • Allowing Dotcms to have a default language.

We're currently working with an online gambling website to help them develop their new websites in Dotcms in 22 different languages.

More than any aspect of implementation, defining all multi-lingual requirements first thing in the process is well worth the effort. This will save you a lot of time and headaches down the road. Some examples of things to consider are:

  • Which images will be translated on the site and which images will stay the same no matter regardless of the selected language.
  • What text will be translated. Tip: For all labels and links, we recommend using language property files.
  • Should the site have a default language?
  • Which languages will be used on the website?
  • How will the site's URL structure identify language, if applicable?

As a direct result of implementing these multi-lingual projects, we have started developing a plugin that will include the following features:

  • A macro to create list of languages defined for your website, you will need this list to show to your users to allow them to switch the site's language.
  • A configurable filter to set language based either on host or on folder. Allows you to have different URLs for each language or different folders such as:,, OR,,
  • Ability to set Dotcms's default language.
  • Define language variables in Dotcms's context to be used in containers, widgets and templates such as language code, language country, language description.
  • Javascript functions for language switching
  • Ability to preset user's language based on browser's language headers.

Following is a list of some recommended best practices when implementing multi-lingual sites in Dotcms:

  • When using images on the templates, containers or widgets using $languageKey like this:

< img src="/global/images/${languageKey}/myimage.jpg" >
Then save the image on each language folder like this:

  • When creating dynamic pulls there is no need to use the languageId variable, this gets set automatically to use the language from the session:

+type:content +structureInode:5

  • If you want your website to have one host per language like this:

You need to create one host: and create all other hosts as aliases.

  • You can also have prefixes for your site with the languageKey like this:

/es_es /myfolder/

These can be virtual folders or real folders in Dotcms.

  • Edit the language property files through webdav. They are stored in the system folder and are only editable if you have the CMS Admi n or Administrator role. Make sure you edit these files in UTF-8 format.
  • Create all template labels using variables from the language property files. We like to use a convention for each template or main sections like this:

com.mysite. navigation. home=Home
com.mysite. navigation. about=About Us
com.mysite. navigation. about.our_company=Our Company

When using these variables on the templates you need to call the Dotcms macro that allows you to get the variable value based on the language selected like this:

  • Create your folders and items you want to display on the navigation with Titles using labels from your property files.

If you'd like help implementing some of these features on your website you can always call us and we can have one of our professional services team work with you in having a successful multilingual implementation in Dotcms. If you have specific requirements please contact us. We are here to help.

Filed Under:

Recommended Reading

Why Global Brands Need a Multi-tenant CMS

Maintaining or achieving a global presence requires effective use of resources, time and money. Single-tenant CMS solutions were once the go-to choices for enterprises to reach out to different market...

14 Benefits of Cloud Computing and Terminology Glossary to Get You Started

What is cloud computing, and what benefits does the cloud bring to brands who are entering into the IoT era?

Headless CMS vs Hybrid CMS: How dotCMS Goes Beyond Headless

What’s the difference between a headless CMS and a hybrid CMS, and which one is best suited for an enterprise?