Globalization

This document provides an introduction to the globalization and language management concept for the EPiServer platform, including CMS and Commerce. By globalization we mean the possibility to create and display website content in different languages, as well as the possibility to make the user interface appear in different languages through the localization of user facing texts.

How does EPiServer know which language to display to visitors? The short answer is that EPiServer enforces the language to be visible in the URL, either in the path or the domain part of the URL. The reasons for this are:

Search engines, such as Google, must be able to crawl a website and easily separate content.
Users expect to be able to cut and paste a link into an e-mail and send it to someone who can click the link getting the same content.

There are also some technical reasons such as output caching in .NET and web browser caching on the client, these will expect a single URL to render the same content to anonymous users.

Language concepts

There are three different language concepts in EPiServer, two which are defined by ASP.NET (culture and uiCulture), and one which is the EPiServer (CMS) content language. Refer to the ASP.NET culture as “System Language” and uiCulture as “User Interface Language”. All languages and language settings are expressed as Cultures (as defined by the .NET CultureInfo object). A typical culture is “EN-US” which defines the language as English (EN) with the culturally defined specifics for United States (US). You may in some cases only define the language, such as “SV” which defines the neutral culture "Swedish".

Terminology

Culture. An instance of the CultureInfo class. The preferred way of passing language information in EPiServer.
Locale. Never explicitly used in EPiServer, except where locale is required by other components. In this case the locale is read from the LCID property of the required culture, usually CultureInfo.CurrentCulture which corresponds to the system language.
Language code. A string that defines the culture to use. See CultureInfo.Name for definition and possible values. If you cannot pass a CultureInfo object, this is the alternative way of specifying language/culture.
Candidate match. Many language selection algorithms will make use of "candidate matches". This means that if you have a language code "en-GB", then language code "en" would be a candidate match. Another possible candidate match for "en-GB" would be "en-US". This means that a candidate match is the first language code that matches the substring before the hyphen.

Language setting types

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, and any other place where calls are made to retrieve and display localized texts.
Content language. The preferred language when displaying content. Note that the actual content language is eventually determined by a LanguageSelector and depends on the languages available for the content displayed, since fallback or replacement languages may be applied on the website.

System language

The system language determines how listings are sorted, how to format date and time, etc. Since these types of formatting rules are culturally dependent, the system language must not be a neutral culture.

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 profiles are enabled, use the personalized language selection for this user.
Use the setting (xx-YY) from web.config ( <globalization culture="xx-YY" ... /> ). Note that if culture is set to Auto, the language preferences from the web browser is used.

User interface language

The user interface language is only used to pull out localized texts in the ASP.NET application, it will define the majority of the texts in the EPiServer CMS user interface, but for a site visitor the user interface language will only apply to minor elements such as texts on buttons. For a visitor the majority of information is usually content, which is defined by the content language.

The user interface language is determined by the following rules:

If not in Edit/Admin user interface, use the content language.
If the user is logged on and profiles are enabled, use the personalized language selection for this user.
Use the setting (xx-YY) from web.config ( <globalization uiCulture="xx-YY" ... /> ). Note that if culture is set to Auto, the language preference from the web browser is used.

The preferred way to retrieve localized string resources in EPiServer is through the LocalizationService API. For information on how to use this, refer to the Localization service section in the EPiServer Framework SDK.

Content language

The content language controls which language version of the content that is displayed, it can be a neutral culture or a specific culture.

The preferred content language is determined by the following rules:

If there is a language indicator in the URL (a friendly URL like http://company.com/en/info, or a classic URL like http://company.com/templates/page.aspx?id=23&epslanguage=en), that language is used (en).
If you are in the edit view and have a language selection from the language selection drop-down list, that language is used.
If you have defined the host name to be associated with a specific language, that language is used, see information about section <siteHosts> in web.config for more information.
If the requests contain a cookie named epslanguage, use the language defined by the cookie.
If the web.config setting pageUseBrowserLanguagePreferences is true, then the language preference from the web browser is used.
Fetch the setting from the uiCulture attribute on the globalization node in web.config if defined.
If nothing else is discovered, use the first enabled language branch as defined in Admin / Language Branches, which means that this could be viewed as the default language.

Try our conversational search powered by Generative AI!