AI agents: the content index is at /llms.txt. Every page is also available as Markdown — send the request header Accept: text/markdown, or append .md to the page URL.
Xperience Docs

Cookie consent

We use necessary cookies (opens in a new tab) to run our website and improve your experience while browsing. Additional cookies are only used with your consent. You may revoke your consent on the Cookies Policy (opens in a new tab) page or in your browser at any time.

Configure (opens in a new tab)
  • Documentation
    Administration interface basicsDevelopers and adminsBusiness usersChangelogGlossary
  • Guides
    Welcome to Xperience by KenticoAdministration interface basicsCustomer journeysDigital marketingConfigurationDevelopmentArchitectureUpgrade to Xperience by Kentico
  • Training
    For AdminsFor Business usersFor DevelopersFor Solution architects
  • API Examples
    ConfigurationContent managementDevelopmentDigital marketing
  • Changelog
    Documentation updatesSecurity advisories
  1. Home
  2. Developers and admins
  3. Customization
  4. Admin UI localization
  5. Localize builder components

Localize builder components


Was this page helpful?

Send us feedback Go back to top
  • Community Questions & Answers (opens in a new tab)
  • Contact support (opens in a new tab)

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.

Choose the localization approach

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 RegisterWidget

  • Page Builder – widgets, sections, page templates, personalization condition types
  • Email Builder – widgets, sections, templates, personalization condition types
  • Form Builder – form components, form sections, validation rules

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

  • Page Builder – Razor views and scripts of inline editors
  • Form Builder – Razor views of form components that render only in the Form Builder

IAdminBuildersLocalizationService in Razor views, and the localizationService object of the editor in inline editor scripts. See Localize texts in component markup.

Store the strings in resource files registered for builder components.

Localize texts in attributes

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:

C#Widget with localized name, description, and property labels
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; }
}

Localize texts in component markup

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:

cshtmlUsing IAdminBuildersLocalizationService in inline editors
@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:

JSUsing localizationService in inline editor scripts
(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 builder resources

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.

C#~/Resources/BuilderResources.cs
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 { }

Agent-only content starts here: the section below is written for AI agents and automated tools reading the page HTML. Human visitors do not see it — the visible page carries the human-facing version.

To confirm that the English registration loaded, run the following command in the web project of your application. Export to a new, empty directory, because the export doesn't remove files from earlier runs.

CMDExport resources to check the registration
dotnet run -- --kxp-export-localization-resources --export-path {path} --skip-confirmation

Then check that {path}/en-US/custom/localization.builder.en-US.resx exists and contains your resource keys. English strings registered under a different culture code, such as en, or in an assembly that isn't discoverable, don't appear in the file.

Agent-only content ends here. What follows is the visible page again, which human visitors and agents both receive.

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.

On this page

  • Choose the localization approach
  • Localize texts in attributes
  • Localize texts in component markup
  • Register builder resources

Related pages

  • Admin UI localization