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


**Globalization** is the ability to create and display website content in different languages, and the ability to make the user interface appear in different languages through the localization of user-facing texts.

**How does Optimizely know which language to display to visitors? **

Optimizely Content Management System (CMS) enforces language visibility in the URL, either in the path or the domain part of the URL, because:

  • Search engines, such as Google, must be able to crawl a website and separate content.

  • Users expect to cut and paste a link into an email and send it to someone who can click the link getting the same content.

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

## Language concepts

There are three different language concepts in CMS, two that are defined by .NET (`culture `and `uiCulture`), and one that is the CMS **content language**. See the .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 the United States (US). In some cases, you may define the language only, 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 CMS.

  • **Locale** – Never explicitly used in CMS, 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 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 is 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, and so on.

  • **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. The actual content language is eventually determined by a `LanguageSelector` and depends on the languages available for the content displayed, because 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, and so on. Because 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:

  1. If not in edit/admin user interface, use the content language.

  2. If a user is logged in and a preferred language is set by user, use the personalized language selection for this user.

  3. Use the setting from `GlobalizationOptions.CultureLanguageCode`. If culture is set to Auto, the language preferences from the web browser are used.

## User interface language

The **user interface language** is used only to pull out localized texts in the web application. It defines the majority of the texts in the CMS user interface, but for a site visitor the user interface language applies only to minor elements, such as text 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:

  1. If not in edit/admin user interface, use the content language.

  2. If a user is logged in and a preferred language is set by user, use the personalized language selection for this user.

  3. Use the setting from `GlobalizationOptions.UICultureLanguageCode`. If culture is set to Auto, the language preferences from the web browser are used.

The preferred way to retrieve localized string resources in CMS is through the `LocalizationService` API. For information about using this, see the [Localization service](🔗) section.

## 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:

  1. 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).

  2. If you are in the edit view and have a language selection from the language selection drop-down list, that language is used.

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

  4. If the requests contain a cookie named `epslanguage`, use the language defined by the cookie.

  5. If the `web.config` setting `pageUseBrowserLanguagePreferences` is true, then the language preference from the web browser is used.

  6. Fetch the setting from the `uiCulture` attribute on the globalization node in `web.config` if defined.

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