Implementing multilingual sites using dotCMS

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.

August 03, 2012

Filed Under:


Recommended Reading

Beware of CMS Fads

This blog warns against adopting new technologies without sufficient consideration, using examples to illustrate how jumping on trends can lead to wasted resources.

24.04.24 LTS: Upgrade to the Universe

Now available: dotCMS 24.04.24 LTS, the first long-term supported release of 2024

Getting started with the dotCMS Universal Visual Editor with Next.js

In this blog post, I’ll demonstrate how you can get started with the Universal Visual Editor and Next.js in just fifteen minutes.