Localizing builder components

✖
Copy to clipboard

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

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

Prerequisite

In order to use localization in your MVC project, you need to set up the project to correctly recognize cultures.

Page and form builder components consist of multiple parts that all need to be localized if you wish to cover the whole interface. We recommend creating a separate resource file for each component.

Before you start localizing your component:

  1. Create a dedicated resource file.

    1. Create a dummy class that “wraps” the resource file and serves as its access point for the framework. The namespace of the class must correspond to its location on the file system minus its name. 

      


 // For example, for resource files located under ~/MyProject/ComponentResources/MyComponent, set MyProject.ComponentResources as the namespace
 namespace relative.path.to.file
 {       
     // Dummy class for 'MyComponent.resx' or 'MyComponent.<culture code>.resx'
     public class MyComponent
     {
     }
 }

    2. Create the corresponding resource file in the same folder as the dummy class. The resource file name needs to match the name of the class and contain the language code of the target culture in its suffix. For example: MyComponent.es-es.resx. For resource strings in the default culture, the suffix can be omitted.

      • If a corresponding .resx file is not found for the current culture, a fallback mechanism that attempts to find the closest matching culture takes over. See Culture fallback behavior in the ASP.NET Core documentation.
  2. Register the dummy class via the RegisterPageBuilderLocalizationResource attribute.

    • The registration makes all localization strings available client-side as well. This is required when localizing client-side resources of inline editors and modal dialogs.

    • Specify the type of the dummy class and the culture for which the resources are intended as the attribute’s parameters.

      


  [assembly: RegisterPageBuilderLocalizationResource(typeof(MyComponent), "es-es")]

Now you can localize the component:

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
    


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

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.

  2. Edit the class containing the given component’s registration attribute and add {$key$} expressions into the string 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
    


 [assembly: RegisterSection("CompanyName.DefaultSection", "{$company.defaultsection.name$}", typeof(CustomSectionProperties), "~/Components/Sections/_MySection.cshtml", 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.

    


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

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.

  2. Localize the component’s view using standard localization classes provided by the framework (IStringLocalizer, IHtmlLocalizer, IViewLocalizer).

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
    


 (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.

  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.

  2. Access the registered resources via the localizationService property exposed by the options object provided by Xperience in the client-side init function.

    


 (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 Xperience 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.