Determining languages

This document describes the API for accessing, selecting and modifying languages, as well as strict language routing in EPiServer CMS.

When describing the language concept in EPiServer 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.

Refer to the Globalization section for a more detailed explanation of the language management concept in CMS.

Determing system language

Accessing

The current value can be determined by reading CultureInfo.CurrentCulture and set by setting Thread.CurrentThread.CurrentCulture. The information is a CultureInfo object and the language code ("en-GB", "sv-SE" etc.) can be retrieved from CultureInfo.Name.

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 uiCulture="xx">, which may be auto in which case it reads the browser language preferences. Since this culture has been set at the very start of the request, this step is really a "do nothing".

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

Modifying

In case 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.

Determing user interface language

Accessing

The current value can be determined by reading CultureInfo.CurrentUICulture and set by setting Thread.CurrentThread.CurrentUICulture. The information is a CultureInfo object and the language code ("en", "sv" etc.) can be retrieved from CultureInfo.Name.

Selecting

1. Compile a list of perferred 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.

Modifying

In case 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 EPiServer are through the LocalizationService API. For information on how to use this, refer to the Localization service section.

Determing content language

Accessing

The current value can be determined by reading ContentLanguage.PreferredCulture. You can change the value by assigning this property.

Selecting

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 we 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.

Modifying

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.

Refer to Globalization scenarios for more information about language-specific content settings in EPiServer CMS.

Strict language routing

Strict language routing will cause the display of an error message if the URL and language-host mapping do not match. The examples below illustrates 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 config, the URLs will be 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/ will give a 404, since when there is a host mapping that defines a language the language should not be present in the URL.

The strict langauge routing behavior can be modified. There is a configuration setting strictLanguageRouting on the configuration element applicationSettings that can be set to "false" to get a more "tolerant" behavior.

See also

• Globalization
• Globalization scenarios
• Adding languages
• Localization services