Working with localizations - XMPieLab/uStore-NG GitHub Wiki

uStore themes can be localized to support all cultures that are available for the Storefront. The translation of texts in an NG store is either of dynamic text per store (e.g. category names, products names) or theme static text, which is identical in all themes. All out-of-the-box texts in the system are saved in the DB and retrieved from the server upon loading of the application.

Note: When developing a localized theme, add all the required cultures to a test store in the Backoffice, so you can select them in the Storefront and test the translated texts.

It is possible to add text to the theme for newly developed areas. First you need to prepare the infrastructure for translating the text using the existing localization mechanism. After adding the support for text translation, the text appears with the default “[no localization]”, which denotes that the translation is not available yet. Once the text is translated and added to the theme, the correct translation appears according to the selected culture.

Let’s look at this process using an example from the ContactUs page we’ve previously added.

1. Open the src\components\Layout\Header\index.js file and locate the link you’ve already added (Contact Us).
2. Change the Contact Us text to:

<div className="right-icons">
  <div style={{marginRight: '20px', width: '90px'}}>
    <Link to={urlGenerator.get({page:'contact-us'})}>
      <a>{t('Header.Contact_us')}</a>
    </Link>
  </div>
…

We’ve used the internal function t(), which gets as a parameter the localization key for the string to be translated.

3. Check in your browser that this text (in the English culture) has changed to “[no localization]”.
4. Open the src\localizations\en-US.json file (the localization file for en-US) and add in the curly brackets the following line:

{ "Header.Contact_us":"Contact Us en-US" }

The localization file is constructed of a json object that has key-value pairs - a localization key and its translation. Repeat this for every localization file in each culture that you wish the theme to support.

NOTE: The localization key can hold any text which is legal in json. It is recommended to keep the notation of the prefix Page/Component name, followed by a dot and a unique identifier for the text.

5. Check in your browser that the text has changed to “Contact Us en-US”.

Before publishing the theme, don’t forget that the correct translation should be supplied as the value of the key in this json object, and should be filled for all cultures relevant for this theme in the appropriate localization files. The localization files should be part of the theme so they can be published with the theme package.

In case a theme should support a culture which is not one of uStore’s out-of-the-box cultures, it is possible to add the culture to the theme and then add customized localization keys and text to the newly developed areas of the application.

If there is no new text, there is no need to add the culture to the theme, since the store administrator can add the translated text to existing localization keys from the Backoffice. The localization infrastructure of the theme then takes care of fetching the translations from the DB.

When adding a new culture to a theme, you must make sure that the required culture is defined in the Backoffice and assigned to the store.

If the culture is not defined for the store, follow these steps:

1. In uStore Backoffice go to Presets > Localizations, click New and add the required culture. For example Bulgarian-Bulgaria.
2. In the Cultures Sections window, click Resources > Save and then Back. (You can also reach this window by clicking the Translate icon in the Localization – Culture List window.)
3. Open your test store and go to Store Setup > Appearance tab and add the culture.
4. Click Save and Place Online.

Now the culture is available in the store. When previewing the store (from the Backoffice or in a development environment), you will see that the culture has been added to the Culture dropdown list located in the store’s header, and is available for selection. If you select the culture, you can see that the static text which has no translation shows the default “[no localization]” text.

Add the culture to the theme:

1. Open the src\components\Layout\Header\index.js file and locate the link you’ve already added (Contact Us).
2. Change the Contact Us text to:

<div className="right-icons">
  <div style={{marginRight: '20px', width: '90px'}}>
    <Link to={urlGenerator.get({page:'contact-us'})}>
      <a>{t('Header.Contact_us')}</a>
    </Link>
  </div>
…

We’ve used the internal function t(), which gets as a parameter the localization key for the requested string to translate.

3. Create a json file under src\localizations, similar to the other culture files. The name of the file should be the culture code of this culture that can be found in the Presets > Localization window in the Backoffice. In this example the file name should be bg-BG.json. Place the following lines in the file and save it:

{ "Header.Contact_us":"Contact Us bg-BG" }

4. Open the src\localizations\index.js file and add a declaration for the new culture file as follows:

import enUs from './en-US'
import frFr from './fr-FR'
import deDE from './de-DE'
import jaJP from './ja-JP'
import enGB from './en-GB'
import esES from './es-ES'
import nlNL from './nl-NL'
import ptBR from './pt-BR'
import bgBG from './bg-BG'

…

const localizations = {
  'en-US' : i18n.create({ values: fixTranslationValues(enUs) }),
  'fr-FR' : i18n.create({ values: fixTranslationValues(frFr) }),
  'de-DE' : i18n.create({ values: fixTranslationValues(deDE) }),
  'ja-JP' : i18n.create({ values: fixTranslationValues(jaJP) }),
  'en-GB' : i18n.create({ values: fixTranslationValues(enGB) }),
  'es-ES' : i18n.create({ values: fixTranslationValues(esES) }),
  'nl-NL' : i18n.create({ values: fixTranslationValues(nlNL) }),
  'pt-BR' : i18n.create({ values: fixTranslationValues(ptBR) }),
  'bg-BG' : i18n.create({ values: fixTranslationValues(bgBG) })
}

5. Check your browser to see whether when changing the language to Bulgarian, the text of the link in the header indeed changes to “Contact Us bg-BG”.

Don’t forget, before publishing the theme, that the correct translation should be supplied as the value of the key in this json object in the src\localizations\bg-BG.json file. The localization files should be part of the theme in order to be published with the theme package.

For a detailed example, watch the Localizing Theme text video on XMPie Campus.