Walkthrough: Adding a new language to the Business Tools user interface

Version: 10.3

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 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 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:

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.

Add a new language to the Sitecore system settings

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:

In the Content Editor, go to /sitecore/System/Languages.
Right-click and then click Insert, Language.
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 new language is added to the content tree.
Click Save to save your changes.

Add a new language to the Commerce Control Panel

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:

In the Content Editor, go to /sitecore/Commerce/Commerce Control Panel/Shared Settings/Language Sets/Defaults.
In the Commerce Control Panel section, double-click the new language you just added to move it to the Selected column.
Click Save to save your change.

Synchronize content path

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:

In Postman, execute the Sync content path sample request.

Note

Ensure to clear the Redis cache after the item synchronization operation completes.
In Microsoft IIS Manager, restart the Commerce Engine application.
In Microsoft IIS Manager, restart the Business Tools application.

Add the language to the Commerce Engine GlobalEnvironment policy

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:

Go to the \inetpub\wwwroot\CommerceAuthoring_Sc\wwwroot\data\Environments.
Open the PlugIn.<catalog name>.CommerceAuthoring-1.0.0.json file.

In the Sitecore.Commerce.Core.GlobalEnvironmentPolicy section, in the Languages section, add the new language to the language set and save the file.

RequestResponse

{
        "$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"
          ]
        },

Using Postman, bootstrap the Commerce Engine.
Using Postman, clear the <catalog>Shops environment cache.
In the Content Editor, click the Commerce tab and click Refresh Commerce Cache.
Clear the Browser cache.
Open the IIS Manager and restart Commerce Engine Authoring.

Create a .JSON language file

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:

RequestResponse

{
    "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:

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.
Open the file and replace the English language strings with the translated strings.
Save the file.

Register a new language ID and recompile the Business Tools application

If you created a new JSON file in the previous step , 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 to properly display in the user interface.

Note

This procedure assumes that you have set up and deployed the Sitecore.BizFX.SDK in your development environment.

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

In your development environment, open the Sitecore.BizFX.SDK folder, and then open the src/app/app.module.ts file.

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

RequestResponse

/* 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);
/**

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

Do you have some feedback for us?

If you have suggestions for improving this article,