Drop-in components

Labeling and localizing drop-in components

In this topic, you will learn how to update drop-in component labels by using the resources available in the commerce boilerplate.

Key concepts

Placeholders file

A Google Sheets file (placeholders) or a SharePoint Excel file (placeholders.xlsx) where you change and maintain your storefront’s labels, which includes localization. See the Placeholders file for more information.

Language objects

A JavaScript object (named langDefinitions by convention) that contains key-value pairs for UI text labels in a specific language. The object is used to override the default dictionary with the placeholder file’s keys and values.

Drop-in component dictionaries

JSON files that define the shape, keys, and default values for labels and text within a drop-in component. Each drop-in component has a default dictionary file: i18n/en_US.json. But drop-in components can contain multiple dictionary files as the site is localized for other languages, including fr_CA.json for French, de_DE.json for German, and so on. The documentation for each drop-in component includes the default dictionary for that drop-in component. As an example, see the dictionary for the product details page drop-in component.

Labeling

To add or change UI text labels within Commerce drop-in components. Merchants can change the UI labels in their storefronts by changing the values in the placeholders file within their Google Docs or SharePoint directories.

Localizing

To change UI text labels to a specific language. This process includes translating text labels and changing the text direction, date and time formats, and currency symbols to match the target language.

Big picture

Labeling drop-in components in the storefront involves two files:

The placeholders file that provides the default drop-in component UI labels that merchants can quickly update as needed.
The drop-in block (examples, product-details.js, cart.js) where you add code to fetch, map, and override the drop-in component dictionary at runtime.

The following diagram shows the process for adding and overriding labels and text for drop-in components within the boilerplate template.

How localization and labeling works in storefronts.

Placeholder files. Merchants can quickly update the labels in their storefront from one file: placeholders, which is either a Google Sheet or Microsoft Excel file.
Import function. You need to import the fetchPlaceholders function from the boilerplate’s aem.js file.
Fetch placeholders. Use the fetchPlaceholders function to retrieve the placeholders key-value pairs from Google Docs or SharePoint folders.
Override default dictionary. Override the default property from the langDefinitions object with the keys and values from the placeholder object.
Initialize dictionary. Use the register function to update the dictionary at runtime.

Step-by-step

In the boilerplate code, the UI text labels in drop-in components come from the placeholders file. Using this file as the source for all storefront UI labels across drop-in components makes it easy for merchants to make label changes without developer involvement.

Import `fetchPlaceholders` function

In the drop-in block (for example, product-details.js, cart.js), import the fetchPlaceholders function from the boilerplate’s aem.js file.

import { fetchPlaceholders } from '../../scripts/aem.js';

Fetch placeholders

Within the decorate function, use the fetchPlaceholders function to retrieve the placeholders language object from the Google Docs or SharePoint folders. The following diagram and code snippet shows how to fetch the placeholders.

Using placeholder labels in your EDS commerce block

// Retrieve the placeholders language object
const labels = await fetchPlaceholders();

export default async function decorate(block) {
  const $elem = document.createElement('div');
  $elem.innerText = labels.Cart.PriceSummary.shipping.label;
}

Override default dictionary

Within the decorate function, override the drop-in component’s default dictionary with the placeholders object.

// Get labels from placeholders sheet
const langDefinitions = {
  default: {
    ...placeholders,
  },
};

Register updated dictionary

Use the initializers.mountImmediately API to register the new dictionary. The following code snippet shows how to register the new langDefinitions object.

// Register Initializers
initializers.mountImmediately(initialize, {
  langDefinitions,
  defaultLocale: locale,
  models
});

Test the changes

After you’ve updated the drop-in component dictionary with the new langDefinitions object, test the changes in the storefront to ensure the new labels are displayed correctly. If the labels are not displaying as expected, review the mapping between the placeholder keys and the drop-in component dictionary keys. Make sure the keys match exactly. If the keys don’t match, the drop-in component will use the default dictionary values.