Builder components (in Page Builder, Form Builder, and Email Builder) display texts to editors in the administration interface. Localize the texts so editors see them in their preferred admin UI language.
The texts come from different sources, and each source uses a different localization approach:
Text | Used in | Approach |
|---|---|---|
Names and descriptions in registration attributes, such as |
| Localization expressions. The system resolves them when it displays the texts. See Localize texts in attributes. |
Labels, explanation texts, and tooltips of editing components | Properties classes of the components in the previous row | Localization expressions. The system resolves them when it displays the texts. See Localize texts in attributes. |
Texts in your own markup, shown only to editors |
|
|
Store the strings in resource files registered for builder components.
Use localization expressions in the format {$resource.key$} in place of the texts. The following example localizes the name, description, and a property label of a widget:
using Kentico.PageBuilder.Web.Mvc;
using Kentico.Xperience.Admin.Base.FormAnnotations;
using MyProject.Widgets;
[assembly: RegisterWidget(
identifier: "MyProject.Widgets.Hero",
name: "{$myproject.widgets.hero.name$}",
propertiesType: typeof(HeroWidgetProperties),
customViewName: "~/Components/Widgets/Hero/_Hero.cshtml",
Description = "{$myproject.widgets.hero.description$}",
IconClass = "icon-badge")]
namespace MyProject.Widgets;
public class HeroWidgetProperties : IWidgetProperties
{
[TextInputComponent(
Label = "{$myproject.widgets.hero.heading.label$}",
ExplanationText = "{$myproject.widgets.hero.heading.explanation$}",
Order = 1)]
public string Heading { get; set; }
}For texts rendered in Razor views that only editors see, such as the buttons of inline editors, retrieve the strings using IAdminBuildersLocalizationService. The service returns the strings in the user's admin UI language:
@using Kentico.Builder.Web.Mvc
@using Kentico.PageBuilder.Web.Mvc
@using Kentico.Web.Mvc
@* Injects the localization service for admin UI components *@
@inject IAdminBuildersLocalizationService localizationService
@model LearningKitCore.Components.PageBuilder.InlineEditors.NumberEditor.NumberEditorModel
@using (Html.Kentico().BeginInlineEditor("number-editor", Model.PropertyName))
{
<div style="position: absolute; top: 0px; right: 0px;">
<button id="add-btn" type="button">
@* Gets the localized string using current admin UI culture *@
@localizationService.GetString("myproject.editors.numbereditor.add")
</button>
<button id="sub-btn" type="button">
@localizationService.GetString("myproject.editors.numbereditor.subtract")
</button>
</div>
}In the scripts of inline editors, retrieve the strings using the localizationService object, which the init function of the editor receives in its options parameter. The getString method returns the string in the user's admin UI language, falls back to the English string, and otherwise returns the resource key:
(function () {
window.kentico.pageBuilder.registerInlineEditor("number-editor", {
init: function (options) {
var addButton = options.editor.querySelector("#add-btn");
addButton.title = options.localizationService.getString(
"myproject.editors.numbereditor.add.tooltip");
}
});
})();The scripts receive only strings registered for LocalizationTarget.Builder. Resource keys in scripts are case-sensitive, unlike keys that the system resolves on the server.
For content that appears on the live site, use ASP.NET Core localization, for example, IHtmlLocalizer (opens in a new tab).
Register the resource files with the builder strings for LocalizationTarget.Builder. The system resolves these strings both on the server and in the browser, so they work for every text on this page. Register each file under the culture codes of your admin UI languages, and the English strings under the SystemContext.SYSTEM_CULTURE_NAME constant, which the system uses as the fallback. See Culture codes.
If the registration class is in a class library, the assembly must be discoverable. Otherwise, the system ignores the registrations without an error. The web project of your application is discoverable automatically.
using CMS.Base;
using CMS.Localization;
using MyProject.Resources;
[assembly: RegisterLocalizationResource(
typeof(BuilderResources),
LocalizationTarget.Builder,
SystemContext.SYSTEM_CULTURE_NAME)]
[assembly: RegisterLocalizationResource(
typeof(BuilderResources),
LocalizationTarget.Builder,
"es-ES")]
namespace MyProject.Resources;
// Corresponding .resx files: BuilderResources.resx, BuilderResources.es-ES.resx
public class BuilderResources { }To reuse strings registered for another target, for example, LocalizationTarget.Server strings shared with custom admin code, see Choose the localization target, which lists the texts of each target.