Language and globalization concepts
Globalization displays website content in different languages and localizes user-facing text to match each visitor's language preference. Use the globalization features in CMS to serve multilingual audiences from a single site.
CMS requires language information in the URL path or domain because:
- Search engines such as Google need to crawl and separate content by language.
- Users expect to share a link and have the recipient see the same content.
Output caching in .NET and browser caching require a single URL to serve identical content to anonymous visitors.
Language concepts
The three language concepts in CMS control how the platform resolves language for visitors and editors. Understanding these concepts is essential for configuring multilingual sites.
CMS uses three language concepts. Two come from .NET: culture (system language) and uiCulture (UI language). The third is the CMS content language. Languages and language settings use cultures as defined by the .NET CultureInfo object. A typical culture is en-US, which specifies English with United States formatting. A neutral culture such as sv specifies Swedish without region-specific formatting.
Terminology
The following terms describe how CMS represents and resolves language information.
- Culture – An instance of the CultureInfo class and the preferred way to pass language information in CMS.
- Locale – Not explicitly used in CMS, except where other components require it. The locale is read from the LCID property of the required culture, typically CultureInfo.CurrentCulture, which corresponds to the system language.
- Language code – A string that defines the culture to use. See CultureInfo.Name for valid values. Use a language code when you cannot pass a CultureInfo object.
- Candidate match – A fallback language code that shares the segment before the hyphen. For the code en-GB, both en and en-US are candidate matches.
Language setting types
CMS separates language into three setting types, each controlling a different part of the visitor and editor experience.
- System language – Controls date and time formatting, sort order, and number formatting.
- User interface language – Controls which translated resources display. Sets the language for the editing UI and all localized text retrieved through code.
- Content language – The preferred language for displaying content. A LanguageSelector resolves the actual content language from available languages. The system applies fallback or replacement languages when the preferred language is unavailable.
System language
The system language controls culture-dependent formatting such as sort order and date display. Because formatting rules are culturally dependent, the system language requires a specific culture rather than a neutral culture.
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.
User interface language
The UI language controls which translated text appears for interface elements such as buttons and labels. It defines most text in the CMS editing UI. For site visitors, the UI language controls only minor elements such as button text. The content language defines most visitor-facing information.
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.
Retrieve localized string resources through the LocalizationService API. For details, go to Localization service.
Content language
The content language determines which language version of content each visitor sees. It accepts both neutral and specific cultures.
The following rules determine the preferred content language:
- If the hostname maps to a specific language, that language applies. Configure this in Manage Sites in the Admin view.
- If a language segment exists in the URL (for example, http://company.com/en/info), that language applies.
- If you are in the edit view and have selected a language site from Sites, 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.