Adding and Editing Languages

Last Updated: Oct 16, 2019
documentation for the dotCMS Content Management System

Multiple languages are fully supported in dotCMS. Back-end users can contribute the same content in multiple languages and front end users may choose to view content in the supported languages. To access the language configuration screen, select Languages from the System menu.

Languages selection in the System menu

Adding a Language

To add another language to your site, click the Add New Language button in the Languages tab.

Add New Language button

Enter the two character Language Code and Country Code and then fill out the complete descriptive name of the Language and Country being represented as in the image below.

Add New Language fields

After saving the new language users will be able to open, search for, or create a piece of content of any Content Type in the new language by clicking on the language flag icon that is now displayed. When adding or editing content, simply click on the select box provided by the Language field to enter content in a particular language.

The initial dotCMS configuration specifies English as the default language. However the default language can be changed to any language by editing the System Language Properties in the file. Note: It is strongly recommended that changes to this file be made through a plugin.

List of system languages

After adding the new language, click on the content tab and make sure that the new language has been added to the language filter field in the content search area.

Language filter field

Editing or Removing Languages

To edit or remove a language, right-click the language name in the Languages list, and select Edit Language to open the Language properties.

Edit Language right-click menu

To edit the Language properties, change the appropriate properties and press the Save button.

To delete the Language, press the Delete button.

Removing Languages After Creating Content in the Language

You can not delete a language if you have content which was created in that Language. If you attempt to delete a Language which has content, the delete will fail and an error message will be displayed:

Error message attempting to delete content Language

Therefore, after you have created content in a given language, you can not delete that language unless you first delete all content in that Language. However when you delete any content, you must delete all language versions of that content (you can not delete just one language version of a content item), so you can not delete content in that Language without also deleting all versions of that content in all other languages as well.

However you may unpublish and archive different language versions of a content item, without unpublishing or archiving other language versions of the same content. Thus, for example, you may unpublish and archive just the Spanish language version of a content item, while leaving the English version of that content published.

Since you can not delete just a single Language version of content, it is strongly recommended that if you wish to remove a Language, you simply unpublish and archive all content in that Language instead of deleting the language itself.

The Language ID

Whenever you add a language to dotCMS, the new language is automatically assigned a Language ID, which is an integer number used to identify the language within dotCMS. You can use the languageId field to query and access content in a specific language and to identify the language of a piece of content when accessing content in multiple languages.

To identify the Language ID of a language, you must first add and save the language. Once the language has been saved, right-click on the language flag and select Edit Language. The Language Id is displayed in the Edit Language screen.

Important Notes

  • You can not choose the Language ID to assign to a language, or the order in which the Language IDs are assigned.
    • The default language always has a Language ID of 1.
    • The Language ID for all other languages is automatically assigned by dotCMS, in sequential order as you add languages.
      • For example, the first language you add to dotCMS is assigned a Language ID of 2, the second language is assigned a Language ID of 3, etc..
  • You can not edit or change the Language ID once a language has been added to dotCMS.
    • If you manage multiple dotCMS instances, or if you plan to migrate content from one dotCMS instance to another (e.g. using bundles, make sure to add the all the same languages to both dotCMS instances and add them all in the same order.
      • This is the only way to ensure that the languages in different dotCMS instances have the same Language IDs.
    • Content which is not in the default language which is migrated to another dotCMS instance with different language IDs will be imported into the wrong language version of the content on the receiving instance.

On this page


We Dig Feedback

Selected excerpt: