Implementing multilingual sites using Dotcms


Aug 04, 2012

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.

Recent Posts

Omnichannel Doesn't Mean You Have To Be On Every Channel

Delivering an omnichannel customer experience is now considered obligatory, but does omnichannel mean you should be on every channel?

Lessons Learned From Building An Alexa Skill For Students

Gettysburg College build a set of skills for their students, and this is what they learned.

Voice of the Customer: 6 Common Mistakes To Avoid

Voice of the customer programs are easy, and your customers love the customer experience you give them. Well, at least, you think they do. Here’s why VOC programs are important, and six ways to not fail at them.

You're Living In a Customer Experience Bubble (Here's How To Burst It)

Customer experience is far too important to be exclusively owned by the marketing department. Here’s how to burst your CX bubble and take part in the ultimate team sport — customer experience orchestration — in five steps.