Dev GuideAPI ReferenceUser Guide
HomeDev GuideRecipesAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityOptimizely AcademySubmit a ticketLog In
Dev Guide
GitHubNuGetDev CommunityOptimizely AcademySubmit a ticket

Determine languages

Describes the API for accessing, selecting, and modifying languages and strict language routing in Optimizely CMS.

Optimizely Content Management System (CMS) uses three language setting types:

  • System language – Controls date and time formatting, sort order, and number formatting.
  • User interface language – Controls which translated resources display and sets the language of the editing UI.
  • Content language – The preferred language for displaying content.

For details about the language management concept, go to Globalization.

Determine system language

The system language controls date formatting, sort order, and other culture-dependent behavior. Determine the current value or override it at runtime.

Read the current value from CultureInfo.CurrentCulture. Set it through Thread.CurrentThread.CurrentCulture. Retrieve the language code (such as en-GB or sv-SE) from CultureInfo.Name.

📘

Note

CurrentCulture cannot be a neutral culture because it provides sorting and formatting information. The language code must be a specific culture such as en-GB or sv-SE. Assigning a neutral culture to CurrentCulture throws an exception.

The following rules determine the system language:

  • Outside the edit and admin UI, the system uses the content language.
  • For a logged-in user with a preferred language, the system uses that selection.
  • Use the setting from GlobalizationSettingsOptions.CultureLanguageCode. If the value is set to Auto, the browser language preferences apply.

Determine user interface language

The UI language determines which translated text appears for interface elements. Override it at runtime to test localized resources.

Read the current value from CultureInfo.CurrentUICulture. Set it through Thread.CurrentThread.CurrentUICulture. Retrieve the language code (such as en or sv) from CultureInfo.Name.

CurrentUICulture accepts neutral cultures because the runtime does not use it for sorting or formatting. For example, CultureInfo.GetCulture("en") returns a valid culture for CurrentUICulture.

The following rules determine the UI language:

  • Outside the edit and admin UI, the system uses the content language.
  • For a logged-in user with a preferred language, the system uses that selection.
  • Use the setting from GlobalizationSettingsOptions.UICultureLanguageCode. If the value is set to Auto, the browser language preferences apply.

Determine content language

The content language controls which language version of content each visitor sees. Read or change the value at runtime to support language-specific logic.

Read the current value from IContentLanguageAccessor.Language or the static accessor ContentLanguage.PreferredCulture. Change the value by assigning this property. Content language accepts neutral cultures. When sorting or formatting requires a specific culture, call CultureInfo.CreateSpecificCulture. This method follows .NET rules for deriving a specific culture from a neutral one. See the Microsoft documentation for CultureInfo.CreateSpecificCulture.

The following rules determine the preferred content language:

  • If the hostname is associated with a specific language, that language applies.
  • If a language segment exists in the URL (for example, http://company.com/en/info), that language applies.
  • If a language site is selected from Sites in the edit view, that language applies.
  • If the request contains a query parameter or cookie named epslanguage, that language applies.
  • If GlobalizationSettingsOptions.UseBrowserLanguagePreferences is true, the browser language preference applies.
  • If a language is mapped to wildcard host *, that language applies.
  • Use the value from GlobalizationSettingsOptions.UICultureLanguageCode.
  • When no other rule matches, the system uses the first enabled language branch in Admin > Language Branches. This branch serves as the default language.
📘

Note

After the preferred content language is determined, a second step determines the actual language to display. If the content does not exist in the preferred language, a fallback process begins. For pages, the page language settings in the edit view define the fallback. Go to Globalization scenarios for details about language-specific content settings.

Strict language routing

Strict language routing returns an error when the URL and language-host mapping do not match. Disable or adjust this behavior to support more flexible URL patterns.

The following examples show how language routing works. A website has a page at root named News in English and Nyheter in Swedish. With no language mapping defined for site hosts, URLs resolve as follows:

  • http://localhost/News/ – Returns 404 because a language segment is required when no language-host mapping is configured.
  • http://localhost/en/News/ – Displays the page in English.
  • http://localhost/sv/Nyheter/ – Displays the page in Swedish.
  • http://localhost/Nyheter/ – Returns 404 (same reason as the first example).
  • http://localhost/en/Nyheter/ – Returns 404 because the URL segment language does not match the language segment.

When a language-to-host mapping is defined, http://localhost/en/News/ returns a 404. The language segment must not appear in the URL when a host mapping defines a language.

Set RoutingOptions.StrictLanguageRouting to false to relax strict language routing.

Updated 11 days ago