Dictionary Customization Guide

Every drop-in includes a dictionary with all user-facing text. Customize it to localize for different languages, match your brand voice, or override default text. The drop-in deep-merges your custom values with defaults—you only specify what you want to change.

Which guide do I need?

• Using the boilerplate? → See Labels for the placeholder system
• Want conceptual understanding? → You’re in the right place (deep-merge behavior, multi-language patterns, advanced use cases)
• Need specific drop-in keys? → See individual dictionary pages: Cart, Checkout, Product Details, etc.

Quick start

1. Find the dictionary keys: Check your drop-in’s dictionary page (Cart, Checkout, and so on).

2. Create your overrides:

   export const customDictionary = {
     Cart: {
       MiniCart: {
         heading: "Shopping Basket ({count})",  // Only override what you want
         cartLink: "View Basket"
       }
     }
   };

3. Pass it to initialize():

   import { initializers } from '@dropins/tools/initializer.js';
   import { initialize } from '@dropins/storefront-cart/api.js';
   import { customDictionary } from '../config/custom-dictionary.js';
   
   const langDefinitions = {
     default: {
       ...customDictionary,
     },
   };
   
   await initializers.mountImmediately(initialize, { langDefinitions });

Tip

Partial overrides only: You don’t need the entire dictionary. The drop-in deep-merges your values with the defaults, so specify only what you’re changing.

How deep merge works

Understanding the merge behavior is critical:

✅ Override specific keys, keep all the defaults:

// Your dictionary:
{ Cart: { MiniCart: { heading: "My Cart" } } }

// Result (merged with defaults):
{
  Cart: {
    MiniCart: {
      heading: "My Cart",        // ← Your value
      cartLink: "View Cart",     // ← Default kept
      checkoutLink: "Checkout"   // ← Default kept
    }
  }
}

✅ Nested objects merge recursively:

{
  Cart: {
    PriceSummary: {
      promoCode: {
        errors: {
          invalid: "That code didn't work"  // Only this changes
          // All other errors stay default
        }
      }
    }
  }
}

Multi-language support

Create dictionaries for each locale and load them dynamically:

Setup

export const cartEN = {
  Cart: { MiniCart: { heading: "Cart ({count})" } }
};

export const cartFR = {
  Cart: { MiniCart: { heading: "Panier ({count})" } }
};

Load by locale

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-cart/api.js';
import { cartEN } from '../config/dictionaries/cart-en.js';
import { cartFR } from '../config/dictionaries/cart-fr.js';

const userLocale = navigator.language.replace('-', '_');
const translations = { en_US: cartEN, fr_FR: cartFR };
const selectedLang = translations[userLocale] || cartEN;

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

await initializers.mountImmediately(initialize, { langDefinitions });

Note

Dynamic language switching: To switch languages after initialization, you’ll need to re-initialize the drop-in with the new langDefinitions. Store your translations and re-run the initialization code with the selected language.

Caution

Test the text length in all languages—longer translations may affect the UI layout.

Advanced patterns

Organize by drop-in

src/config/dictionaries/
  cart.js
  checkout.js
  user-auth.js

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-cart/api.js';
import { cartDictionary } from '../config/dictionaries/cart.js';

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

await initializers.mountImmediately(initialize, { langDefinitions });

Use JSON

{
  "Cart": {
    "MiniCart": {
      "heading": "Cart ({count})"
    }
  }
}

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-cart/api.js';
import enUS from '../config/dictionaries/en_US.json';

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

await initializers.mountImmediately(initialize, { langDefinitions });

Load from CMS

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-cart/api.js';

const translations = await fetch('/api/translations/cart/en_US')
  .then(res => res.json());

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

await initializers.mountImmediately(initialize, { langDefinitions });

---

Best practices

1. Keep placeholders - Values with {count}, {price}, and so on, must keep these placeholders for dynamic data injection
2. Use version control - Track all custom dictionaries in Git
3. Start small - Override a few keys, test them, then iterate
4. Document the changes - Add comments explaining why certain values were customized
5. Test the text length - Longer translations can break the UI layouts
6. Check for updates - New drop-in versions may add dictionary keys

Troubleshooting

Custom values not appearing:

• Verify that langDefinitions is passed to initialize()
• Check that the locale key matches exactly (en_US not en-US)
• Ensure that the dictionary structure matches the defaults
• Check the console for initialization errors

Missing dynamic values (counts, prices):

// ❌ Bad
heading: "Shopping Cart"

// ✅ Good - keep {count} placeholder
heading: "Shopping Cart ({count})"

Language not switching: Some components need to re-render after setLang(). Try refreshing the page or re-initializing the drop-in.

---

Related: Initialization • Labels • Branding