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

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.

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 } from '../../scripts/commerce.js';

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

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

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

// 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;
}