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.
Changing the Default Language
There are two ways to change the default language:
- On version
21.11or later, the default language can be configured at the user-interface level, through the admin panel. - On earlier versions, you must change all relevant properties to appropriate values for your location and language.
In both cases, remember to ensure that your site has versions of your content in the new default language!
Changing the Default Language via the Admin Panel
The recommended way to change the default language is through a dropdown selector in the admin panel.
Under the Types & Tags (or Content Model) category, select the Language portlet, right-click the language you wish to make default, and select the Make Default command.
After a language is selected as default, the changes will propagate in the background; the exact time this will take can vary by data sets.
Changing the Default Language via Legacy Method (Deprecated)
The method below details how to change the default language on a version of dotCMS prior to 21.11. Because of the relative complexity of the process — both in execution and support — dotCMS advises that it may be both simpler and safer to upgrade your dotCMS installation and instead use the method described above.
Nevertheless, for thoroughness, we have retained the instructions for the legacy procedure below.
Important
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.
Content Versions in the New Default Language
If you change the default 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:
- 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.
- Use the REST API to pull and then write new Language versions of each file and content item.
- (File Assets only) Create new Language versions of all File Assets using dotCLI.
For File Assets, the dotCMS CLI 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.
