labeling.mdx

title	Labeling and Localizing Drop-In Components
description	How to localize your drop-in components.
sidebar	label order Labels 5

import Aside from '@components/Aside.astro'; import Diagram from '@components/Diagram.astro'; import CodeImport from '@components/CodeImport.astro'; import CodeInclude from '@components/CodeInclude.astro'; import dictionary from '@dropins/tools/types/elsie/src/i18n/en_US.json.d.ts?raw'; import Vocabulary from '@components/Vocabulary.astro'; import Callouts from '@components/Callouts.astro'; import OptionsTable from '@components/OptionsTable.astro'; import { Steps } from '@astrojs/starlight/components'; import Tasks from '@components/Tasks.astro'; import Task from '@components/Task.astro';

The Commerce Boilerplate provides a placeholder system that lets merchants customize drop-in labels without code. Learn to implement placeholder JSON files to override default text in drop-in components.

Merchants translating content: See Commerce localization tasks for step-by-step guidance on translating placeholder files for different locales.

Developers implementing the system: This guide explains how placeholder files integrate with drop-in dictionaries using the langDefinitions system. For advanced customization beyond the placeholder system, see the Dictionary customization guide.

Key concepts

Placeholder files

JSON files that manage storefront labels, including localization. Each drop-in component has its own placeholder file (for example, cart.json, checkout.json, pdp.json). For merchants translating these files, see Commerce localization tasks. For reference documentation, see Placeholder files.

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.

Labeling (Customizing Text)

Changing UI text labels within Commerce drop-in components, whether for branding, tone, or clarity. For example, changing "Add to Cart" to "Add to Bag" or "Buy Now". Merchants use placeholder files to customize these labels without code changes.

Localizing (Translating for Different Languages)

Adapting UI text labels and formatting for specific languages and regions. This includes translating text labels and adapting date/time formats, currency symbols, and text direction to match the target language. Uses the same placeholder file system as labeling, but organized by locale folders (for example, /en/placeholders/, /fr/placeholders/).

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.


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,
  //...
});

**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](/dropins/all/dictionaries/). ### 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.


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