Localizing MVC builder components

If you want to allow administration interface users to experience the page builder or form builder MVC features in their preferred UI culture, you can localize the used components. To cover the whole interface, you need to localize the following:

• Metadata of the builder components
• Partial views of inline property editors
• Client scripts of inline editors

This page describes localization of the administration interface. To learn how to localize content displayed by widgets on the live site, visit Localizing content on MVC sites.

Localizing builder component metadata

You can localize the displayed text of form builder components (form components, form builder sections, field validation rules, field visibility conditions) and page builder components (widgets, page builder sections, personalization condition types, page templates):

1. Create resource strings containing the Display names and Descriptions of your components.

   • Use a unique prefix for the resource string key, for example, your company name. The prefix prevents possible conflicts with the resource strings of other components.
   • We recommend including the component’s identifier as a part of the resource string key.
   Portability of the components

   To allow for portability of the components, it is recommended to store resource strings within separate resx files for each component. The recommended location for such files is _{/App_Data/Global/Resources/<FileName>.resx. For cultures other than the default culture, use folder} /App_Data/Global/Resources/<CultureCode>/<FileName>.resx. For example, ~/App_Data/Global/Resources/es-ES/NumeroWidget.resx for the Spanish culture.

2. Edit the class containing the given component’s registration attribute, and add {$key$} expressions into the text parameters of the attribute (such as name and description). Replace “key” with the key of the matching resource string.

   Example - Localizing a page builder section

   Copy

   
   
   
    [assembly: RegisterSection("Company.DefaultSection", typeof(DefaultSectionController), "{$company.defaultsection.name$}", IconClass = "icon-paragraph", Description = "{$company.defaultsection.description$}")]
   
   
    

Localizing partial views

You can localize strings in partial views that are only displayed in the administration interface. For example, the text of a widget property inline editor button:

1. Create resource strings for the text you want to localize.

   • Use a unique prefix for the resource string key, for example, your company name. The prefix prevents possible conflicts with the resource strings of other components.
   • We recommend including the component’s identifier as a part of the resource string key.
   Portability of the components

   To allow for portability of the components, it is recommended to store resource strings within separate resx files for each component. The recommended location for such files is  ~/App_Data/Global/Resources/<FileName>.resx . For cultures other than the default culture, use folder  _{/App_Data/Global/Resources/<CultureCode>/<FileName>.resx. For example,}  /App_Data/Global/Resources/es-ES/NumeroEditor.resx  for the Spanish culture.

2. Retrieve the resource string value in partial views using the ResHelper.GetString(stringName, cultureCode) method available in the CMS.Helpers namespace. It is important to specify the culture code parameter using the MembershipContext.AuthenticatedUser.PreferredUICultureCode value available in the CMS.Membership namespace. This enures that the resource string is displayed in the preferred UI culture of the user.

   Copy

   
   
   
    @ResHelper.GetString("resource.string.key", MembershipContext.AuthenticatedUser.PreferredUICultureCode)
   
   
    

Localizing inline editor scripts

To localize strings in the client scripts of widget property inline editors:

1. Create resource strings for the text you want to localize. Use a unique prefix for the key, for example, your company name. The prefix prevents possible conflicts with other resource strings.

   Resource string location

   Resource strings used for inline editor scripts must be placed in resx files in the ~/App_Data/Global/Resources folder.

   • Default culture: ~/App_Data/Global/Resources/<FileName>.resx
   • Other cultures: ~/App_Data/Global/Resources/<CultureCode>/<FileName>.resx (e.g., ~/App_Data/Global/Resources/es-ES/NumeroEditor.resx )

   The localization service available within the inline editor registration function only loads resource strings from this location.

2. Retrieve resource string values in the inline editor scripts using the localizationService available via the options object in the inline editor registration function.

   Example - Inline property editor script

   Copy

   
   
   
    (function () {
      window.kentico.pageBuilder.registerInlineEditor("custom-editor", {
        init: function (options) {
            // Retrieves the localized text of the specified resource string (in the current user's preferred UI culture)
            var localizedString = options.localizationService.getString("resource.string.key");
   
            ...
        }
      });
    })();
   
   
    

   Tip: You can also retrieve the culture code of the current administration interface user’s preferred UI culture from the localizationService.cultureCode property. This might be useful if you need to pass the current culture to a JavaScript utility, for example a date picker.

After you localize component metadata, partial views and inline editor scripts, you can view the result in the Kentico administration interface. Change the UI language by opening the User menu and clicking on Change language. Navigate to a page where the page builder is initialized (in the Pages application) or the form builder (in the Forms application). Now text values in the user interface are displayed in the selected language.