---
title: Localize builder components
related:
  - https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

[Builder](https://docs.kentico.com/documentation/developers-and-admins/development/builders.md) 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<br>**Email Builder** – widgets, sections, templates, personalization condition types<br>**Form Builder** – form components, form sections, validation rules                                                                         | [Localization expressions](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/localize-custom-admin-code.md#localization-expressions). The system resolves them when it displays the texts. See [Localize texts in attributes](#localize-texts-in-attributes). |
| Labels, explanation texts, and tooltips of editing components               | Properties classes of the components in the previous row                                                                                                                                                                                                                                                                  | [Localization expressions](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/localize-custom-admin-code.md#localization-expressions). The system resolves them when it displays the texts. See [Localize texts in attributes](#localize-texts-in-attributes). |
| Texts in your own markup, shown only to editors                             | **Page Builder** – Razor views and scripts of [inline editors](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/inline-editors-for-widget-properties.md)<br>**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](#localize-texts-in-component-markup).                                                                                              |

Store the strings in resource files [registered for builder components](#register-builder-resources).

## Localize texts in attributes

Use [localization expressions](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/localize-custom-admin-code.md#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:

```csharp title="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](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/inline-editors-for-widget-properties.md), retrieve the strings using `IAdminBuildersLocalizationService`. The service returns the strings in the user's admin UI language:

```cshtml title="Using 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:

```js title="Using 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](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/localization/make-content-localizable).

## 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](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md#configure-available-languages-for-users), and the English strings under the `SystemContext.SYSTEM_CULTURE_NAME` constant, which the system uses as the fallback. See [Culture codes](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md#culture-codes).

If the registration class is in a class library, the assembly must be [discoverable](https://docs.kentico.com/documentation/developers-and-admins/customization/integrate-custom-code.md#enable-class-discovery). Otherwise, the system ignores the registrations without an error. The web project of your application is discoverable automatically.

```csharp title="~/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 { }
```

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.

```cmd title="Export 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.

To reuse strings registered for another target, for example, `LocalizationTarget.Server` strings shared with custom admin code, see [Choose the localization target](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/register-localization-resources.md#choose-the-localization-target), which lists the texts of each target.