--- title: "Localization | Customer's Canvas On-Premises" canonical: "https://customerscanvas.com/docs/on-premises/ui-framework/ui/localization/" --- # Localization > The UI Framework allows for the localization of custom text, standard widgets, and config elements. Some complex widgets have separate localization files. Translation descriptions in localization files have the JSON format and may contain several objects of key-value pairs. The object names represent two-letter codes of languages. Translation descriptions may look as follows: ```json { "en": { "common.loading.waiting": "Please wait ...", "common.loading.preload": "Loading, please wait...", "editor.buttons.finish": "Finish", "editor.buttons.next": "Next", "editor.buttons.back": "Back", "editor.buttons.help": "Help", "widgets.uploader.uploading": "Uploading...", ... }, "nl": { "common.loading.waiting": "Even geduld aub ...", "common.loading.preload": "Bezig met laden...", "editor.buttons.finish": "Af hebben", "editor.buttons.next": "Volgende", "editor.buttons.back": "Terug", "editor.buttons.help": "Helpen", "widgets.uploader.uploading": "Uploaden...", ... } ``` When you define a new localization, you can use any string as the language identifier. However, it's recommended to stick to [ISO 639-1 codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). You can add as many custom translations as you want. Just follow the key naming conventions: - Reflect the translation purpose in the key. - Separate words by a dot, for example, `"module.component.somekey"`. - Use standard module names and component names, for example, `"editor.buttons."`, `"widgets.option."`, `"steps.finish_button."`, and so on. ## Defining custom translations There are three ways to enable the UI Framework: - Install it locally through npm or get it as part of another application. - Use it from Azure CDN (Content Delivery Network) when running a deployed application. - Install it in BackOffice. Depending on which method you use, you can define your translations as follows: | |Local instance|CDN|BackOffice| |---|---|---|---| |[Changing the locales.json file](#in-localesjson-file)| ![check mark](images/check.png) | | |[Passing localizations to JavaScript methods](#through-javascript)| ![check mark](images/check.png) | ![check mark](images/check.png) | | |[Adding localizations to the config](#in-config-file)| ![check mark](images/check.png) | ![check mark](images/check.png) | ![check mark](images/check.png) | For the local instance, you should edit the **locales.json** file with translations. When you take the framework from CDN or implement custom integration with BackOffice, it's better to define translations through JavaScript. If you edit the config through BackOffice, then define the translations through the config as well. ### In locales.json file When you have deployed the UI Framework locally through `npm` or within other applications, like Preflight, then you have access to the **locales.json** file. To change translations on local deployment, you can just open and edit this file, which can be found in this path: `/ui-framework//locales.json` At the moment, the UI Framework provides the **locales.json** file with the English (`en`), Dutch (`nl`), German (`de`), French (`fr`), and Russian (`ru`) languages. Such widgets as `design-editor` or `preflight` have separate localization files with different sets of languages. For example, the Design Editor provides the English (`en`), Spanish (`es`), French (`fr`), and Russian (`ru`) languages, whereas the Preflight widget provides only English (`en`), Dutch (`nl`), and Russian (`ru`). When a localization or a single translation string is missing, then the UI Framework uses English. ### Through JavaScript When you are working with an on-premises instance of the UI Framework, you have access to JavaScript methods, which allow for changing the translations. To initialize your e-commerce driver, you call `driver.init()` with the following parameters. ``` js // Initialize an e-commerce driver. const ecommerce = await driver.init( product /* product definition */, editor /* editor instance */, config /* configuration */, settings /* data returned from the editor */, order /* order number, `null` to skip */, quantity /* quantity of items, if needed */, user /* user properties */, backOffice /* BackOffice settings */, themeSettings /* UI theme */, localization /* string resources of UI */ ); ``` This method accepts the `localization` array, which may contain a single definition or a set of definitions for different modules. ``` js const localization = [{ "app": "ui-framework", "data": { "en": { "editor.buttons.next": "Next step", "editor.buttons.back": "Previous step" }, "nl": { "editor.buttons.next": "Volgende stap", "editor.buttons.back": "Vorige stap" } } }]; const ecommerce = await driver.init( product, editor, config, settings, null, quantity, user, ...[,,], localization ); ``` In this example, we changed the captions of the **Next** and **Back** buttons in the UI Framework. Here, the `data` object redefines translations for both English and Dutch. Now, let's assume that we have created the **uif.json** and **preflight.json** files with localization and put them into the **translations** folder on your server. In this case, you can specify links to different localization files within an array as follows: ```js const localization = [ { "app": "ui-framework", "url": "http:///translations/uif.json" }, { "app": "preflight", "url": "http:///translations/preflight.json" } ]; const ecommerce = await driver.init( product, editor, config, settings, null, quantity, user, ...[,,], localization ); ``` Here, the `app` property specifies the application to which the new localization will be applied. You can specify one of the following values: `"ui-framework"` or `"preflight"`. Preparing a separate file is not always convenient, and when you need to change only a few captions in the current language, you can pass key-value pairs in `localization.data`. ```js const localization = { "app": "ui-framework", "data": { "editor.buttons.next": "Next step", "editor.buttons.back": "Previous step" } }; const ecommerce = await driver.init( product, editor, config, settings, null, quantity, user, ...[,,], localization ); ``` ### In config file If your only option is to edit configs, then you can change translations through the `localization` array in the same way as you define it through JavaScript. This array may contain a single definition or a set of definitions for different modules, for example: ```json { "localization": [{ "app": "ui-framework", "data": { "en": { "editor.buttons.next": "Next step", "editor.buttons.back": "Previous step" }, "nl": { "editor.buttons.next": "Volgende stap", "editor.buttons.back": "Vorige stap" } } }], ... } ``` :::note In BackOffice, you must first create a custom workflow, make the changes there, and then use this custom workflow when defining a product specification. When changing the config, you can only use identifiers (keys) of translations that are already defined in **locales.json**. To add new translations to the UI Framework, you must change the [**locales.json**](#in-localesjson-file) file. ::: If you don't allow your users to change the language of the UI, then you can use another format of `data` that will apply translations to the current language. For example: ```json { "localization": [{ "app": "ui-framework", "data": { "editor.buttons.next": "Volgende stap", "editor.buttons.back": "Vorige stap" } }], ... } ``` When you need to not only correct a couple of captions but also redefine a significant part of translations, you can organize them into a separate file and specify a local path or an external link to this file in the `localization.url` property in your config. Let's assume that you created a **uif.json** file with localization and put it into the same folder as **config.json**. In this case, you can expand **locales.json** with **uif.json** as follows: ```json { "localization": [{ "app": "ui-framework", "url": "uif.json" }], ... } ``` ## Selecting a language To change the language of the user interface, you can use the `language` property in your config. For example, for the Dutch interface, set: ```json { "language": "nl", "localization": [...], "widgets": [...], "steps": [...] } ``` This is how the English and Dutch interfaces will look. ![Preflight widget in English and Dutch.](images/localization-preflight.png) ## Localizing custom text To use a newly created translation in your config, you can use the `#localize` operator. For example, let's learn how you can translate the hard-coded names of the editor's steps in the Preflight Tool. First, open `/ui-framework//locales.json` and add the following translations to the end of `"en"` and `"nl"` objects. ```json { "en": { ... "steps.upload.name": "Upload", "steps.preflight.name": "Preflight", "steps.preview.name": "Preview" }, "nl": { ... "steps.upload.name": "Uploaden", "steps.preflight.name": "Preflight", "steps.preview.name": "Voorbeeld" } } ``` Now, you can use these translations in the user interface: open **config.json**, search for the `"steps"` section, and change the step names as follows: ```json "steps": [ { "name": "1. {{#localize steps.upload.name }}", ... }, { "name": "2. {{#localize steps.preflight.name }}", ... }, { "name": "3. {{#localize steps.preview.name }}", ... } ] ``` As a result, step names will look as follows. ![Applying localization to step names.](images/localization-steps.png) ## Localizing preflight Translations of the `preflight` widget are defined in the separate file **locales.json**. Depending on the UI Framework deployment, you can find this file in the following path: 1. When using a local instance: `/ui-framework//static/preflight/locales.json` 2. When using CDN or BackOffice: `https://staticjs-aurigma.azureedge.net/ui-framework//static/preflight/locales.json` :::note To find out which version is used in your BackOffice tenant, you can navigate to **Settings**, click the **General** tab, and copy the **URL** of UI Framework. To see the content of the localization file, you can just paste its link into the address bar of your browser. ::: To change the localization, you can use the same three methods as described for the [UI Framework](#defining-custom-translations), but specify `"preflight"` in the `app` property. For example, you can pass `localization` through JavaScript as follows: ```js const localization = { "app": "preflight", "data": { "topToolbar.uploadButton": "Upload", "uploader.errorTitle.back": "Error!" } }; const ecommerce = await driver.init( product, editor, config, settings, null, quantity, user, ...[,,], localization ); ``` ## Localizing design-editor The Design Editor widget has its own localization engine, and the UI Framework uses localization files deployed in your Design Editor instance. To localize this widget, you can refer to the [Design Editor localization](https://customerscanvas.com/docs/on-premises/design-editor/iframe-api/customization/localization.md) article.