Globalization scenarios

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

Scenario 1 – Global domain with multiple languages

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

1. Set a default language that most visitors understand (typically English for a global site).
2. Enable language detection based on browser preference by setting GlobalizationSettingsOptions.UseBrowserLanguagePreferences to true.

Test the configuration

1. Go to the language settings in your web browser.
2. Select a language preference. The browser redirects to the matching content language if one exists.

Scenario 2 – Local domains mapped to languages

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

Scenario 3 – Remember user preference

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.

📘

Note

Use cookies with care. Include the language in the URL for every page to preserve language context during navigation. A visitor with a Swedish language cookie who follows an English link should stay on the English site. The cookie should not override an explicit language choice.

Language branches

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

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

Properties

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:

• IContent.Name
• IVersionable.IsPendingPublish
• IVersionable.Status
• IChangeTrackable.Saved
• IChangeTrackable.Changed
• IChangeTrackable.CreatedBy
• IChangeTrackable.ChangedBy
• IChangeTrackable.Created
• ILocalizable.Language
• IVersionable.StartPublish
• IVersionable.StopPublish
• PageData.ExternalURL
• IRoutable.RouteSegment
• PageData.LinkType

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

Content language settings

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.

📘

Note

Language settings are available for pages only, not for other content types such as blocks.

Language options in the API

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.

Archive page

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.

Web browser preference

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.

📘

Note

Use ISO language codes. To enable preference fallback, use the language code en for the English version that serves as the default English branch.

Property search

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:

• Search on a specific language only.
• Pass a language selector used when returning the pages.

These parameters narrow the search to a specific language branch.