Localize Storefront Components

Learning Objectives

After completing this unit, you’ll be able to:

List the steps of the Salesforce B2C Commerce localization process.
List the steps of the translation process for text versus source files.
Explain how resource files work.
Explain how to localize images and URs.

Localization Components

Now that Cloud Kicks merchandiser, Brandon Wilson has configured locale settings at the organization and site level, he’s ready to start the localization process. He knows that he can’t do it on his own. He asks Vijay Lahiri, Cloud Kicks developer, to help.

Vijay Lahiri, Cloud Kicks Developer

Here are the steps they take.

Step	Task
1	Identify which components of the storefront require localization—for example, content assets, products, product attributes, and currency.
2	Identify which languages they support and how they interrelate.
3	Determine how to structure localized components via templates and properties files.

Identify the Components

Brandon starts by identifying what appears on the storefront as text and as text within graphics, all of which needs to be translated. Some countries only want to see their own language. Showing a different language can deter shoppers.

Brandon works with Vijay to:

Create language-specific folders (for example, es_US).
Identify images (for example, buttons) with locale-specific text.
Identify for translation only those templates that are used in the storefront.
Identify the JavaScript files where the locale-specific text is used.
Identify other product, category, or content images where the locale-specific text is used.

There are some situations, however, where localization isn't possible. See the documentation for details.

Identify the Languages and How They Interrelate

Brandon needs to identify which languages he wants to support and how they interrelate. For example, he wants the US and Spanish storefront versions to use the same underlying business objects so that when a shopper selects a location, B2C Commerce knows which file set to select from. In Europe, however, he wants to offer products that are unique for a particular country. He wants to provide unique catalog data for each locale.

Structure Localized Components

Salesforce B2C Commerce is localizable, from business objects (for example, catalogs, products, and attributes) to the storefront. But what does that mean? The answer lies in where the localizable data is and how it’s organized. B2C Commerce uses the cartridge structure to deliver a localized storefront. A cartridge is a container for packaging and deploying program code and data that’s structured in folders and subfolders for maximum efficiency.

Take a look at this cartridge folder structure where localized files are stored in language-specific directories (French and German). Vijay can make this as granular as he wants via folder naming, for example, fr_FR, fr_CA, en_US).

/Cartridge
   /static
       /default
           /css - generic files
                normalize.css
                print.css
                style-responsive.css
                style.css
           /images
                generic images
           /js - generic files
       /fr
           /css
                normalize.css
                print.css
                style-responsive.css
                style.css
           /images
                localized images
           /js
       /de
           /css
                normalize.css
                print.css
                style-responsive.css
                style.css
           /images
                localized images
           /js

This example shows the structure of localized CSS (Cascading Style Sheets) files, which describe how Hypertext Markup Language (HTML) elements are displayed on the screen. The default folder is what B2C Commerce uses when there’s no localized file available. Locale-specific files must have the same names as the files under the default folder and the same folder structure. That is the essence of the fallback mechanism.

Localization Steps

Brandon has US English source files that include content, category, and product text, and UI or content images and templates (page layout) that contain text. He also has CSS files that need to handle localized page styling. He starts by adding one locale, US Spanish, and separates the translation tasks into two projects: text and files.

Translate Content, Category, and Product Text

Here’s what he does to translate US English text into US Spanish text.

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

Translate Source Files

Here’s what he does to translate English source files into US Spanish files.

Create language-specific folders (for example, es_US).
Identify images (for example, buttons) with locale-specific text.
Identify for translation only the templates that are used in the storefront.
Identify the JavaScript files where the locale-specific text is used.
Identify other product, category, or content images where the locale-specific text is used.
Translate these files and store them under the folder previously created (for example, es_US). For images, this often involves recreating images using their original creation tool.
Run a full regression test and QA for the localized content.
Change the header or sidebar to integrate a select box where the user can select the language to be used for a session.

Localize Templates

Vijay also localizes templates and form definitions. Templates define how data and page information is transformed into HTML-based web pages. Form definitions let you control how shopper-entered values are validated and rendered on the browser.

When developing the storefront application, Vijay can use a single template set or a unique template set for each locale. It’s a set because it contains storefront page templates for a variety of pages, including the product details, search results, and cart pages, for example.

Best practice is to separate the text (string data) from the template set and save it as translated resource files that templates call. Salesforce recommends this approach as a best practice for many reasons.

Templates don't have to be modified as the storefront text is localized.
The display logic exists in a single place (the non-language specific template).
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.

Resource Bundles

Resource bundles contain localized static content, such as error messages. You can create a resource bundle for each folder in the templates directory that’s stored within the /templates/resources directory. It’s the same with forms definitions. Templates access the messages from within their cartridge path via the B2C Commerce API msg()method, available in the dw.web.Resource class.

/templates
     /default
         /account.isml
         ...
         /util.isml
     /resources
         account.properties - default files
         ...
         storelocator.properties
         /fr
              account.properties
              ...
              storelocator.properties
         /de
              account.properties
              ...
              storelocator.properties

The default folder is always first, with locale-specific folders following in the same pattern that B2C Commerce uses for its localization fallback mechanism.

To show localized text within a template or form, B2C Commerce references the corresponding line from the correct file. Here’s an example of accessing text within the cart template.

// Reference to resource minicart.viewcart in resource file
<a href="${URLUtils.https('Cart-Show')}"
 title="${Resource.msg('minicart.viewcart','checkout',null)}"
 class="mini-cart-link">
// ${Resource.msg('minicart.viewcart', 'checkout',null) } will grab the text = View your cart

The Resource.msg entry has a corresponding entry in checkout.properties file that contains the cart page HTML title text: minicart.viewcart

You can also store resource bundles under the /templates/resources directory, without subdirectories, and specify the locale in the filenames like this.

account_en_GB.properties
account_en_US.properties
account_us.properties

Localize Forms

Localizing a form often means changing its structure, such as including different address fields, such as state or province, depending on the country. You can program how it processes form, such as changing the zip code/country code structure based on country selection. You can change the structure completely, say for an Asian locale that displays words in a different way than the source language.

Vijay creates a forms/default folder for the standard locale and then separate folders for each locale, where he stores a locale-specific form definition for the billing address. Here’s the structure.

  forms
      default
          billingaddress.xml
      it_IT
          billingaddress.xml
      ja_JP
          billingaddress.xml

Localize Images

Localizing images means translating the text or symbols within them. Brandon works with Vijay to learn where these files are located so he can provide them to a translation service. Here’s where the source files are typically located.

Files	Location	Localized
English (or default) images (such as buttons), JavaScript (including English error messages), css files (all are in the code)	cartridge\web_ch_cust_app\cartridge\static\default	No
English (or default) content and category images, category images and homepage images (all are from the content library)	sites\Sites-cust-Site\1\units\Sites-cust\static\default	Yes—text overlay

Localize URLs

B2C Commerce URLs are not localized by default and are not optimized for search engine optimization (SEO). So Brandon researches the standard URL structure to determine what he wants to do. Vijay must add code to the storefront application that generates locale-specific URLs programmatically.

Here’s a typical URL that corresponds to the default locale.

http://<domain>/on/demandware.store/Sites-customer-Site/default/... Value

Victor adds code that identifies the available locales and then produces URLs to look like this.

http://<domain>/on/demandware.store/Sites-customer-Site/en_US/... Value
http://<domain>/on/demandware.store/Sites-customer-Site/fr_CA/... Value

Next Steps

In this unit, you learned how to localize storefront components, where they are, and how you can structure them to take advantage of the B2C Commerce fallback mechanism. Next, take a closer look at multisite localization concepts and practices.

Looking for Help?

Discover More