--- 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. ## 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. ```cmd title="Export command syntax" dotnet run --no-build -- --kxp-export-localization-resources --export-path {path} ``` The export always contains the default `en-US` localization and all [registered languages](#register-localized-resources). ### Export options | Option | Description | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--export-path` | **(Required)** The directory path where .resx files will be created. | | `--system-only` | **(Optional)** Exports only the default system resources. When not provided, the utility exports both system and custom resources.
The system treats all external resources registered using the [RegisterLocalizationResource](https://docs.kentico.com/documentation/developers-and-admins/customization/integrate-custom-code.md#store-application-resources-in-resource-files) attribute as custom resources. | | `--skip-confirmation` | **(Optional)** Skips the confirmation prompt before export. | ```cmd title="Examples of usage" # 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: ```text noheader {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](https://docs.kentico.com/documentation/developers-and-admins/development/builders.md) components, including widget names, property labels, and builder-specific UI elements. The _custom_ folder contains external resources registered using the [RegisterLocalizationResource](https://docs.kentico.com/documentation/developers-and-admins/customization/integrate-custom-code.md#store-application-resources-in-resource-files) attribute. ## Translation workflow The approach for translating admin UI resources depends on specific goals and target audience. ### Create a default localization package To create a general-purpose localization package for the admin UI: 1. [Export](#export-system-localization-resources) system resources using `--system-only` to get Xperience's English strings: ```cmd title="Export system resources" 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](#distribute-localization-files) 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](#export-system-localization-resources) all resources to obtain all strings that need to be localized: ```cmd title="Export all resources" 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. > **Info:** **Naming convention** > > Custom projects are not required to follow the naming convention used in exported files; use naming conventions that fit your project structure. For an example, see the [finished branch of our Training guides repository](https://github.com/Kentico/xperience-by-kentico-training-guides/tree/finished/src/TrainingGuides.Admin/Localization/Resources). 3. Translate [custom Froala logic](#froala-rich-text-editor). 4. Register the translated resources in your application using the [registration API](#register-localized-resources), including both system and custom translations. 5. Configure the new languages in [AdminLocalizationOptions](#configure-available-languages-for-users). This approach ensures complete localization coverage for your specific application, including any custom components or extensions you've developed. > **Note:** **Translation volume and tooling** > > Note that exported system resources contain thousands of localization strings. Professional translation tools or AI-powered translation services handle this volume efficiently. When using AI tools, process resources in manageable batches and have a language professional review the results to ensure accuracy and proper context. ## Maintain translations across updates Xperience by Kentico [updates](https://docs.kentico.com/documentation/developers-and-admins/installation/update-xperience-by-kentico-projects.md) may add, modify, or remove system resource strings. If you maintain admin UI translations in a language other than English, review and update your translations after each update. > **Note:** **Translations do not update automatically** > > When Xperience modifies the English text of an existing resource string, your translations for that key remain unchanged. This means the translated UI may display outdated or incorrect text until you manually update the affected translations. ### How updates affect translations Resource string changes in an update can impact your translations in the following ways: - **New keys** – The system falls back to English automatically. No immediate action is required, but you may want to translate new strings for a consistent experience. - **Modified keys** – Your translation still uses the old text. The UI may display a meaning that no longer matches the actual behavior (e.g., a button translated as "Delete" when the action now moves items to the recycle bin). - **Changed format parameters** – If the English string added or removed format placeholders (e.g., `{0}`), your translation with mismatched placeholders can cause runtime errors. - **Removed keys** – Unused translations remain in your _.resx_ files without causing issues, but you can remove them to reduce clutter. ### Update translations after an update Follow this procedure to identify and fix affected translations after updating Xperience: 1. **Before updating**, export system resources as a baseline for comparison: ```cmd title="Export pre-update resources" dotnet run --no-build -- --kxp-export-localization-resources --export-path "./pre-update-resources" --system-only ``` 2. **Perform the Xperience update** following the [standard update process](https://docs.kentico.com/documentation/developers-and-admins/installation/update-xperience-by-kentico-projects.md). 3. **After updating**, export system resources again from the updated project: ```cmd title="Export post-update resources" dotnet run --no-build -- --kxp-export-localization-resources --export-path "./post-update-resources" --system-only ``` 4. **Compare the two exports** to identify added, modified, and removed resource strings. Use a diff tool or [source control system](https://en.wikipedia.org/wiki/Revision_control). The following example uses [Git](https://git-scm.com/): ```cmd title="Compare exported resources (git)" git diff --no-index ./pre-update-resources ./post-update-resources ``` 5. **Update affected translations** in your localized _.resx_ files to reflect the new meaning and format of changed strings. > **Tip:** **Automate your translations** > > We recommend using AI-powered translation tools to batch-analyze the diff and automatically produce updated translations for changed strings. ## Register localized resources To add custom localization resources for your admin UI translations, create and register _.resx_ resource files using the [conventional .NET approach](https://learn.microsoft.com/en-us/dotnet/core/extensions/create-resource-files). 1. Create a new .NET resource file in your [custom assembly](https://docs.kentico.com/documentation/developers-and-admins/customization/integrate-custom-code.md). See [Create resource files for .NET apps](https://learn.microsoft.com/en-us/dotnet/core/extensions/create-resource-files). 2. Register the resource file using the [RegisterLocalizationResource](https://docs.kentico.com/documentation/developers-and-admins/customization/integrate-custom-code.md#store-application-resources-in-resource-files) attribute: ```csharp title="Register localization resources" 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](https://docs.kentico.com/documentation/developers-and-admins/customization/integrate-custom-code.md#store-application-resources-in-resource-files). > **Info:** **Project configuration for multiple language variants** > > When registering multiple language variants using a single registration class (as shown in the example), configure the `LogicalName` property in the project's _.csproj_ file to map _.resx_ files to the registration class. See the [TrainingGuides.Admin project](https://github.com/Kentico/xperience-by-kentico-training-guides/blob/finished/src/TrainingGuides.Admin/TrainingGuides.Admin.csproj) for an example. > > Alternatively, place each _.resx_ file next to its own _.cs_ registration class, which requires a separate class per variant but no _.csproj_ configuration. > **Note:** **English resources are optional** > > English (`en-US`) _.resx_ files are not required in the project unless overriding Xperience's default English strings is necessary. The system uses built-in English resources automatically. Register English resources only when customizing or replacing the default English text. ## 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](#register-localized-resources). 2. Package the translation using `dotnet pack`, and distribute: ```cmd title="Create NuGet package" dotnet pack --configuration Release --output ./packages ``` ## 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(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`. | | SupportedCultures | `IEnumerable` | 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 in the format "language-region" (e.g., "en-US", "cs-CZ", "de-DE"). | | DisplayName | `string` | The display name shown to users in the language selector. If not provided, uses the culture's native display name. | | UseDefaultSystemUICulture | `bool` | Indicates whether the default system UI culture provided by Kentico (en-US) will be used. This is used to set a different date format while preserving the default en-US translations provided by Kentico.
`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](https://api-reference.kentico.com/api/CMS.Core.ILocalizationService.html): ```csharp title="Using localized strings in admin components" // 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](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](#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 (

{t('myproject.admin.users.title')}

{t('myproject.validation.emailRequired')}

); }; ``` See the [i18n documentation](https://react.i18next.com/) 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). ```tsx title="useGlobalization example" import { useGlobalization } from '@kentico/xperience-admin-base'; export const MyAdminComponent = () => { const { uiLanguage, uiLocale } = useGlobalization(); return (

Current UI language: {uiLanguage}

Current UI locale: {uiLocale}

); }; ``` 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](#configure-available-languages-for-users). ### Builder components For [builder](https://docs.kentico.com/documentation/developers-and-admins/development/builders.md) elements that are used exclusively within the administration interface (such as widget configuration dialogs, or Page Builder inline editors), use `IAdminBuildersLocalizationService`: ```cshtml title="Using IAdminBuildersLocalizationService in inline editors" @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)) {
} ``` For content that appears on the live site, use the framework's `IHtmlLocalizer` API. > **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. ### 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](#resource-string-resolution-and-fallbacks). 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) (label, explanation text, etc.). ![Localization expression usage](https://docs.kentico.com/docsassets/documentation/admin-ui-localization/localization_expressions.png "Localization expression usage") In the editing interface of the corresponding object, the expression resolves to the underlying string. ![Localized field value](https://docs.kentico.com/docsassets/documentation/admin-ui-localization/localization_example.png "Localized field value") ### Froala rich text editor The [Froala rich text editor](https://docs.kentico.com/documentation/business-users/rich-text-editor.md) supports localization to match the user's [preferred admin UI language](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md). 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](https://froala.com/wysiwyg-editor/languages/). 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](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md#export-system-localization-resources) and must be translated as part of your localization efforts. #### Localize custom 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), you can use localization macros to translate custom options and display names. The corresponding resource strings must be registered in a [resource file](https://docs.kentico.com/documentation/developers-and-admins/customization/integrate-custom-code.md#store-application-resources-in-resource-files) 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](https://froala.com/wysiwyg-editor/examples/inline-styles/), you can use the macros like so: ```json title="Example - Localized custom configuration" { "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](#adminlocalizationoptions-properties). 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. ## 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.