Supporting multiple languages for your store

The Emerald and Sapphire Reference Store applications are enabled for multiple languages. All UI text, labels, and buttons for the Reference Store applications are translated. For more information about the languages supported by HCL Commerce, see Globalization prerequisites for installing HCL Commerce.

The data for UI text, labels, buttons, and so on is separated into JSON files and is available in key-value format where the application fetches a string to display based on its key in a specific language/locale. You can translate these JSON files to support any required languages.

When the key does not exist for a specific locale, the application falls back to a default language which is generally en_US. The Reference Store applications though do not have a UI component to switch languages within the Store itself.

Language parameter in the URL

Use the langId or locale parameter in the URL to indicate the required language.

For example, for the French language, use langId=-2 or locale=fr_FR. So the URL for the Sapphire Reference Store application will be https://<hostname>:6443/Sapphire?langId=-2 or https://<hostname>:6443/Sapphire?locale=fr_FR.

Note:

If both the langId and locale parameters are specified, the langId parameter is used.
If the langId or locale that is passed in the URL is not supported by the store, then it is considered that no language parameter is passed.
If neither langId or locale is passed in the URL, the default language for the store is displayed.

Store display language when no language parameter is passed

When the user opens the store website, the store display language is set based on the following points:

For registered users, the store display language is set based on the Preferred Language set for the user.
For other users, when the user sets the store language, it is stored in browser local storage for 30 days. If the user visits the store website at anytime during those 30 days, the store display language is set to the same language as the browser local storage.
If the user is visiting the store website for the first time, the store display language is set to the default language for the store.
If the store does not support the language that is set as the Preferred Language for registered users or no longer supports the language saved in the browser local storage, the store display language is set to the default language for the store.

Other considerations

Consider the following points about language support for the stores:

The Emerald Store data is only provided in en_US locale. The catalog of categories, products, attributes and the marketing content/promotion content in eSpots are only provided in English. The Emerald Reference Store application UI supports only en_US by default.
The Sapphire Store data is partially enabled for multiple languages. The catalog is shared from the Extended Sites Catalog Asset Store and hence has full translations in the languages that are already supported for the Aurora Starter store. However, the marketing content is unique to Sapphire and is only available in English. The Sapphire Reference Store application UI supports en_US and fr_FR by default.
Elastic Search supports language fallback such that product, category information that does not have specific translated data in another language can still return data when requested for that language by falling back to a defined fallback language. For example, if a store has a product for which only en_US data is available and the language for the store is set to fr_FR, the API call for that product requesting fr_FR data will return the corresponding en_US data.

Setting up language support for the stores

Before you can launch a store in a language other than the default en_US language, you must add the required languages to the SAS and the eSite stores from the Management Center. You must also run a full index on ElasticSearch.

To add support for a language for your store, see Supported languages in Updating store information

Examples for enabling French language support for the Reference Store applications

To enable French language support for the Emerald Reference Store application, complete the following steps:

Go to Management Center > Store Management tool and select the EmeraldSAS store.
Add the language fr_FR to the EmeraldSAS store.
Select the Emerald store.
Add the language fr_FR to the Emerald store.
Run the ElasticSearch full index for storeId=11 (storeId for Emerald Reference Store application). Wait for the indexing to be completed.
Launch the Emerald Store in French by using the following URL: https://<hostname>:6443/Emerald?langId=-2
The Emerald Reference Store application is now enabled for French. The UI is displayed in French if the UI data is translated. Catalog data appears in English with fallback and all marketing content is displayed in English with fallback.

To enable French language support for the Sapphire Reference Store application, complete the following steps:

Go to Management Center > Store Management tool and select the SapphireSAS store.
Add the language fr_FR to the SapphireSAS store.
Select the Sapphire store.
Add the language fr_FR to the Sapphire store.
Run the ElasticSearch full index for storeId=12 (storeId for Sapphire Reference Store application). Wait for the indexing to be completed.
Launch the Sapphire Store in French by using the following URL: https://<hostname>:6443/Sapphire?langId=-2
The Sapphire Reference Store application is now enabled for French. The UI is displayed in French if the UI data is translated. Catalog data appears in French as the categories and products are translated. All marketing content is displayed in English with fallback.

Adding new languages

Follow these steps to add new language:

Navigate to the directory: store-web/react-store/assets/common/public/locales.
The translation file folders for languages already added will be visible.
Select one of the existing language folders.
Copy the selected existing language folder.
Paste the copied folder in the same location.
Rename the copied folder with the name of the new language the user intends to add.
Open the translation file located within the copied folder.
Modify the contents of the translation file to align with the requirements of the new language.

Note: Follow established naming conventions and guidelines when adding new languages.