Kentico Xperience 13 documentation and ASP.NET Core

Most documentation about running Xperience applications under ASP.NET Core can be found in a dedicated section: Developing Xperience applications using ASP.NET Core. The rest of the documentation still applies, but some code samples and scenarios might need slight modifications for Core projects.

Certain pages allow you to switch between Core and MVC 5 content using a selector located under the page heading.

All major differences between the MVC 5 and Core platforms are summarized in Migrating to ASP.NET Core.

×

Localizing content

To serve content in multiple languages on your site, you first need to ensure the following:

Localizing site content

Pages in the content tree

To localize content stored within page fields or edited via the page builder:

On this page

Independent text strings

For individual text strings displayed on the site (which are not stored within page fields), we recommend using multilingual resource strings. You can create and edit the strings in the Localization application of the Xperience administration interface.

To retrieve localized strings in the MVC application, add a using statement for the CMS.Helpers namespace, and use the ResHelper class:

Example
@using CMS.Helpers;
...
@{
    ViewBag.Title = ResHelper.GetString("SiteName.OurProducts");
}

<h2>@ResHelper.GetString("SiteName.OurProducts")</h2>

Individual text strings displayed on the site (which are not stored within page fields) can be localized just like in any ASP.NET Core application via strings in resource files.

Follow the practices described in Microsoft's localization documentation.

Xperience Localization application

Text values used within ASP.NET Core live site applications must be stored within localized resource files. For this purpose, you cannot use the Localization application of the Xperience administration interface (i.e., resource strings stored in the database).

Such strings can only be placed into fields in the administration using localization macros.

Text fields in the administration

If you need to supply a localized value into a field or text area where localization expressions are supported (such as the form builder UI), you can use expressions in the following formats:

Format

Description

Sample Value

Basic format:

{$key$}

Displays the value of the resource string with the specified key. Strings can be viewed and edited in the .resx files of your web projects or in the Localization application.

{$myform.firstname$}

In-place localization:

{$=default_string|culture_code=translation|culture_code=translation|etc.$}

Displays the strings defined in the expression.


{$=Hello|de-de=Hallo|it-it=Ciao$}

See also: Macro syntax

Localizing validation results and model properties

The standard approach for setting validation messages and other text properties of data models is to use attributes from the System.ComponentModel.DataAnnotations namespace. The attributes allow you to define common validation patterns, such as range checking, string length and required fields.

Localization of data annotation attributes in Xperience follows the conventional ASP.NET Core pattern. See the DataAnnotation localization section in the official ASP.NET Core documentation.

The default approach to validating the data model of MVC applications is to decorate the model and its properties with attributes from the System.ComponentModel.DataAnnotations namespace. You use the attributes to define common validation patterns, such as range checking, string length and required fields.

The Kentico.Xperience.AspNet.Mvc5 integration package provides a feature that allows you to use localized Xperience resource strings as error messages in data annotation attributes. The strings are localized based on the current culture context of the current visitor. The Kentico.Xperience.LanguagePack.English integration package (installed with the Kentico.Xperience.AspNet.Mvc5 integration package) contains a .resx file with the resource strings used in the English localization of Xperience. Aside from that, you can also use the standard resource strings stored in the database.

The feature supports localization of the following data annotation attributes:

  • Display
  • DisplayName
  • DataType
  • MaxLength
  • MinLength
  • Range
  • RegularExpression
  • Required
  • StringLength

Enabling data annotation localization

To enable localization of data annotations in your MVC application:

  1. Open your MVC project in Visual Studio.
  2. Enable the localization feature by calling the UseDataAnnotationsLocalization() method of the ApplicationBuilder instance.

    • Enable the feature at the start of your application's life cycle, for example in the Application_Start method of your project's Global.asax file.

      MVC projects created by the installer contain the ApplicationConfig class, whose RegisterFeatures method is called in the Application_Start method by default. You can use this class to encapsulate all of your ApplicationBuilder code (enabling and configuring of Xperience MVC features).

      using Kentico.Web.Mvc;
      
      ...
      
      protected void Application_Start()
      {
      	...
      
          // Gets the ApplicationBuilder instance
          // Allows you to enable and configure selected Xperience MVC integration features
          ApplicationBuilder builder = ApplicationBuilder.Current;
      
          // Enables the data annotation localization feature
          builder.UseDataAnnotationsLocalization();
      
      	...
      }

If the feature is enabled, validation results and display names of model properties are localized using Xperience localization services.

public class MessageModel
{
...
	 [Required(ErrorMessage = "General.RequiresMessage")]
     [Display(Name = "General.Message")]
     [DataType(DataType.MultilineText)]
     [MaxLength(500, ErrorMessage = "General.MaxlengthExceeded")]
     public string MessageText
     {
         get;
         set;
     }
...
}

Note: Individual error messages are processed by the System.String.Format method and support composite formatting. That is, the strings themselves can contain format items that are specific to each validation attribute and represent their parameters. For example, the minimum length for the MinLenghtAttribute or the minimum and maximum for the RangeAttribute.


Was this page helpful?