---
title: Localize the widget (optional)
---

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

## Localize the widget (optional)

If you are [localizing your Admin UI](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md) into other languages, you can localize the widget's name, description, and property labels so editors see them in their preferred language.

The localization process has two parts: first, you'll replace hardcoded strings in your code with localization expressions. Then, you'll define the actual translations in resource (`.resx`) files and register them with Xperience, as described in the [Admin UI localization documentation](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md#register-localized-resources).

For a complete example of a localized widget, see the [CallToAction sample widget in the finished branch](https://github.com/Kentico/xperience-by-kentico-training-guides/tree/finished/src/TrainingGuides.Web/Features/LandingPages/Widgets/CallToAction) of the Training guides repository.

### Localize widget properties

To localize the widget's configuration interface, update widget property annotations to use [localization expressions](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md#admin-ui-fields) in the format `{$ resource.key $}`.

Here's an example showing how to localize the `Label` and `ExplanationText` for one property in the Service widget:

```csharp title="ServiceWidgetProperties.cs (localized example)" highlight="10-11"
using ...

namespace TrainingGuides.Web.Features.FinancialServices.Widgets.Service;

public class ServiceWidgetProperties : IWidgetProperties
{
    ...
    [ContentItemSelectorComponent(
        ServicePage.CONTENT_TYPE_NAME,
        Label = "{$TrainingGuides.ServiceWidget.SelectedServicePage.Label$}",
        ExplanationText = "{$TrainingGuides.ServiceWidget.SelectedServicePage.ExplanationText$}",
        MaximumItems = 1,
        Order = 30)]
    public IEnumerable<ContentItemReference> SelectedServicePage { get; set; } = [];
    ...
}
```

You'll need to apply this pattern to all properties in the class that have user-facing strings.

### Localize widget registration

Next, localize how the widget appears in the Page Builder widget selector. Use localization expressions in the widget registration attribute for the widget's name and description:

```csharp title="ServiceWidgetViewComponent.cs (localized registration)" highlight="6,8"
using ...

[assembly: RegisterWidget(
    identifier: ServiceWidgetViewComponent.IDENTIFIER,
    viewComponentType: typeof(ServiceWidgetViewComponent),
    name: "Service",
    propertiesType: typeof(ServiceWidgetProperties),
    Description = "{$TrainingGuides.ServiceWidget.Description$}",
    IconClass = "icon-ribbon")]

namespace TrainingGuides.Web.Features.FinancialServices.Widgets.Service;

public class ServiceWidgetViewComponent(IContentItemRetrieverService contentItemRetrieverService,
        IComponentStyleEnumService componentStyleEnumService,
        IServicePageService servicePageService,
        IContentTypeService contentTypeService) : ViewComponent
{
    ...
```

### Define resource strings

After adding localization expressions to your code, create the corresponding resource strings in `.resx` files. For example:

```xml title="LocalizationCustom.en-US.resx"
...
<data name="TrainingGuides.ServiceWidget.Name">
  <value>Service</value>
</data>
<data name="TrainingGuides.ServiceWidget.SelectedServicePage.Label">
  <value>Select service page</value>
</data>
...
```

> **Tip:** **Use AI agents to accelerate localization**
>
> AI assistants like GitHub Copilot can significantly speed up the localization process. For example:
>
> - Manually write the localization expression for the first property, then let Copilot infer the pattern for the remaining properties.
> - Use a prompt like the following to generate both the localized code and resource file entries:
>
> ```text
> For this widget properties class, perform two tasks:
>
> 1) Replace all hardcoded Label, ExplanationText, and Options strings with localization expressions in the format {$TrainingGuides.ServiceWidget.{PropertyName}.{ParameterType}$} (e.g., {$TrainingGuides.ServiceWidget.SelectedServicePage.Label$}).
>
> 2) Generate a .resx file with XML entries for each replaced string, using the original hardcoded values. Include entries from [RadioGroupComponent], [ContentItemSelectorComponent], [CheckBoxComponent], [DropDownComponent], and [TextInputComponent] attributes.
>
> Provide both the updated C# code and the complete .resx XML content.
> ```
>
> This approach reduces repetitive work while maintaining consistency across your localized content.
>
> Note that this is just an example prompt. Adjust it to match your project's naming conventions and specific needs, and provide the AI agent with the relevant code context.
>
> **We recommend using the [Xperience by Kentico Documentation MCP server](https://docs.kentico.com/documentation/developers-and-admins/installation/mcp-server.md) to help AI agents better understand Xperience widgets and localization patterns.**