---
title: Localize custom admin UI code
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).

When you [extend the administration interface](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface.md), display the texts of your customizations in the user's preferred admin UI language. Store the texts in [registered resource files](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/register-localization-resources.md) and retrieve them in your back-end and client-side code, or reference them using localization expressions in texts the system displays for you, such as field labels.

## Retrieve strings in back-end code

Access registered resource strings using [ILocalizationService](https://api-reference.kentico.com/api/CMS.Core.ILocalizationService.html). The service reads strings registered for the `LocalizationTarget.Server` and `LocalizationTarget.Builder` [targets](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/register-localization-resources.md#choose-the-localization-target).

```csharp title="Using localized strings in admin components"
using CMS.Core;

public class UserButtonLabels(ILocalizationService localizationService)
{
    // Gets the localized string for the current UI culture
    public string GetCreateLabel() =>
        localizationService.GetString("myproject.admin.users.createButton");

    // Gets the localized string for a specific culture
    public string GetGermanCreateLabel() =>
        localizationService.GetString("myproject.admin.users.createButton", "de-DE");
}
```

### Format resource strings with placeholders

To insert values into a resource string with placeholders, such as `{0}`, use the `GetStringFormat` extension method for `ILocalizationService` from the `CMS.Helpers` namespace. The method gets the string for the current UI culture and formats it with the given arguments using the standard `String.Format` method.

```csharp title="Formatting localized strings with placeholders"
using CMS.Core;
using CMS.Helpers;

public class UserMessageProvider(ILocalizationService localizationService)
{
    /* Formats a resource string such as "User {0} was deleted."
       for the current UI culture. */
    public string GetDeletedMessage(string userName) =>
        localizationService.GetStringFormat("myproject.admin.users.deleted", userName);
}
```

If a translation can't be formatted with the given arguments, for example, because the translation contains a `{1}` placeholder but the code passes only one argument, `GetStringFormat` formats the English (`en-US`) string instead. The method also logs a warning with the `LocalizedStringFormatFailed` event code to the [event log](https://docs.kentico.com/documentation/developers-and-admins/configuration/event-log.md). If the English string can't be formatted with the given arguments either, the method throws a `FormatException`.

We recommend using `GetStringFormat` instead of calling `String.Format` on the result of `GetString`.

## Retrieve strings in client-side code

[Client-side admin code](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface.md) uses the [i18n library](https://react.i18next.com/) instead of `ILocalizationService`. The i18n library is automatically initialized with the current user's [preferred admin UI culture](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md#resource-string-resolution-and-fallbacks) and provides access to client-side localization resources.

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

```tsx title="Using localized strings in React admin components"
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>
    );
};
```

For a full usage guide and other resources, see the [i18n documentation](https://react.i18next.com/).

> **Info:** **Resource key consistency**
>
> Use the same resource keys in both your _.resx_ files and client-side code. The admin UI automatically loads client-side resources (registered with `LocalizationTarget.Client`) and makes them available to the i18n library.

### Access the 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. For cultures with `UseDefaultSystemUICulture` enabled, contains the default system culture (`en-US`).
- `uiLocale` – The culture code used for datetime and number formatting. Contains the `CultureCode` of the user's admin UI language.

```tsx title="useGlobalization example"
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>
    );
};
```

Use the hook to format dates, numbers, or other culture-specific content in your React components consistently with the admin UI's [localization settings](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md#configure-available-languages-for-users).

## Localization expressions

Many texts in the admin UI support localization expressions in the format `{$resource.key$}`. An expression resolves to the matching resource string in the user's admin UI language, according to [Resource string resolution and fallbacks](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md#resource-string-resolution-and-fallbacks). You can use the expressions in:

- Field metadata defined in the [field editor](https://docs.kentico.com/documentation/developers-and-admins/customization/field-editor.md) (label, explanation text, etc.).
- Texts defined in code, for example, the labels and explanation texts of editing components, or the names and descriptions of [builder components](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/localize-builder-components.md).

For example, the following screenshot demonstrates the localization of field metadata via the [field editor](https://docs.kentico.com/documentation/developers-and-admins/customization/field-editor.md).

![Field editor with the expression {$my.resource.string$} entered in the Field caption field](https://docs.kentico.com/docsassets/documentation/localize-custom-admin-code/localization_expressions.png "Localization expression usage")

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

![Editing form in which the field label reads 'Resolved field label', the string that the expression resolves to](https://docs.kentico.com/docsassets/documentation/localize-custom-admin-code/localization_example.png "Localized field value")

The following example localizes the label and explanation text of an editing component:

```csharp title="Editing component with a localized label and explanation text"
using Kentico.Xperience.Admin.Base.FormAnnotations;

namespace MyProject.Admin;

public class ContactFormModel
{
    [TextInputComponent(
        Label = "{$myproject.admin.contactform.email.label$}",
        ExplanationText = "{$myproject.admin.contactform.email.explanation$}",
        Order = 1)]
    public string Email { get; set; }
}
```

Store the strings in a resource file [registered](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/register-localization-resources.md) for `LocalizationTarget.Server`, or for `LocalizationTarget.Builder` when the texts belong to [builder components](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/localize-builder-components.md). Strings registered only for `LocalizationTarget.Client` don't resolve in localization expressions.

## Localize rich text editor configurations

For [custom rich text editor configurations](https://docs.kentico.com/documentation/developers-and-admins/configuration/rich-text-editor-configuration/rich-text-editor-customization.md#create-and-use-custom-editor-configurations), use [localization expressions](#localization-expressions) to translate custom options and display names. Register the corresponding resource strings in a resource file for `LocalizationTarget.Server`.

The expressions work in any option with a custom display name. For example, the following configuration localizes the names of [inline styles](https://froala.com/wysiwyg-editor/examples/inline-styles/):

```json title="Example -- Localized custom configuration"
{
    "toolbarButtons": [
        "bold", "italic", "underline", "|", "inlineStyle", "customButton"
    ],
    "inlineStyles": {
        "{$myproject.editor.redBoldText$}": "font-size: 16px; font-weight: bold; color: red;",
        "{$myproject.editor.blueItalicText$}": "font-style: italic; color: blue;",
        "{$myproject.editor.highlightText$}": "background-color: yellow; padding: 2px;"
    }
}
```

The editor's own interface and Xperience's editor customizations are part of the system translation. See [Translate the rich text editor](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/translate-the-admin-ui.md#translate-the-rich-text-editor).