HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Globalization

Introduces the globalization and language management concept for the Optimizely platform, including Optimizely Content Management System (CMS) and Optimizely Customized Commerce.

Globalization creates and displays website content in different languages and makes the user interface display in different languages by localizing user-facing texts.

How does Optimizely know which language to display to visitors?

Optimizely Content Management System (CMS) enforces language visibility in the URL, 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 it to get the same content.

There are also 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 of which .NET defines (culture and uiCulture), and one that is the CMS content language. See the .NET culture as System Language and uiCulture as User Interface Language. 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 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 of 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 other components require locale. 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 or culture.
  • Candidate match–Many language selection algorithms use candidate matches. 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. A candidate match is the first language code that matches the substring before the hyphen.

Language setting types

  • System language – Used to control date or time formatting, 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 you make calls 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 you can apply fallback or replacement languages on the website.

System language

The system language determines how to sort listings, format dates and times, and so on. Because these formatting rules are culturally dependent, the system language must not be a neutral culture.

The following rules determine the system language:

  1. Use the content language if not in the edit or admin user interface.
  2. If a user is logged in and sets a preferred language, use the personalized language selection for this user.
  3. Use the setting from GlobalizationOptions.CultureLanguageCode. If you set a culture to Auto, it uses the language preferences from the web browser.

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. Still, for a site visitor, the user interface language applies only to minor elements, such as text on buttons. Most information is usually content for a visitor, defined by the content language.

The following rules determine the user interface language:

  1. Use the content language if not in the edit or admin user interface.
  2. If a user is logged in and sets a preferred language, use the personalized language selection for this user.
  3. Use the setting from GlobalizationOptions.UICultureLanguageCode. If you set a culture to Auto, it uses the language preferences from the web browser.

The preferred way to retrieve localized string resources in CMS is through the LocalizationService API. See the Localization service section.

Content language

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

The following rules determine the preferred content language:

  • 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, it uses that language.
  • If you have defined the hostname to be associated with a specific language, it uses that language; see information about section <siteHosts> in web.config.
  • 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 the content language does not discover anything else, use the first enabled language branch defined in Admin or Language Branches as the default language.