Labeling and Localizing Drop-In Components

The Commerce Boilerplate provides a placeholder system that lets merchants handle labelingCustomizing UI text labels for tone, branding, or clarity while staying in the same language. without code. Learn to implement placeholder filesJSON files that store storefront UI labels by drop-in and locale so merchants can change text without changing code. to override default text in drop-in components.

Merchant vs Developer guides

Merchants translating content: See Commerce localization tasks for step-by-step guidance on localizingAdapting UI text and formatting for specific languages and regions, including translated labels and locale-specific conventions. placeholder files for different locales.

Developers implementing the system: This guide explains how placeholder files integrate with drop-in dictionaries using langDefinitions language objectsObjects such as `langDefinitions` that map translation keys to localized UI text values.. For advanced customization beyond the placeholder system, see the Dictionary customization guide.

Big picture

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

1. The placeholders files that provide the default drop-in component UI labels that merchants can quickly update as needed.
2. 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.

1. Placeholder files. Merchants can change the storefront labels by changing the values in the placeholder JSON files, which are organized by drop-in components—cart.json, checkout.json, pdp.json, and so on.
2. Import function. You need to import the fetchPlaceholders function from the boilerplate’s commerce.js file.
3. Fetch placeholders. Use the fetchPlaceholders function to retrieve the placeholders key-value pairs from the content folder.
4. Override default dictionary. Override the default property from the langDefinitions object with the keys and values from the placeholder object.
5. 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 placeholder files. By using these files as the source for all storefront UI labels, merchants can easily change labels without involving developers.

There are two things to be aware of when using the fetchPlaceholders() function:

1. During initialization:
   You must provide the path to the drop-in’s placeholders file. This file will be fetched and merged into the existing placeholders object. Subsequent calls to fetchPlaceholders() without a path will return the merged object containing all fetched labels.

2. After initialization:
   You can call fetchPlaceholders() without a path to retrieve all initialized placeholders as a single object. This object can be accessed from a Block or anywhere else in the project.

Import fetchPlaceholders function

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

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

Initialize placeholders with path

During initialization, you must use the fetchPlaceholders() function using an argument to the path to your drop-in’s placeholders file. This fetches and merges the placeholders into the global object.

// Initialize placeholders for this drop-in
const placeholders = await fetchPlaceholders('placeholders/cart.json');

const langDefinitions = {
  default: {
    ...placeholders,
  },
};

// Register Initializers
initializers.mountImmediately(initialize, {
  langDefinitions,
  //...
});

Tip

Locale key: The boilerplate uses default as the locale key for the primary language. Under the hood, this maps to the drop-in’s en_US locale. For multi-language implementations, see the Dictionary customization guide.

Fetch placeholders after initialization

After initialization, you can use the fetchPlaceholders function without a path to retrieve all merged placeholders. 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;
}

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.