Localization

Salesforce B2C Commerce is localizable, from business objects (for example, catalogs, products, and attributes) to the storefront.

To localize your B2C Commerce site:

  1. Identify which components of your storefront require localization, for example, content assets, products, product attributes, and currency.
  2. Determine how to architect localization for your business: processed using localized templates or properties files, depending on your approach.
  3. Identify which languages you support and how they interrelate. For example, when creating US and Spanish storefront versions, you might want to use the same underlying business objects. When in the storefront, a user can select a location, which specifies to B2C Commerce the file set from which to select. Alternatively, when supporting multiple European languages, you could offer products that are unique for a particular country, thus requiring unique catalog data for each locale.
  4. Configure locale settings at the organization and site level.

There are some situations, however, where localization isn't possible.

B2C Commerce supports Asian languages.

B2C Commerce includes current world currency data. There’s no need to add, edit, or remove currencies through Business Manager. You can, however, define how a currency appears for a locale. For example, the decimal positive pattern is defined as #,##0.00 for the Default (default) locale.

The appropriate currency is automatically selected in the storefront based on the selected locale. The currency assigned to the default locale is the lead locale of B2C Commerce.

B2C Commerce uses the $ for United States dollar (USD). For other currencies, the $ symbol is prefixed with letters based on common convention. For example, A$ denotes the Australian dollar.

B2C Commerce uses country codes for various features, such as:

  • Customer address and order address
  • Tax jurisdictions
  • Store locator
  • Rule evaluation of a dynamic customer group
  • Shipping address exclusion
  • Product lists
  • Geolocations

B2C Commerce supports two-character country codes per ISO 3166-1-alpha-2 only. B2C Commerce doesn't support other standards, such as 3-letter codes. Using them might result in some features no longer working correctly. For example, if you store 3-letter country codes in order addresses, the export of such orders would fail. Export files would be invalid per the B2C Commerce order.xsd schema.

See the API documentation on the following:

  • Package: dw.customer
  • Class: CustomerAddress
  • Property: countryCode : EnumValue (The customer's country code).

A locale represents a specific geographical, political, or cultural region. Salesforce B2C Commerce supports multiple locales for both the Business Manager user interface, and the underlying storefront site data.

B2C Commerce supports language-specific locales, in addition to country-specific locales, with an extended resource lookup sequence for all localized data.

  • Language-specific locales are included in Business Manager global preferences.
  • You can create locale-specific folders for image upload. When you create or manage language-specific image folders in Business Manager, the new locales appear in the locale select box, enabling you to create language-specific image folders, as for any other locale.
  • The lookup fallback sequence for all localizable resources (business object data, images, templates, messages) is consistent across B2C Commerce.

If you use the United Arab Emirates Dirham (AED) currency, we recommend that you show the amount value prefixed with the abbreviation currency, for example, (AED) 250. B2C Commerce doesn’t currently handle certain UTF characters that are right-to-left. For example, gift certificates purchased under the AED currency don’t show the amount under the list view. The list view is displayed when you select site > Merchant Tools > Online Marketing > Gift Certificates.

B2C Commerce is structured as an organization containing one or more sites (storefronts). To configure locales:

  1. Use global preferences to configure the organization locales settings (for example, the Business Manager default user interface language, the default data language, and activating/deactivating locales), instance time zones, and store locator data (geolocation).
  2. Use site preferences to configure storefront site currencies, locales, default country codes, and store lookup units (miles versus kilometers).
  3. You can also configure locale-specific URLs.
  4. Assign preferred locales by user for the Business Manager user interface.
  5. Assign preferred locales for the underlying B2C Commerce data, such as products, content, orders, and customers.

If you support multiple languages across sites, you might want to use a second language for your default language. For example, you could use French for the default language for France, Switzerland, and Luxembourg, but use country-specific resources for a portion of the data. In this case, typically you have multiple sites with shared resources and want to localize most of your data based on language rather than region. While sites using the same language (such as en), but different country (such as en_US, en_CA), might use some region or country-specific resources, most of the resources are the same.

Some Business Manager elements can't be localized.

Business Manager supports multiple languages in both its user interface and in the underlying data that is created, edited, and shown within it to be used in the storefront. You can configure locales separately for:

  • Viewing the application
  • Managing the data in a target language

For example, a user could view English products and content using a Japanese Business Manager.

There are two ways to select the Business Manager user interface locale:

  • Administrator: the administrator selects a preferred locale for the Business Manager display language. The interface shows a list of possible languages. The administrator can assign the preferred locale when creating a user profile, or editing an existing profile.
  • User: to select a different Business Manager display language, the user edits their user profile. The new locale appears for that user until the user selects another language.

To set a locale as preselected for all Business Manager pages that include localized attributes, you define the preferred locale (language) in a user profile. This locale (language) must have been previously activated for the instance through global preferences. This sets locales for:

  • Product
  • Catalog
  • Content
  • Search
  • Promotion rules
  • Customers
  • Custom objects
  • Ordering
  • Organization
  • Site development

To edit the locale, including specifying localized formats for attributes, dates, currency, quantity, and input settings, click the Locale ID link. If you want B2C Commerce to give you default formats, click Prefill after you select the locale.

You can define how linguistic search rules (stop words, category name exclusions, synonyms, hypernyms, compound words, common phrases, search suggestions, and stemming exceptions) are applied in a multi-locale site.

When you’ve configured the required locales, you must build search indexes for those locales. When customers use those locales (languages) in their search criteria, B2C Commerce is able to respond appropriately.

Salesforce B2C Commerce provides you with a locale fallback mechanism to meet your site's multi-locale requirements. By default, the country locale (for example, en_US) inherits data from the respective language locale (en), and the language locale (en) inherits from the locale default. You can configure locale inheritance.

You can configure a locale to skip a locale in its fallback chain, or to not have any fallback. For example, en_US falls back to en and then to default. You can configure en_US to fall back directly to default or you can configure en_US to not have any fallback.

The application server uses the locale fallback that you configure only when looking up localizable attributes or properties of objects of subclasses of PersistentObject, such as Product. The application server doesn’t consider the fallback locale when locating ISML templates, web forms, resource files in cartridges, or static content such as images.

If a locale is configured as the fallback for another locale, you can't delete it: an error message appears.

For example:

  • You configure en_US > en > default.
  • You can't delete en because it's the fallback for en_US.
  • Similarly, if you attempt to import en in delete mode, an error message appears in the import log.

Disabling Locale Fallback

You can disable the fallback behavior for each locale.

For example:

  • A product description is in the en locale
  • For the en locale, the fallback is disabled and there’s no description for that product
  • Nothing is returned

Most elements of the Business Manager user interface are localizable. You see the configured language throughout the application. However, there are some situations where localization isn't possible

The following table describes situations where localization isn't possible.

ElementDescription
Attributes used for column titles in gridsAttributes defined by a customer in the database appear as they were entered. Some column headers in an otherwise localized grid appear untranslated.
Attributes used for section and field labelsAttributes defined by the customer in the database that are used on many pages as field labels, appear untranslated. On a page with many such custom attributes, 90% of the page could appear untranslated.
Site IDs in breadcrumb and other stringsThe site ID on a History tab or in breadcrumbs aren't translated.
Country names used in the Store LocatorIn the Store Locator, country names come from the GeoLocationPO database and aren’t translated.
Order statusOrder status names are customer-defined and aren’t translated.
Tooltips text defined in the databaseText beneath the dividing line of some tooltips comes from the customer's database and isn't translated.
Permissions managed in the databaseIn the Roles & Permissions module, descriptions for the different permissions are defined in the customer database and aren’t translated.
Third-party data and proper namesThird-party data and names aren’t translated, for example, the calendar to enter the start or end date of a campaign is in English. It's part of GWT and not accessible for localization.
Object types from auditing framework:On the Customer Groups page, for example, a variable inside the description of a group isn't translated. Such object types can't be translated because they come from inside the auditing framework.
UI elements coming from the browser:The browser controls the Browse button. This button isn't localizable from within Business Manager.
Internal exceptions:Errors caused by exceptions outside of Business Manager aren’t translated. For example, an error such as, "Start node not found (ManageCustomGMVReports) for pipeline (ViewCustomizationImpex)." is untranslated.

Message resources support Asian character sets because property files assume a UTF-8 encoding. As a result, existing property files that are compatible with the ISO-8859-1 (Latin 1) encoding might no longer be supported in their existing form.

UTF-8 encoding supports many more languages than ISO-8859-1, including Greek, Cyrillic, Coptic, Armenian, Hebrew, Arabic, Syriac and Tana alphabets, as well as Chinese, Japanese and Korean ideographs, symbols, and punctuation.

LocationImpact
USAUTF-8 encoding, like ISO-8859-1, is a super-set of the US-ASCII format. This means that existing property files containing only letters, numbers and punctuation among the 128 character codes in US-ASCII are inherently compatible with this change.
Other CountriesProperty files containing accented characters and additional punctuation, that are beyond the 128 US-ASCII codes and commonly called extended ASCII characters, aren’t compatible with this change. These files must be converted to UTF-8 format to continue to be used.

If you use extended ASCII characters, you must convert your property files to support UTF-8.

Search Query Processing

Salesforce B2C Commerce supports search query processing for Chinese and Japanese sites.

There are tasks required to translate your storefront into the required languages.

To enable translation of the source:

  1. Create language-specific folders (for example, es_US).
  2. Identify images (for example, buttons) with locale-specific text.
  3. Identify for translation only those templates that are used in the storefront.
  4. Identify the JavaScript files where the locale-specific text is used.
  5. Identify other product, category, or content images where the locale-specific text is used.
  6. Translate these files and store them under the folder previously created (for example, es_US).
  7. Run a full regression test and QA for the localized content.
  8. Change the header or sidebar to integrate a select box where the user can select the language to be used for a session.

To enable content translation:

  1. Export content, category, or products.
  2. Translate the content, category, or products.
  3. Import the content and use Business Manager for further editing.
  4. Translate name and description of shipping methods. These values appear in the storefront during checkout.

You can localize static files such as images and CSS.

Images

Localizing static files such as images enables you to include images that contain localized text or locale-specific symbols. Your initial system includes the following structure:

LocationContainsLocalized
cartridge/web_ch_cust_app/cartridge/static/{default}English (or default) images (such as buttons), JavaScript (including English error messages), css files. (all are in the cod)No
sites/Sites-cust-Site/1/units/Sites-cust/static/{default}English (or default) content and category images, category images and homepage images (all are from the content library)Yes - text overlay

You can include an images folder within the locale-specific folder, but the SiteGenesis application doesn't use this capability for cartridge images.

If a user calls the URL using locale es_US, the files in folder es_US are loaded first. If they aren’t found, Salesforce B2C Commerce uses the default folder as a fallback. So within a local-specific folder, you need only include files that are truly locale-specific (not background images, for example).

This logic occurs on a per file basis.

CSS Files

Your file system must have unique, locale-specific folders. For example, to support both English and Spanish (es_US), create a second es_US folder within the /static folder that lets B2C Commerce overwrite the default files. The included files must have the same names as the files under default and the same folder structure.

In the following directory structure, for example, the localized files are stored in language-specific directories (French and German). You can also use locale-specific directories (for example, fr_FR, fr_CA, en_US).

When developing your storefront application, you can use one template set or use a unique template set for each locale.

When you use one template set, you externalize localizable strings, and translate the strings in resource files. Salesforce recommends this approach as a best practice methodology.

The advantage of using one template set is that templates (which can hold complex logic to visualize dynamic data) don't have to be modified as the storefront is localized. Also, the display logic exists in a single place (the non-language specific template) only. The externalized strings are stored in a simple file format that can be passed to translation service providers. The translation can be integrated back into B2C Commerce simply by copying the translated file into the cartridge, without potentially breaking the logic.

The Storefront Reference Architecture (SFRA) application provides a simple way to localize any text that appears in the storefront. It uses a single template set for all locales, stored in properties files (called template resource bundles). The template resource bundles are translated, not the templates. The templates reference the localizable text in the template resource bundles by keys. Depending on the locale that is used in the storefront, a different translation (localization) of the properties file is used.

Projects typically start from the SFRA application code, so it's important that you use this approach consistently.

To support multiple languages, you can create language-specific (for example, en) or locale-specific (for example, en_US) directories within the templates/resources directory, as follows:

Salesforce B2C Commerce (and the SFRA application) supports a localization fall-back mechanism. If no locale-specific directory exists, the language-specific directory is used. If there’s no language-specific directory, the default directory is used.

There’s a corresponding template resource bundle for each folder in the templates directory and one for the forms definitions.

Template resource bundles hold static content for localization. They’re stored for each cartridge within the /templates/resources directory. Messages from the bundles are accessible to all templates of the corresponding cartridge via the msg()method, available in the dw.web.Resource class.

Content Warning: The content on this page necessarily engages with noninclusive language that can be emotionally and intellectually challenging.

See the Salesforce B2C Commerce API documentation for more information.

These properties files have already been created for you in the SiteGenesis application. They each contain a list of text that pertains to its corresponding object (template or form). They’re organized as a single properties file per top-level directory.

If a valid localeID is set by the SendMail API pipelet, the locale is also used inside an email template to resolve localized messages by the Resource.msg() function based on the given locale. If you’re using the dw.net.Mail class to send messages, the LocaleID set through Template.setLocaleId or the constructor Template(Template,LocaleID) is used to look up the template resource before the locale linked to the current request.

Account Example

For example, account.properties, which lists the text in the minicartcontent.isml template, looks like this:

You can name the elements anything you want. In the SiteGenesis application, the elements are named after the files in which they’re contained, followed by a descriptive string. For example, a resource bundle referenced in the editaddress.isml template would be editaddress.discriptivestring,

For any text to be included in the storefront using this methodology, you must create a line within the corresponding language-specific properties file. These language files are named to correspond to the file directory of the language snippet to be used. Each text snippet has a unique key (unique across resource bundle files).

Comments

Comments are preceded by a # character.

For example, in the account.properties file, the text list is separated by the sub directories within the top-level directories.

Properties with the sub directory would be separated, as shown previously.

Form Example

The following is an example of using properties within a German version of a form (forms/default/creditcard_de.xml - forms.properties):

Use the same pattern of appending the local identifier when creating locale-specific resource bundles (.properties) files. For example:

  • account_en_GB.properties
  • account_en_US.properties
  • account_en.properties

To include your language text within a template or form, reference the corresponding line from the correct file.

Content Warning: The content on this page necessarily engages with noninclusive language that can be emotionally and intellectually challenging.

Cart Template Example

The following example calls resource usage in a template:

This entry is the corresponding entry in checkout.properties:

Form Example

This example shows resource usage in a form:

This is the corresponding section in forms.properties:

You can use language-specific template sets to localize, although using one template set is the preferred approach.

With the multiple template set approach, each locale of a storefront has its own set of templates. The templates are stored in uniquely named folders, with this file structure:

By default, Salesforce B2C Commerce provides all templates within the \defaultfolder. This folder is used when no template is found for the requested locale. Directory names for locale-specific templates consist of a language and a country code, as specified in the standard ISO 639 (language) and ISO 3166 (country).

This table shows some sample folder names:

LocaleFolder Name
English/United Statesen_US
English/Irelanden_IE
German/Austriade_AT
Spanish/Argentinaes_AR
French/Canadafr_CA

For example, templates could be stored in this directory structure:

You can use the following defaults to represent general languages:

LanguageFolder Name
Englishen
Germande
Frenchfr
Spanishes

You can use different templates for different locales, even though the locales share the same language. You can also share templates between different locales with the same language.

For example, a company set up a multi-site environment with three sites:

  • United States
  • Great Britain
  • Ireland

Select the correct locale for each site: en_US for the US, en_GB for the UK and en_IE for Ireland. All main templates are shared between these locales. You can implement country-specific changes to each site, for example, show the different country icons in the top left-hand corner of the Welcome page.

To achieve this effect, use three welcome templates with three different images or logos. Store the welcome.isml template in different folders specific for each locale:

The characters, xx_XX represent a combination of the language and the country. For example, en_US represents the English (en) language spoken in the USA (US), while en_IE represents the English language (en) spoken in Ireland (IE). Likewise, de_DE represents the German language (de) spoken in Germany (DE), while de_AT represents the German language (de) spoken in Austria (AT).

In Salesforce B2C Commerce, you can localize URLs. When you create a site, the URL Rules module automatically formats your URLs according to the module configuration.

If site URLs are configured with the locale ID as the first element of the URL (for example, /en_US/mens), B2C Commerce doesn't resolve URLs if they don't contain the locale (for example, /mens).

Standard B2C Commerce URLs aren’t enabled by default and aren’t optimized for SEO. This URL structure is important to understand if you’re generating a locale-specific URL programmatically. Standard Demandware URLs have a simple structure for storefront access in the following format:

Links to this type of address call a public pipeline-start node and can provide parameters such as category or product. You can also use these additional parameters:

cgid=category ID

pid= product ID (sku)

cid= content ID

Finding the locale in the URL

You can find the locale that is used for a user session in the URL. For single-language installations, there’s always a locale named default. When using multiple locales, use {locale} instead of /default/.

Example:

URLLocale
http://{domain}/on/demandware.store/Sites-customer-Site/default/... Valuedefault
http://{domain}/on/demandware.store/Sites-customer-Site/en_US/... Valueen_US

The locale is used for the lookup of resources in the file system and in the database.

You can provide two links so that your users can switch from English to Spanish on the homepage. But these links can't be hardcoded to the production instance URL. The links must also be able to access the staging and sandbox instances for testing purposes.

You can access (get or set) the default locale programmatically, as shown in this example:

You can get the default locale from the site: dw.system.Site.getCurrent().defaultLocale (Read Only)

You can show product prices in multiple currencies in the storefront using the Salesforce B2C Commerce API.

Use these API methods:

  • ProductPriceModel.getPriceBookPrice(String priceBookID)
  • ProductPriceModel.getPriceBookPrice(String priceBookID, Quantity quantity)

If the price book currency is different from the site currency, these methods return a product price.

This feature is for display purposes on the product details page only. The feature lets you show product prices in another currency, along with the actual sales price in the site currency. This feature doesn't enable you to implement a multi-currency checkout, for example.

Search result sorting, search refinements, price ranges, and other price-related features are limited to the site currency only.