---
title: Translate the admin UI
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).

To offer the administration interface in a new language, translate Xperience's default UI strings and the strings of your own customizations. Export the strings to _.resx_ files, translate them, and register the translations in your project. After each Xperience update, review the translations for changed strings. To share a translation with other projects, distribute the translated files as a NuGet package.

For the languages available to users and how the system resolves translated strings, see [Admin UI localization](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md).

## Export system localization resources

Xperience includes a `dotnet` utility to export all system localization resources (Xperience's default UI strings) to _.resx_ files. When you create a translation for a new language, export the default resources as a starting point.

```cmd title="Export command syntax"
dotnet run --no-build -- --kxp-export-localization-resources --export-path {path} --skip-confirmation
```

The export asks for confirmation before it starts. With no interactive console attached, the prompt can't be answered and the command fails instead of exporting anything, with `System.InvalidOperationException: Cannot read keys when either application does not have a console or when console input has been redirected. Try Console.Read.`

The export contains the English (`en-US`) strings, which serve as the source for translation.

### Export options

| Option                | Description                                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--export-path`       | **(Required)** The directory path where the export creates the _.resx_ files.                                                                                                                                                                                                                                                                                                                          |
| `--system-only`       | **(Optional)** Exports only the default system resources. When not provided, the utility exports both system and custom resources.<br>The system treats all external resources registered using the [RegisterLocalizationResource](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/register-localization-resources.md) attribute as custom resources. |
| `--skip-confirmation` | **(Optional)** Skips the confirmation prompt before export.<br>Pass this parameter whenever no interactive console is attached. Without it, the command fails at the unanswerable confirmation prompt and exports nothing.                                                                                                                                                                             |

```cmd title="Examples of usage"
# Exports all resources to a local directory
dotnet run --no-build -- --kxp-export-localization-resources --export-path "./localization-export" --skip-confirmation

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

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

Each exported _.resx_ file contains the resources of one [localization target](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/register-localization-resources.md#choose-the-localization-target). The export creates a file only for targets that contain 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 back-end validation text. These resources are resolved dynamically by the back end 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 English resources registered with the [RegisterLocalizationResource](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/register-localization-resources.md) attribute under `en-US` or the `SystemContext.SYSTEM_CULTURE_NAME` constant. Resources registered under other culture codes, such as `en`, don't appear in the export. With `--system-only`, the export doesn't create the folder.

## 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 --skip-confirmation
   ```

2. Translate the resources to your target language.

3. Package and distribute the translations to other projects as a [NuGet package](#distribute-localization-files).

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 every string for localization:

   ```cmd title="Export all resources"
   dotnet run --no-build -- --kxp-export-localization-resources --export-path "./localization-export" --skip-confirmation
   ```

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 don't need to follow the naming convention of the 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 the [rich text editor](#translate-the-rich-text-editor) interface.

4. [Register](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/register-localization-resources.md) the translated resources in your application, including both system and custom translations. Register each file for the localization target shown in the name of its exported file, under the culture codes of your admin UI languages. For the rules, see [Culture codes](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md#culture-codes).

5. Configure the new languages in [AdminLocalizationOptions](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md#configure-available-languages-for-users).

This approach ensures complete localization coverage for your specific application, including your own custom components and extensions.

> **Tip:** **Translation volume and tooling**
>
> 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.

### Translate the rich text editor

The [Froala rich text editor](https://docs.kentico.com/documentation/business-users/rich-text-editor.md) displays its interface in the user's preferred admin UI language. The editor's texts come from two sources:

- **Froala's own interface** – The editor applies the matching language pack from Froala's default language packs, as documented in the [Froala languages documentation](https://froala.com/wysiwyg-editor/languages/). If Froala doesn't support the language, the editor uses English (`en-US`).
- **Xperience's customizations** – Custom toolbar buttons and other features that Xperience adds to the editor aren't covered by Froala's language packs. Their strings are located inside _localization.client.en-US.resx_ in the [exported resources](#export-system-localization-resources). Translate them together with the other system strings.

To localize the options of your own editor configurations, see [Localize rich text editor configurations](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/localize-custom-admin-code.md#localize-rich-text-editor-configurations).

## 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 don't update automatically**
>
> When Xperience modifies the English text of an existing resource string, your translations for that key remain unchanged. As a result, 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 displays the English string instead, or throws an error in code that formats strings without `GetStringFormat`.
- **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

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 --skip-confirmation
   ```

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 --skip-confirmation
   ```

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.

## 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](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/register-localization-resources.md). The class library must be [discoverable](https://docs.kentico.com/documentation/developers-and-admins/customization/integrate-custom-code.md#enable-class-discovery). Otherwise, the system ignores its registrations without an error.

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

   ```cmd title="Create NuGet package"
   dotnet pack --configuration Release --output ./packages
   ```