Globalization scenarios

Globalization scenarios structure language routing, domain mapping, and user preferences for multilingual CMS sites.

Serve different content from a single domain based on each visitor's language selection.

Use this approach when a domain such as http://site.se should default to Swedish without including the language in the URL path.

Persist the user language preference on a single domain by setting a cookie with the current language selection. The cookie named epslanguage ensures visitors see the same language when they return. This approach also supports redirecting visitors to systems that do not retain the language in the URL.

A language branch has a unique identifier in the database to handle constraints. APIs expose the branch as a language code such as EN. Language codes must be unique because the reverse lookup fails with duplicate codes.

Developers create a content item on a language branch. The first language branch created becomes the master branch for that content item. Every content item has a master language branch, whether globalized or not. The master branch stores all properties for its language and the common properties. Additional language branches store only language-specific properties.

Non-master language branches include common properties from the master branch. Those properties are read-only. Calling IContentRepository.Save on a non-master branch with changes to a common property raises an exception.

Language-specific settings control which properties store values per language and how language selection, fallback, and archival behavior work across content.

Language-specific properties control which fields store separate values per language.

Administrators and developers define language-specific properties on content types. The system defines which metadata properties, such as Name, are language-specific. Content-related metadata properties are language-specific. Navigation-related metadata properties are common.

The following metadata properties are defined per language:

Check whether a property is language-specific by reading IsLanguageSpecific on the PropertyData class.

Content language settings define the languages available to editors when creating content on each part of a site. The settings also define fallback and replacement languages. The administrative API is EPiServer.DataAbstraction.ContentLanguageSettingRepository. The runtime API with inheritance support is EPiServer.Core.IContentLanguageSettingsHandler. Content language settings do not restrict the languages rendered on the site. CMS uses these settings to select fallback languages and filter editor options.

Languages are selected at runtime through a language selection process. Pass LanguageLoaderOption to IContentRepository to customize language selection.

The language loader considers a language available when it is published (CurrentPage.PendingPublish is false). The language selector does not check publish dates. When a content item expires in one language, it is no longer displayed, and no fallback to another language is applied.

Archival moves expired pages to a designated archive location.

A page is archived when an archive page is set and the Stop publish date has passed. The archival process clears the Stop publish date. On globalized pages, only the master language Stop publish date is checked. When the page moves to the archive, Stop publish dates for all languages are cleared.

Browser language preferences let CMS detect and match a visitor's language automatically.

The browser sends an Accept-Language header with the visitor's preferred languages. A Swedish user's header contains sv. When GlobalizationSettingsOptions.UseBrowserLanguagePreferences is enabled, CMS matches this value to an enabled website language code. An exact match takes priority. If no exact match exists, such as en-NZ, CMS falls back to a matching neutral culture like en.

FindPagesWithCriteria through IPageCriteriaQueryable searches all languages by default. The results use the same language selection process as any other page load. Control the following parameters:

These parameters narrow the search to a specific language branch.