Multilingual content

5 min

A content type that implements the ILocalizable interface supports several language versions. For example, pages and blocks have multilingual support, while media and folders do not. For a content type that implements ILocalizable, define individual properties as culture-specific to store different values for each language. Properties that are not culture-specific are shared across all language versions. The following example shows a property decorated with the [CultureSpecific] attribute.

[CultureSpecific]
public virtual string Heading {
  get;
  set;
}

Fallback and replacement settings

Fallback settings display translated content where available and fall back to a default language for untranslated parts.

From the edit UI or programmatically, define language fallback and replacement rules. These rules apply to the content item where they are defined and are inherited by all content below it in the structure. For example, if a fallback language B replaces language A for part of the structure, a request for content in language A returns the content in language B.

Use replacement while adding a language to a site but keeping it inaccessible to site visitors. When the translation of the whole structure is complete, turn off the fallback language. Fallback settings apply when content does not exist in a language or when the content is not published in that language.

Load content

The LanguageLoaderOption controls how languages are handled during loading. The following overload on IContentLoader:

var content = _contentLoader.Get<IContent>(contentLink);

is equivalent to:

var content = _contentLoader.Get<IContent>(contentLink, new LoaderOptions() {
  LanguageLoaderOption.FallbackWithMaster()
});

In this case, language is not specified, so the content loads in the same language as the current request route (ContentLanguage.PreferredCulture). It also uses a fallback: if the content does not exist or is not published in the language, it falls back according to the specified fallback rules, with a final fallback to the master language. The master language is the language version where common properties are saved. It is the first language version in which the content was created.

Use the overload that takes a CultureInfo to load content in a specific language:

var content = _contentLoader.Get<IContent>(contentLink, CultureInfo.GetCultureInfo("sv"));

This is equivalent to:

var content = _contentLoader.Get<IContent>(contentLink, new LoaderOptions() {
  LanguageLoaderOption.Specific(CultureInfo.GetCultureInfo("sv"))
});

A fallback option is not specified in this case, so no fallback rules are applied.

Pass CultureInfo.InvariantCulture as CultureInfo to return the master language version. This is useful when no specific language version is required (for example, when reading a language-neutral property like ParentLink). It is also faster because fallback rules are not applied:

var master = _contentLoader.Get<IContent>(contentLink, CultureInfo.InvariantCulture);