20 Localize Your Store

You can translate your catalog and store content into multiple languages so a shopper can automatically see your store in the language specified by her browser’s locale. A shopper can also manually select a language from a list of languages your store supports.

This section describes how to translate your store into other languages. For information about how to display your store’s prices in different currencies, see Configure Price Groups.

Understand Store Localization

Each language Commerce supports matches an ISO locale. For example, English (Australian) matches the en_AU locale.

You must assign a default language for each Retail Digital Commerce site you set up. You must create all catalog items in the site’s default language and then translate them into the additional languages your site supports. See Prepare your catalog for translationand Import translations for catalog items for more information about translation. See Enter basic store information for more information about assigning default and additional languages to a site.

Important:

Do not change your site's default language once you set it, especially if you have already created catalog items such as products, SKUs, and collections.

You can translate the values for short-text and rich-text properties for all catalog items. For example:

  • Product names, descriptions, and brands
  • Collection names and descriptions
  • Variant property names and values. For example, you can translate both the variant property name Color and all its values, such as green, blue, and red.
  • Although not part of your catalog, you can translate the shopper-visible properties for settings, for example, the names of shipping methods and promotions.

You can also translate store text that is not part of the catalog, for example, labels, messages, and help tips. See Translate store text for more information.

The shopper’s browser locale controls the format of numbers, including dates and prices. You cannot manually change or customize number, date, or currency formats.

Note:

Your store can support more than one currency. For information about selecting a default currency when you set up the store, see Define additional store settings. For information about displaying prices in other currencies, see Configure Price Groups.

Emails your store sends are already translated into all the languages that Retail Digital Commerce supports. You can customize the email text in all the languages your store supports. See Configure Email Settings for more information. Emails are sent in the language of the shopper’s browser when the event that triggered the email took place. For example, if a shopper places an order from a browser whose locale was set to ES, the service sends the Spanish translation of the Order Placed email.

Select Additional Languages

The first step in translating your store is to select the additional languages you want your store to be displayed in.

Once you select additional languages, a new dropdown list appears at the top of the administration interface. When you are ready to translate components of your catalog and store into a new language, select that language from the list before you start translation tasks.

To select additional languages your store supports:

  1. Click the Settings icon.
  2. Select Setup from the Settings list.
  3. On the Location tab, click the Additional Store Languages field and select a language. See Languages supported by the storefront for the available options.

    Repeat this step for each new language your store will support.

When you remove any of the additional languages, shoppers can no longer select them from the Language list on your store.

To remove a supported language from your store:

  1. Click the Settings icon.
  2. Select Setup from the Settings list.
  3. On the Location tab, in the Additional Store Languages field, click the X icon in the corner of the language you want to remove.

Languages Supported by the Storefront

The following languages are supported for use with Retail Digital Commerce. All languages in the list are available for use on the storefront translation and search input.

Arabic (ar), Catalan (ca), Indonesian (id), Malay (ms), and Vietnamese (vi) are not supported for the administration interface.

  • Arabic – ar
  • Bulgarian – bg
  • Catalan – ca
  • Chinese (Simplified) – zh_Hans
  • Chinese (Traditional) – zh_Hant
  • Croatian – hr
  • Czech – cs
  • Danish – da
  • Dutch – nl
  • English (Australian) – en_AU
  • English (Canadian) – en_CA
  • English (UK) – en_GB
  • English (US) – en_US
  • Estonian – et
  • Finnish – fi
  • French – fr
  • French Canadian – fr_CA
  • German – de
  • Greek – el
  • Hungarian – hu
  • Indonesian – id
  • Italian – it
  • Japanese – ja
  • Korean – ko
  • Latvian – lv
  • Lithuanian – lt
  • Malay – ms
  • Norwegian – no
  • Polish – pl
  • Portuguese (Brazil) – pt_BR
  • Portuguese (Portugal) – pt_PT
  • Romanian – ro
  • Russian – ru
  • Serbian (Cyrillic) – sr_RS
  • Serbian (Latin) – sr_Latn_RS
  • Slovenian – sl
  • Spanish – es
  • Spanish (Mexico)– es_MX
  • Swedish – sv
  • Thai – th
  • Turkish – tr
  • Ukrainian – uk
  • Vietnamese – vi

Prepare your Catalog for Translation

Create all catalog items in your store’s default language and then translate them into the additional languages your store supports.

Text for a short-text or rich-text properties can be translated when the property is marked as translatable in the product type. Some properties, such as the Base product’s Name, Description, and Long Description properties, are marked as translatable by default. New properties you create are not marked as translatable by default. When you create new properties you can decide if they will contain translatable content and mark them accordingly. Once you mark a property as translatable, you cannot remove that setting. See Create and edit product types to learn how to mark properties as translatable.

Note:

The names of collections and the names of shipping methods are automatically translatable; there is no setting to mark them as such.

Import Translations for Catalog Items

The easiest way to translate your catalog into the additional languages your store supports is to export products, variants, and collections in your store’s default language, replace the translatable strings with localized text in the spreadsheets, and import them back into your catalog.

See Import and Export Catalog Items and Inventory for more information.

When you export catalog data for translation, you must select a language that the export supports. If you select a different language than your store’s default language, LOCALE appears in the fifth column (cell E1) of the export spreadsheet and shows the ISO locale code for the language, for example, LOCALE=fr.

When you import the translations back into your catalog, made sure LOCALE appears in the fifth column (cell E1) of the import spreadsheet and shows the ISO locale format for the language you are importing, for example, LOCALE=fr.

Note:

You cannot create new items when you import translations. All new items, even those created by import, must be created in your store’s default language.

Manually Translate Properties

You cannot import translations or other values for shopper-visible settings, such as the names of shipping methods, so you must manually translate them.

You can also manually translate properties for catalog items, though importing translations is recommended when working with a large number of properties. See Import translations for catalog items for more information.

To manually translate items:

  1. Select the language to translate to from the content-language list at the top of the page.
  2. Open the item whose properties you want to translate.
  3. Fields for translatable properties that you have not yet translated into this language are blank.
    Note: The untranslated names of product-type properties are not blank, but appear in the store’s default language.
  4. Enter the translated value for each translatable property on the page.
  5. Click Save.

Translate Store Text

Use text snippets to translate the text displayed on your store into the different languages your store supports.

Store text includes messages, labels, and help tips. You access and translate your store’s text snippets on the Design page. See Configure widgets in the administration interface for information about translating store text for Open Storefront Framework applications.

Configure the Default Locale for a Site

By default, when a shopper visits an Retail Digital Commerce site, it displays in the browser's preferred language if that language supported by the site. You can configure the site to display in the site's default language, even if it is not the browser's preferred language.

Each language Retail Digital Commerce supports matches an ISO locale. A site's default language is specified internally by its defaultLocaleId property. To override the browser's preferred language and display a site in the site's default language, Use the Admin API to set the site object’s useDefaultSiteLocale property to TRUE. (It is set to FALSE by default.)

Use the updateSite endpoint to modify the useDefaultSiteLocale property on an existing site. For example: 

PUT /ccadmin/v1/sites/100002  HTTP/1.1
Authorization: Bearer <access_token>
x-ccasset-language: en

{
  "properties":
  {
    "useDefaultSiteLocale": "true"
   }
}

When you set a site's useDefaultSiteLocale property to TRUE, you must also make sure the site is using the most recent version of the Header widget and Language element.

See Configure Sites for more information about using the REST API to work with sites.

Use a Specific Locale Code in a REST Request

Requests can include the x-ccasset-language header to instruct the endpoint to use a specific locale code for content returned in the response.

The locale supplied in the header must be supported by your store. (See Select additional languages for more information.) The API endpoint documentation specifies if the x-ccasset-language header is required or optional for an endpoint. See Learn about the APIs for information about accessing the endpoint documentation.

Troubleshoot Translation Issues

Many common translation issues have workarounds.

This list describes workarounds for common translation issues.

  • If your store supports additional languages but you do not translate all the translatable shopper-visible properties, the untranslated strings will appear in the store’s default language. This can result in multiple languages appearing on the same page. For example, if you translate product names but not descriptions, the name and description will appear in different languages on the product details page.
  • When you select a default language for your store, select a language that specifies a neutral locale, not one that specifies a region-specific local. For example, select English not English (United States) or English (Canada). To support region-specific variants of the default language on your store, add them to the Additional Store Languages list. See Select additional languages for more information.

Note:

In this release, there are no neutral-locale options for Chinese or Portuguese. You must select either Chinese (Simplified) or Chinese (Traditional) for Chinese and Portuguese (Portugal) or Portuguese (Brazil) for Portuguese.