The Default Language and System Language Properties documentation for the dotCMS Content Management System

A number of system properties define and control how dotCMS displays and handles content in different languages. The most important property is the Default Language, which is used by default for all queries and content retrievals, and is used in the Default Language fallthroughs.

Default Language Configuration

Each system must define a default language. The default language is configured in the file, via the following properties:

CHARSET = text/html;charset=UTF-8

The standard dotCMS distribution ships with the default language and the values of all these properties set for U.S. English (as shown in the property values shown above).

Language Standards

Where applicable, dotCMS adheres to appropriate ISO standards for country codes and language codes. Specifically:

PropertyAcceptable Values
DEFAULT_LANGUAGE_CODEDefined by ISO standard 639-1
DEFAULT_LANGUAGE_COUNTRY_CODEDefined by ISO standard 3166-1 (Alpha-2)
followed by an underscore (_),
followed by the value of the DEFAULT_LANGUAGE_COUNTRY_CODE
Not expected to conform to any standards.
May include country and language names in any language.

Changing the Default Language

To change the default language, you must do two things:

  1. Change all of the above properties to appropriate values for your location and language.
  2. Ensure that your site has versions of your content in the new Default Language.


If you change the default language after you have already created your site and content, the language of your site and content will not be changed, and will not use the new Default Language.

If you need to change the Default Language after you have already created your Site and content, please contact dotCMS support for assistance.

Content Versions in the New Default Language

If you change the Deafult Language on a site with no content in it, then all new content you create will be created, by default, in the new Default Language, and no additional work is required.

However, if you use the data in the dotCMS starter site, or if you already have content in your site before you change the Default Language, then you must update the existing content in your site to ensure that versions exist in the new Default Language.

If you update the Default Language, but content does not exist in the new Default Language, some content may fail to display when you attempt to view the content without explicitly specifying the Language to be the previous Default Language.

  • For example, if you change the Default Language from U.S. English to Spanish, but do not create versions of content in Spanish, then when you attempt to display the content in Spanish it may fail to display.
  • This is expected, since there is no Spanish version of the content to display, and the Language now falls back to Spanish, not English - so the English versions of the content will not be displayed.

Updating Existing Content to the New Default Language

When you change the Default Language, your content will not display properly in many cases unless you have versions of your content in the new Default Language. To create versions of your existing files and content in the new Default Language, you can use any of the following methods:

  1. Manually update each content item or file to be updated:
    • Open each content item and file in the back-end.
    • Change the Language in the content editor to the new Default Language.
    • Save the content or file in the new Language.
  2. Use the REST API to pull and then write new Language versions of each file and content item.
  3. (File Assets only) Create new Language versions of all File Assets using WebDAV.

For File Assets, WebDAV is recommended, since it allows you to update all the files in bulk relatively easily. To update non-file content in bulk, please use the REST API.

Updating Existing Themes to the New Default Language

If you change the Default Language, and attempt to display a Page that uses a Theme which was created before the Default Language was changed, display of the Page in the new Default Language will fail.

This is expected, because the Theme files will not exist in the new Default Language. The Theme, and any Pages that use it, will only display properly when the Language is explicitly set to the previous Default Language (e.g. U.S. English).

To update Themes to work with the new Default Language, you must create versions of each of the Theme files in the new Default Language. Please see above for several ways you can create new Language versions of the Theme files.

Language Property Files Refresh Frequency

The Language Properties files provide translations of common terms in several languages, which can be used to aid in translating forms, and which are used to translate the dotCMS back-end interface into different languages. By default, dotCMS re-reads the language properties files once every five minutes. To increase or decrease this frequency, modify the LANGUAGES_REFRESH_INTERVAL with the new frequency (in minutes).


For more information on the language properties files, see the Multilingual Forms documentation.

Multilingual Content Pulls

Several additional properties determine how dotCMS behaves when a user attempts to display Pages or Content, but no version of the content exists in the user's display language. For more information please see the Multilingual Content Pulls documentation.