---
title: Admin UI localization
---

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

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

> **Info:** **Admin UI vs. content localization**
>
> Admin UI localization affects only the administration interface (buttons, menus, labels, etc.). This is different from [Languages](https://docs.kentico.com/documentation/developers-and-admins/configuration/languages.md), which manages language versions of your content.

This page covers the configuration and rules that apply to all admin UI localization: the languages available to users, how the system works with culture codes, and how it resolves resource strings. For specific localization scenarios, see:

- [Translate the admin UI](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/translate-the-admin-ui.md) – Export the system resources, translate them, keep the translations up to date after Xperience updates, and distribute them as a NuGet package.
- [Register localization resources](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/register-localization-resources.md) – Register _.resx_ files in the system and choose the localization target for each file.
- [Localize custom admin UI code](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/localize-custom-admin-code.md) – Retrieve resource strings in back-end and client-side admin code, and use localization expressions.
- [Localize builder components](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/localize-builder-components.md) – Localize the names, descriptions, properties, and markup of Page Builder, Form Builder, and Email Builder components.

## Configure available languages for users

Use the `AdminLocalizationOptions` class to configure available languages for the administration interface. This configuration determines which languages appear in the language selector dropdown on the [profile page](https://docs.kentico.com/documentation/business-users/manage-your-user-profile.md), allowing users to choose their preferred admin UI language.

> **Info:** **English language configuration**
>
> English (`en-US`) must be explicitly included in the `SupportedCultures` collection to be available as a language option, even when the project does not include English _.resx_ files. The system uses built-in English resources automatically, but users can only select English if configured in `SupportedCultures`.

The following code sample demonstrates the configuration:

```csharp title="Configure admin UI localization (Program.cs)"
using Kentico.Xperience.Admin.Base;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddKentico( ... );

// Configures admin UI localization - must be placed after the AddKentico call to ensure localization services are registered
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

| Property           | Type                        | Description                                                                                                                                                                                                                         |
| ------------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DefaultCultureCode | `string`                    | The default culture code used when no user preference is set or when the preferred language is unavailable (e.g., on the admin UI sign-in page). Must be present in `SupportedCultures`. Otherwise, the application fails to start. |
| SupportedCultures  | `IEnumerable<AdminCulture>` | Collection of cultures available for the administration interface.                                                                                                                                                                  |

> **Info:** **Default content language vs. Default admin UI language**
>
> When editing content in the administration interface, content items are displayed in the default content language configured in [Languages](https://docs.kentico.com/documentation/developers-and-admins/configuration/languages.md), regardless of the admin UI language set in `DefaultCultureCode`.

### AdminCulture properties

| Property                  | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CultureCode               | `string` | The culture code, for example, `en-US`, `cs-CZ`, or `de-DE`. See [Culture codes](#culture-codes).                                                                                                                                                                                                                                                                                                            |
| DisplayName               | `string` | The display name shown to users in the language selector. If not provided, uses the culture's display name in the language of the .NET runtime (`CultureInfo.DisplayName`).                                                                                                                                                                                                                                  |
| UseDefaultSystemUICulture | `bool`   | Indicates whether users of this culture see the English strings of the [default system culture](#default-system-culture) (`en-US`). Use it to set a different date format while keeping the English texts.<br>`new AdminCulture
{
    CultureCode = "de-DE",
    DisplayName = "German date and time formatting",
    // Uses English UI text with German formatting
    UseDefaultSystemUICulture = true
}` |

## Culture codes

Admin UI localization identifies each language by its culture code, a .NET culture name such as `es-ES`. We recommend codes in the "language-region" format. For culture names, see the [CultureInfo class](https://learn.microsoft.com/en-us/dotnet/api/system.globalization.cultureinfo) documentation. You use culture codes in the `CultureCode` property when you [configure the admin UI languages](#configure-available-languages-for-users), and when you [register resource files](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/register-localization-resources.md). The following rules apply to culture codes:

- **Culture codes are not case-sensitive** – For example, `es-ES` and `es-es` identify the same language.
- **Registered culture codes must match exactly** – The system matches the culture of the user against the culture codes of the registered resource files. A language doesn't match its regional variants. For example, strings registered under `en` don't resolve for `en-US` users, and strings registered under `es-ES` don't resolve for `es-MX` users. The system logs no error in these cases, and the strings use the [fallback](#resource-string-resolution-and-fallbacks). If the default system culture doesn't contain the key either, the admin UI shows the resource key. Register each resource file under the culture codes of your admin UI languages. If you don't configure `AdminLocalizationOptions`, the only admin UI language is the [default system culture](#default-system-culture).
- **Missing strings fall back to more general resource files** – When a registration matches the user's culture, the system looks up each string in the file for the full culture code first, then in the file for the language alone, and then in the file without a culture code. For example, for a registration under `es-ES`, the system reads _X.es-ES.resx_, then _X.es.resx_, then _X.resx_.

### Default system culture

The `SystemContext.SYSTEM_CULTURE_NAME` constant (in the `CMS.Base` namespace) contains the culture code of the default system culture, English (`en-us`, which the system treats as `en-US`). Xperience registers its built-in English strings under this culture, so your project doesn't need English _.resx_ files for the system strings.

Register a resource file under `SystemContext.SYSTEM_CULTURE_NAME`, instead of a culture code you write yourself, when you want to:

- **Add default strings for your own resource keys** – The system displays the strings to users of the default system culture, and uses them as the fallback for admin UI languages that don't translate the keys.
- **Change Xperience's default English strings** – Strings registered under the constant replace the system strings with the same resource keys. Register the file for the same [localization target](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/register-localization-resources.md#choose-the-localization-target) as the replaced strings. The name of each [exported](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/translate-the-admin-ui.md#export-output-structure) system file shows its target.

For registration examples, see [Register localization resources](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/register-localization-resources.md).

## 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), including the more general resource files of a matching registration (see [Culture codes](#culture-codes)). If no user preference is set, the system uses the `DefaultCultureCode` specified in [AdminLocalizationOptions](#adminlocalizationoptions-properties).

2. **English fallback** (`en-US`) – If the resource string is not found in the selected culture, the system falls back to the English strings registered under the [default system culture](#default-system-culture).

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.

![The user's culture leads to the strings of the exact culture code, then the English strings, then the resource key. UseDefaultSystemUICulture skips straight to the English strings.](https://docs.kentico.com/docsassets/documentation/admin-ui-localization/string-resolution.drawio.svg "How the admin UI resolves a resource string")

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

## Example implementation

For an admin UI localization implementation example, see the [finished branch of the Training guides repository](https://github.com/Kentico/xperience-by-kentico-training-guides/tree/finished). The example includes localized custom [Page Builder widget](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder.md), a custom [UI page](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-pages.md), and sample localizations in Spanish and French. The localization resources are defined in the _TrainingGuides.Admin_ project.

> **Note:** **Demo translations only**
>
> The Spanish and French resource strings in the Training guides example are machine-translated for demonstration purposes only and may not be grammatically accurate. These translations are not suitable for production use.