HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideLegal TermsGitHubNuGetDev CommunityOptimizely AcademySubmit a ticketLog In
Dev Guide

Determine languages

Describes the API for accessing, selecting and modifying languages, and strict language routing in Optimizely Content Management System (CMS).

Use the following language setting types when describing the language concept in Optimizely Content Management System (CMS):

  • System language – Used to control date or time formatting, sort order, and so on.
  • User interface language – Controls the localized (translated) resources to display and determines the language of the user interface.
  • Content language – The preferred language when displaying content.

See Globalization  for information about the concept of language management in Optimizely CMS.

Determine system language

Access

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.

Select

Compile a list of preferred languages in the following priority order:

  1. If viewing a template, use the current content language code if the language code is valid.
  2. If there is a language setting in the personal profile, use it if the language code is valid.
  3. Use system default as set in web.config, <globalization culture="xx">, which may be auto, where it reads the browser language preferences. Because you set this culture at the start of the request, this step is a do nothing.

📘

Note

Valid means that there is a CultureInfo with the specified language code and that the language is not a neutral culture.

Modify

If you want to customize the selection logic, you can modify CurrentCulture in the InitializeCulture() method (virtual method on System.Web.UI.Page). EPiServer.PageBase does the default implementation.

Determine user interface language

Access

The current value can be determined by reading CultureInfo.CurrentUICulture and set by setting 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.

Select

  1. Compile a list of preferred languages in priority order:
    • If viewing a template, add the current content language code.
    • If there is a language setting in the personal profile, add it to the list.
    • Use system default as set in web.config, <globalization uiCulture="xx">, which may be auto, in which case it reads the browser language preferences.
  2. Get a list of available user interface languages (LanguageManager.GetLanguages()) and pick the first language from the preferred list that has an exact match in the UI Language list.
  3. Use the first candidate match if no such match exists (*).
  4. If no candidate match exists, use the first available user interface language.

Modify

If you want to customize the selection logic, you can modify CurrentUICulture in the InitializeCulture() method (virtual method on System.Web.UI.Page). EPiServer.PageBase does the default implementation.

The preferred way to retrieve localized string resources in CMS is through the LocalizationService API. For information about using this, see Localization service.

Determine content language

Access

You can determine the current value by reading ContentLanguage.PreferredCulture. You can change the value by assigning this property. Content language can be a neutral culture. If sorting or formatting is required, you should read from ContentLanguage.SpecificCulture. The specific culture is evaluated on-demand and follows the .NET Framework rules for determining a specific culture from a neutral culture. See CultureInfo.CreateSpecificCulture.

Select

  1. Compile a list of preferred languages in priority order:
    1. If the query string parameter epslanguage exists, add the language code to the list.
    2. If the admin or edit page and the editlanguagebranch cookie exists, add the language code to the list.
    3. If the web.config parameter domainLanguageMapping is set, and you have a match from the hostname; add the language code to the list.
    4. If the cookie epslanguage exists, add the language code to the list.
    5. If the browserLanguageDetection setting is enabled, get the entire list of Request.UserLanguages into the list.
  2. Get a list of available content languages (LanguageBranch.List()), enabled or not, and pick the first language from the preferred list that has an exact match in the content language list.
  3. Use the first candidate match if the previous step does not find a match(*).
  4. If it does not find a candidate match, use the first language from the available and enabled content languages list.

Modify

CMS implements the selection algorithm outlined above in ContentLanguage.DefaultContentLanguage. You can override it by inheriting it from ContentLanguage and assigning an instance of the class to the static property Instance on ContentLanguage.

After that, the preferred content language is determined, and another step uses the preferred content language to determine the actual language to display. If the current content does not exist in 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 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 there is no language mapping defined for site hosts in the configuration file, it handles the URLs as follows:

  • http://localhost/News/ (404 because when not having a 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 because the 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 language routing behavior with a configuration setting strictLanguageRouting on the configuration element applicationSettings that can be set to false for a more "tolerant" behavior.