Admin UI localization

Xperience allows you to localize the administration interface, enabling users to select their preferred working language.

Export system localization resources

Xperience includes a dotnet utility to export all system localization resources (Xperience’s default UI strings) to .resx files. This is useful when creating translations for new languages – you can export the default resources as a starting point for translation.

dotnet run --no-build -- --kxp-export-localization-resources --export-path {path}

The export always contains the default en-US localization and all registered languages.

Export options

# Exports all resources to a local directory
dotnet run --no-build -- --kxp-export-localization-resources --export-path "./localization-export"

# Exports only system resources 
dotnet run --no-build -- --kxp-export-localization-resources --export-path "./system-resources" --system-only

Export output structure

The export creates a structured directory with .resx files organized by resource type:

{export-path}/
├── en-US/
│   ├── system/
│   │   ├── localization.client.en-US.resx
│   │   ├── localization.server.en-US.resx
│   │   └── localization.builder.en-US.resx
│   └── custom/
│       ├── localization.client.en-US.resx
│       ├── localization.server.en-US.resx
│       └── localization.builder.en-US.resx
└── {language}
    └───

Each exported .resx file contains different types of localization resources:

• localization.client.en-US.resx – Contains strings used in client-side JavaScript/TypeScript admin components, such as button labels, validation messages, and UI text that appears in the browser. Client resources are bundled and sent to the browser when the admin UI loads, making them immediately available on the client.
• localization.server.en-US.resx – Contains strings used in server-side C# admin code, including API responses, server-generated messages, and backend validation text. These resources are resolved dynamically by the backend as part of API responses and request lifecycle processing.
• localization.builder.en-US.resx – Contains strings specific to builder components, including widget names, property labels, and builder-specific UI elements.

The custom folder contains external resources registered using the RegisterLocalizationResource attribute.

Translation workflow

The approach you take for translating admin UI resources depends on your specific goals and target audience.

Create a default localization package

To create a general-purpose localization package for the admin UI:

1. Export system resources using --system-only to get Xperience’s English strings:

   CMD

   Export system resources

   Copy

   
    dotnet run --no-build -- --kxp-export-localization-resources --export-path "./system-resources" --system-only
    

2. Translate the resources to your target language.

3. Package and distribute the translations as a NuGet package for others to use.

This approach creates a focused translation package containing only the default resources, making it suitable for sharing and reuse across different projects.

Translate everything for local consumption

If your goal is to fully localize your specific application, including all custom resources:

1. Export all resources to obtain all strings that need to be localized:

   CMD

   Export all resources

   Copy

   
    dotnet run --no-build -- --kxp-export-localization-resources --export-path "./localization-export"
    

2. Translate both system and custom .resx files to your target language, covering all admin UI text in your application.

3. Translate custom Froala logic.

4. Register the translated resources in your application using the registration API, including both system and custom translations.

5. Configure the new languages in AdminLocalizationOptions.

This approach ensures complete localization coverage for your specific application, including any custom components or extensions you’ve developed.

Register localized resources

To add custom localization resources for your admin UI translations, create and register .resx resource files using the conventional .NET approach.

1. Create a new .NET resource file in your custom assembly. See Create resource files for .NET apps.

2. Register the resource file using the RegisterLocalizationResource attribute:

   C#

   Register localization resources

   Copy

   
    using CMS.Localization;
   
    // Register resources for additional languages
    [assembly: RegisterLocalizationResource(typeof(LocalizationClient), LocalizationTarget.Client, "cs-CZ")]
    [assembly: RegisterLocalizationResource(typeof(LocalizationClient), LocalizationTarget.Client, "de-DE")]
   
    namespace Acme.Web.Admin;
   
    // Class encapsulating the localization resource files
    public class LocalizationClient {}
    

   The RegisterLocalizationResource attribute accepts an optional LocalizationTarget parameter to specify whether resources are used on the client-side, server-side, or in builder components. If not specified, defaults to LocalizationTarget.Server. For more details about the LocalizationTarget enum, see Integrate custom code.

Distribute localization files

You can distribute your translations as NuGet packages. This approach allows other developers to easily include your translations.

1. Structure your project (typically a custom class library) to include the translated resource files and their registration.

2. Package the translation using dotnet pack, and distribute:

   CMD

   Create NuGet package

   Copy

   
   dotnet pack --configuration Release --output ./packages
   

Configure available languages for users

Use the AdminLocalizationOptions class to configure available languages for the administration interface. Users can choose from the available languages on the profile page.

The following code sample demonstrates the configuration:

using CMS.Localization;

var builder = WebApplication.CreateBuilder(args);

// Configures admin UI localization
builder.Services.Configure<AdminLocalizationOptions>(options =>
{
    options.DefaultCultureCode = "en-US";
    options.SupportedCultures = new[]
    {
        new AdminCulture
        {
            CultureCode = "en-US",
            DisplayName = "English (United States)"
        },
        new AdminCulture
        {
            CultureCode = "cs-CZ",
            DisplayName = "Czech (Czech Republic)"
        },
        new AdminCulture
        {
            CultureCode = "de-DE",
            DisplayName = "German (Germany)"
        }
    };
});

AdminLocalizationOptions properties

AdminCulture properties

new AdminCulture
{
    CultureCode = "de-DE",
    DisplayName = "German date and time formatting",
    // Uses English UI text with German formatting
    UseDefaultSystemUICulture = true
}

Access localized resources

When localizing your custom code and components, use the following APIs.

Back-end

Access registered resource strings using ILocalizationService:

// Contains instance resolved using dependency injection
private readonly ILocalizationService localizationService;

// Gets localized string for current UI culture
var message = localizationService.GetString("myproject.admin.users.createButton");

// Gets localized string for specific culture
var germanMessage = localizationService.GetString("myproject.admin.users.createButton", "de-DE");

Front-end

Client-side admin code uses the i18n library instead of ILocalizationService. The i18n library is automatically initialized with the current user’s preferred admin UI culture and provides access to client-side localization resources.

Access localized strings in React components using the useTranslation hook from react-i18next:

import { useTranslation } from 'react-i18next';

export const MyAdminComponent = () => {
    const { t } = useTranslation();

    return (
        <div>
            <h1>{t('myproject.admin.users.title')}</h1>
            <button>{t('myproject.admin.users.createButton')}</button>
            <p>{t('myproject.validation.emailRequired')}</p>
        </div>
    );
};

See the i18n documentation for a full usage guide and other resources.

Accessing globalization context

Use the useGlobalization hook to access the current admin UI culture information, including both resource string culture and datetime format culture.

The useGlobalization hook provides:

• uiLanguage – The culture code used for resource string localization (matches admin UI language selection).
• uiLocale – The culture code used for datetime and number formatting (respects the UseDefaultSystemUICulture setting).

import { useGlobalization } from '@kentico/xperience-admin-base';

export const MyAdminComponent = () => {
    const { uiLanguage, uiLocale } = useGlobalization();

    return (
        <div>
            <p>Current UI language: {uiLanguage}</p>
            <p>Current UI locale: {uiLocale}</p>
        </div>
    );
};

This is particularly useful when you need to format dates, numbers, or other culture-specific content in your React components while maintaining consistency with the admin UI’s localization settings.

Builder components

For builder elements that are used exclusively within the administration interface (such as widget configuration dialogs, or Page Builder inline editors), use IAdminBuildersLocalizationService:

@using Kentico.PageBuilder.Web.Mvc
@using Kentico.Web.Mvc
@using Kentico.Builder.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.SelectedNumber))
{
    <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("my.project.editors.numbereditor.add")
        </button>
        <button id="sub-btn" type="button">
            @localizationService.GetString("my.project.editors.numbereditor.subtract")
        </button>
    </div>
}

For content that appears on the live site, use the framework’s IHtmlLocalizer API.

Admin UI fields

Fields in the admin UI support localization expression in the format: {$ resource.key $}

These expression automatically resolve to a matching string based on the language currently selected by the user. If the localization is not found in the target language, the expression resolves according to Resource string resolution and fallbacks.

For example, the following screenshot demonstrates the localization of field metadata via the field editor (label, explanation text, etc.).

In the editing interface of the corresponding object, the expression resolves to the underlying string.

Froala rich text editor

The Froala rich text editor supports localization to match the user’s preferred admin UI language. The localization system works on multiple levels to ensure both system and custom elements are properly translated.

Default editor localization

By default, the editor automatically localizes its interface based on the user’s culture provided from the backend. The editor supports multiple languages out of the box, as documented in the Froala languages documentation.

The editor automatically applies the appropriate language pack when all of the following conditions are met:

• The user has set a preferred admin UI language in their profile
• The language is supported by Froala’s default language packs

If the language is not supported by Froala, the editor defaults to English (en-US).

Localize system customizations

Xperience’s customizations to the Froala editor (such as custom toolbar buttons and features) are not covered by Froala’s default localization. These strings are located inside localization.client.en-US.resx in the exported resources and must be translated as part of your localization efforts.

Localize custom configurations

For custom rich text editor configurations , you can use localization macros to translate custom options and display names.

The corresponding resource strings must be registered in a resource file with LocalizationTarget.Server.

Rich text editor configurations support localization macros in the format {$resource.key$}. This allows you to reference registered resource strings for any option with a custom display name. For example, when localizing text for inline styles, you can use the macros like so:

{
  "toolbarButtons": [
    "bold", "italic", "underline", "|", "inlineStyle", "customButton"
  ],
  "inlineStyles": {
    "{$mycompany.editor.redBoldText$}": "font-size: 16px; font-weight: bold; color: red;",
    "{$mycompany.editor.blueItalicText$}": "font-style: italic; color: blue;",
    "{$mycompany.editor.highlightText$}": "background-color: yellow; padding: 2px;"
  }
}

Resource string resolution and fallbacks

The localization logic uses a multi-step fallback process to resolve resource strings when a specific localized string is not available:

1. User preferred culture – The system first attempts to load the resource string using the user’s preferred admin UI language (if set in their profile). If no user preference is set, the system uses the DefaultCultureCode specified in AdminLocalizationOptions.

2. English fallback (en-US) – If the resource string is not found in the selected culture, the system falls back to English (en-US).

3. Resource key display – If no localized string is found in English, the system displays the resource key itself as a last resort.

This cascading fallback helps ensure users see meaningful text in the admin UI even if some resources remain untranslated.

Example fallback scenario

Consider a user with Czech (cs-CZ) as their preferred language, and an application configured with German (de-DE) as the default culture:

1. System looks for the resource key in Czech (cs-CZ) resources (user’s preference).
2. If the translated resource isn’t found, the system falls back directly to English (en-US) resources.
3. If the key doesn’t exist in English, the system displays the resource key itself.

If the user had no preferred language set, the system would use German (de-DE) in the first step instead of Czech.