Note: This documentation is for the preview version of the upcoming release of CMS 12/Commerce 14/Search & Navigation 14. Features included here might not be complete, and might be changed before becoming available in the public release. This documentation is provided for evaluation purposes only.
This topic describes the API for accessing, selecting and modifying languages, and strict language routing in Optimizely CMS.
When describing the language concept in Optimizely CMS, the following language setting types are mentioned:
- System language. Used to control date/time formating, sort order etc.
- User interface language. Controls the localized (translated) resources to display, determines the language of the user interface.
- Content language. The preferred language when displaying content.
See Globalization for information about the language management concept in Optimizely CMS.
Determining system language
Accessing
You can determine the current value by reading CultureInfo.CurrentCulture and set by setting Thread.CurrentThread.CurrentCulture. The information is a CultureInfo object and you can retrieve the language code (en-GB, sv-SE, and so on) from CultureInfo.Name.
Note: CurrentCulture cannot be a neutral culture because its primary purpose is to provide sorting and formatting information. This means that the langauge code must be something like en-GB or sv-SE. Trying to use a neutral culture results in an exception when assigning the culture to CurrentCulture.
Selecting
The system language is determined by the following rules:
- If not in edit/admin user interface, use the content language.
- If a user is logged in and a prefered language is set by user, use the personalized language selection for this user.
- Use the setting from GlobalizationOptions.CultureLanguageCode. If culture is set to Auto, the language preferences from the web browser are used.
Determining user interface language
Accessing
You can determine the current value by reading CultureInfo.CurrentUICulture and set Thread.CurrentThread.CurrentUICulture. The information is a CultureInfo object and you can retrieve the language code (en, sv, and so on) from CultureInfo.Name.
CurrentUICulture can be a neutral culture (which means CultureInfo.GetCulture("en") would return a valid culture for CurrentUICulture) because CurrentUICulture is never used for sorting or formatting.
Selecting
The user interface language is determined by the following rules:
- If not in edit/admin user interface, use the content language.
- If a user is logged in and a prefered language is set by the user, use the personalized language selection for this user.
- Use the setting from GlobalizationOptions.UICultureLanguageCode. If culture is set to Auto, the language preferences from the web browser are used.
Determining content language
Accessing
You can determine the current value by reading IContentLanguageAccessor.Language or through static accessor ContentLanguage.PreferredCulture. You can change the value by assigning this property. Content language can be a neutral culture. If a specific culture is required (for example for sorting or formatting) then method CultureInfo.CreateSpecificCulture can be used on-demand and follows the .NET rules for determining a specific culture from a neutral culture. See CultureInfo.CreateSpecificCulture.
Selecting
The preferred content language is determined by the following rules:
- If you have defined the host name to be associated with a specific language, that language is used. The setting is specified under Manage Sites in admin view.
- If there is a language segment in the URL (like http://company.com/en/info), that language is used (en).
- If you are in the edit view and have selected a specific language site from the Sites section, that language is used.
- If the requests contain a query parameter or cookie named epslanguage, use the language defined by the query/cookie.
- If the setting GlobalizationSettingsOptions.UseBrowserLanguagePreferences is true, then the language preference from the web browser is used.
- Use the language mapped to wildcard host '*' if specifed.
- Fetch the setting from the GlobalizationOptions.UICultureLanguageCode.
- If nothing else is discovered, use the first enabled language branch as defined in Admin / Language Branches, which means that it can be viewed as the default language.
Modifying
After you determine the preferred content language, there is another step that uses the preferred content language to determine the actual language to display. If the current content does not exist for the preferred content language, a language fallback process is started. For pages, this is defined by the page language settings in the edit view.
See Globalization scenarios for information about language-specific content settings in Optimizely CMS.
Strict language routing
Strict language routing causes the display of an error message if the URL and language-host mapping do not match. The following examples show how the language routing works. Say, for example, that on a website there is a page under root named News in English and Nyheter in Swedish. Given that no language mapping is defined for site hosts in configuration file, the URLs are handled as follows:
- http://localhost/News/ (404 since when not having language-host mapping in config language segment must be present)
- http://localhost/en/News/ (page in English)
- http://localhost/sv/Nyheter/ (page in Swedish)
- http://localhost/Nyheter/ (404 as in point 1)
- http://localhost/en/Nyheter/ (404 since language for a page with the URL segment does not match the language segment)
When a language to host mapping is defined, then a URL like http://localhost/en/News/ produces a 404, because when there is a host mapping that defines a language, the language should not be present in the URL.
You can modify the strict langauge routing behavior through setting RoutingOptions.StrictLanguageRoutin, that can be set to false to get a more "tolerant" behavior.
Related topics
Do you find this information helpful? Please log in to provide feedback.
Last updated: Jul 02, 2021
Area:
Optimizely CMS
