Dev GuideAPI ReferenceUser Guide
HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In
GitHubNuGetDev CommunityDoc feedback

When describing the language concept in Optimizely Content Management System (CMS), the following language setting types are mentioned:

  • **System language** – Used to control date/time formatting, 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.

## Determine 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.N`ame.

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

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

  1. If viewing a template, use the current content language code if language code is valid.

  2. If there is a language setting in the personal profile, use it if language code is valid.

  3. Use system default as set in _web.config_, **<globalization culture="xx">**, which may be auto in which case it reads the browser language preferences. Because this culture was set at the very start of the request, this step is really 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.

### Modifying

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

## 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 all available User Interface languages (`LanguageManager.GetLanguages()`) and pick he first language from the preferred list that has an exact match in the UI Language list.

  3. If no such match exists, use the first candidate match (\*).

  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`). The default implementation is done in `EPiServer.PageBase`.

The preferred way to retrieve _localized string resources_ in CMS are 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 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 host name, 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 all available content languages, enabled or not, (`LanguageBranch.List()`) and pick the first language from the preferred list that has an exact match in the content language list.

  3. If no match found in the previous step, use the first candidate match(\*).

  4. If no candidate match found, use the first language returned by the list of available and enabled content languages.

### Modify

The selection algorithm outlined above is implemented in `ContentLanguage.DefaultContentLanguage` and can be overridden by inheriting from `ContentLanguage` and assigning an instance of the new class to the static property Instance on `ContentLanguage`.

After that, the preferred content language is determined, and 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 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 language routing behavior with a configuration setting `strictLanguageRouting` on the configuration element `applicationSettings` that can be set to **false** to get a more "tolerant" behavior.