---
title: "Walkthrough: Adding a new language to the Business Tools user interface"
slug: "walkthrough--adding-a-new-language-to-the-business-tools-user-interface"
abstract: "How to add a language to Sitecore so that you can display the XC Business Tools user interface in a language other than English, German or Japanese."
---
# Walkthrough: Adding a new language to the Business Tools user interface

The default language of the Sitecore XC Business Tools user interface is English, but you can set up the Business Tools to display the interface in the language of your choice. To display the Commerce Business Tools in a language other than those Sitecore makes available as downloads (that is Danish, Japanese, and German), follow the procedures in this walkthrough.

> [!note]
> Sitecore and the XC Business Tools are preconfigured to support Japanese, Danish and German language IDs and locales. To display the Business Tools interface in one of those languages, you can simply [download and install](https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-commerce/install-a-translation-file-for-the-xc-business-tools.html "Install a translation file for the XC Business Tools") the language resource files. You do not need to follow procedures in this walkthrough.
>
> For any other language support, you must provide the XML translation file and [upload it](https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-commerce/install-a-translation-file-for-the-xc-business-tools.html "Install a translation file for the XC Business Tools") in Sitecore before performing this walkthrough.
>
> If the translation file for the language selected in the Business Tools is not installed, the Business Tools user interface defaults to English.

This walkthrough describes how to:

- [Add a new language to Sitecore settings](https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-commerce/walkthrough--adding-a-new-language-to-the-business-tools-user-interface.html#UUID-d922e464-bb46-be82-e876-5f38d317c587_section-idm4479625703592031645852718634 "Add a new language to the Sitecore system settings")
- [Add a new language to the Commerce Control Panel](https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-commerce/walkthrough--adding-a-new-language-to-the-business-tools-user-interface.html#UUID-d922e464-bb46-be82-e876-5f38d317c587_section-idm4540676706457631645896629276 "Add a new language to the Commerce Control Panel")
- [Synchronize content path](https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-commerce/walkthrough--adding-a-new-language-to-the-business-tools-user-interface.html#UUID-d922e464-bb46-be82-e876-5f38d317c587_section-idm4550549033332831645926685878 "Synchronize content path")
- [Add the language to the Commerce Engine GlobalEnvironment policy](https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-commerce/walkthrough--adding-a-new-language-to-the-business-tools-user-interface.html#UUID-d922e464-bb46-be82-e876-5f38d317c587_section-idm231858525113129 "Add the language to the Commerce Engine GlobalEnvironment policy")
- [Create a .JSON language file](https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-commerce/walkthrough--adding-a-new-language-to-the-business-tools-user-interface.html#UUID-d922e464-bb46-be82-e876-5f38d317c587_section-idm231747867988757 "Create a .JSON language file")
- [Register a new language ID and recompile the Business Tools application](https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-commerce/walkthrough--adding-a-new-language-to-the-business-tools-user-interface.html#UUID-d922e464-bb46-be82-e876-5f38d317c587_section-idm231752917697329 "Register a new language ID and recompile the Business Tools application")

At the end of this walkthrough, you can open the Sitecore XC Business Tools, and use the language selector to display the user interface in the newly installed language.

<details>
<summary><h2>Add a new language to the Sitecore system settings</h2></summary>

You must add the new language in Sitecore system settings so that the new language code and associated country/region code become available for configuration within Sitecore.

To add a language to Sitecore system settings:

1. In the Content Editor, go to */sitecore/System/Languages*.
2. Right-click and then click **Insert, Language**.
3. In the **Add a New Language** dialog box, in the **Choose a predefined language code** field, select the language code you want to use, complete the remaining fields as required, click **Next** to step through the remaining pages of the Wizard. When you are finished, click **Close**.

    ![The Add a New Language dialog box in Sitecore Content Editor.](https://doc.sitecore.com/api/markdown-image/xp/en/developers/103/sitecore-experience-commerce/images/XMC_CE_language.png)

    The new language is added to the content tree.

4. Click **Save** to save your changes.

</details>

<details>
<summary><h2>Add a new language to the Commerce Control Panel</h2></summary>

You add a new language to the Commerce Control Panel so that the language is available in Sitecore Experience Commerce.

To add a new language to the Commerce Control Panel:

1. In the Content Editor, go to */sitecore/Commerce/Commerce Control Panel/Shared Settings/Language Sets/Defaults*.
2. In the **Commerce Control Panel** section, double-click the new language you just added to move it to the **Selected** column.

    ![The language selector in the Commerce Control Panel.](https://doc.sitecore.com/api/markdown-image/xp/en/developers/103/sitecore-experience-commerce/images/XC_Commerce_Language_Sets.png)

3. Click Save to save your change.

</details>

<details>
<summary><h2>Synchronize content path</h2></summary>

As a result of making the new language available in the Commerce Control Panel, new content items were created in Sitecore. In order for these new items to be visible in the Commerce Engine, and by extension, in the Business Tools, you must synchronize the content using the `Sync content path` sample request in Postman.

To synchronize the content path:

1. In Postman, [execute the Sync content path sample request](https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-commerce/synchronize-content-items.html "Synchronize content items").

    > [!note]
    > Ensure to clear the Redis cache after the item synchronization operation completes.

2. In Microsoft IIS Manager, restart the Commerce Engine application.
3. In Microsoft IIS Manager, restart the Business Tools application.

</details>

<details>
<summary><h2>Add the language to the Commerce Engine GlobalEnvironment policy</h2></summary>

In order for the Commerce Engine to recognize the new language, you need to add the language code to the `Sitecore.Commerce.Core.GlobalEnvironmentPolicy` policy file and then bootstrap the Commerce Engine.

To add the language to the Commerce Engine:

1. Go to the `\inetpub\wwwroot\CommerceAuthoring_Sc\wwwroot\data\Environments`.
2. Open the `PlugIn.<catalog name>.CommerceAuthoring-1.0.0.json` file.
3. In the `Sitecore.Commerce.Core.GlobalEnvironmentPolicy` section, in the Languages section, add the new language to the language set and save the file.

    ```csharp
    {
            "$type": "Sitecore.Commerce.Core.GlobalEnvironmentPolicy, Sitecore.Commerce.Core",
            "Languages": {
              "$type": "System.Collections.Generic.List`1[[System.String, mscorlib]], mscorlib",
              "$values": [
                "en",
                "de-DE",
                "ja-JP",
                "fr-FR"
              ]
            },
    ```

4. Using Postman, [bootstrap](https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-commerce/bootstrap-the-commerce-engine.html "Bootstrap the Commerce Engine") the Commerce Engine.
5. Using Postman, clear the <catalog>Shops environment cache.
6. In the Content Editor, click the **Commerce** tab and click **Refresh Commerce Cache**.
7. Clear the Browser cache.
8. Open the IIS Manager and restart Commerce Engine Authoring.

</details>

<details>
<summary><h2>Create a .JSON language file</h2></summary>

In addition to the XML file containing the translation of the Business Tools interface labels (which contains the bulk of the user interface labels), a .JSON language file is used to translate a few more labels and validation error messages (a total of 9 additional strings). If you want to have the entire Business Tools user interface translated, you must create the required language .JSON file and have the additional labels translated.

> [!note]
> Optionally, for a simplified localization process, you can skip this procedure. If you do not create a JSON file for the new language, the Business Tools displays these additional 9 strings in English.
>
> All other labels translated within the language XML file (which represent most of the interface) do not require additional steps and will display in the newly configured language.

The following is a sample of the content of the language JSON file for English ( `en.json` file), showing the additional label strings:

```csharp
{
    "ValidationErrors": {
        "IsRequired": "{{DisplayName}} is required.",
        "IncorrectDecimalValue": "{{DisplayName}} has an incorrect decimal value.",
        "IncorrectDateValue": "{{DisplayName}} has an incorrect date value."
    },
    "ActionExecuted": "{{DisplayName}} executed.",
    "Back": "Back",
    "Logout": "Log out",
    "LanguageSelector": "Language displayed",
    "NoSearchResults": "No results matching your search were found.",
    "Searching": "Searching..."
}

```

> [!note]
> Sitecore XC includes .JSON files for the following languages: English (`en.json`), German (`de-DE.json`), French (`fr-FR.json`) and Japanese (`ja-JP.json`).

To create .JSON language file for another language:

1. On the server where the Business Tools are installed, go to `c:/inetpub/wwwroot/SitecoreBizFxSite\assets\i18n`, and copy one of the existing file, (for example, the `en.json` file), and rename the file to reflect the name of the required language, for example `es-ES.json` for Spanish.
2. Open the file and replace the English language strings with the translated strings.
3. Save the file.

</details>

<details>
<summary><h2>Register a new language ID and recompile the Business Tools application</h2></summary>

If you created a new JSON file in the [previous step](https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-commerce/walkthrough--adding-a-new-language-to-the-business-tools-user-interface.html#UUID-d922e464-bb46-be82-e876-5f38d317c587_section-idm231747867988757 "Create a .JSON language file") , then you must register the new language and recompile the application. The portion of the XC Business Tools user interface translated in the JSON language file relies on the [Angular localization framework](https://angular.io/guide/i18n) to properly display in the user interface.

> [!note]
> This procedure assumes that you have [set up and deployed the Sitecore.BizFX.SDK](https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-commerce/walkthrough--getting-started-with-business-tools-customization.html "Walkthrough: Getting started with Business Tools customization") in your development environment.

To register a new language ID and locale in the Business Tools application:

1. In your development environment, open the `Sitecore.BizFX.SDK` folder, and then open the `src/app/app.module.ts` file.
2. In the section of the file named `/* Locales */`, add the additional language.

    The following example shows added support for the Spanish language ID (es) and locale (ES).

    ```javascript
    /* Locales */
    import localeFr from '@angular/common/locales/fr';
    import localeFrExtra from '@angular/common/locales/extra/fr';
    import localeJa from '@angular/common/locales/ja';
    import localeJaExtra from '@angular/common/locales/extra/ja';
    import localeDe from '@angular/common/locales/de';
    import localeDeExtra from '@angular/common/locales/extra/de';
    import localeEs from '@angular/common/locales/es';
    import localeEsExtra from '@angular/common/locales/extra/Es';

    registerLocaleData(localeFr, 'fr-FR', localeFrExtra);
    registerLocaleData(localeJa, 'Ja-JP', localeJaExtra);
    registerLocaleData(localeDe, 'de-DE', localeDeExtra);
    registerLocaleData(localeEs, 'es-Es', localeEsExtra);
    /**
    ```

3. Save your changes to call the Angular `import` and `registerLocaleData(...)` functions.
4. Recompile the Business Tools (BizFx) application.

</details>