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 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 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.

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.

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.

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.

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.

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:

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).

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.

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.

Account Example

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

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):

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

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:

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

You can use the following defaults to represent general languages:

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:

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.

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:

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 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.