Skip to main content
If you want to change the text of a native component you don’t have to create a custom component just for that. Every string the native checkout renders is a message with a key, and a version can override any of them.

​
Finding the key of a text

Every customizable text carries metadata attributes in the page. To find the key of the text you want to change:
  1. Open any checkout page in your browser.
  2. Right-click the text and choose Inspect.
  3. In the Elements tab, look at the selected node. The attributes sit on the element that renders the text, or right next to it.
Component Dev Tools
Messages use the ICU format through next-intl. The image below shows cardinal pluralization: the same key renders differently for one item and for many.
Messages Cardinal Plural
For the formatting rules (plurals, selects, rich text), see the next-intl documentation. Keep the placeholders of the original template when you override a message.

​
Where to edit

Admin → Versions → your version → Messages Configuration. The tab has two rows, ui and app, and each one is edited as a JSON object with its Edit button.
Messages Configuration tab

Versions → Messages Configuration

  • ui holds the texts of the checkout pages and components. Almost everything you will change is here.
  • app holds application-level texts.
The trash icon removes all overrides of a row at once.

​
Overriding a text

Edit the ui row and add the key with the new text. Click Update; the change is saved immediately and the checkout uses it on the next page load. For one value in every language, use the key at the top level:
ui
For a value in one language only, nest the keys under the locale:
ui

​
Rules for locale keys

  • Locale keys are lowercase with a hyphen: pt-br, en-us, es-mx. pt-BR never matches.
  • The match is exact against the shopper’s language. A pt key does not apply to a pt-br session.
  • A row is either flat or locale-keyed. Once a key matching the current language exists, only that nested object is used and any flat keys next to it are ignored for that language.
  • Your overrides are merged over the template’s defaults, so you only list the keys you change.
Supported locales: en, en-us, en-ca, es, es-ar, es-es, es-gt, es-mx, fr, fr-ca, pt, pt-br, ro, ro-ro. A shopper in an unsupported locale gets the first locale with the same language, then en-us.
Translation

Overriding the cart page title

​
Adding a translation

A translation is just an override under another locale key. Add the locale object with the keys you want to translate; everything you leave out keeps the template’s default for that locale.
Messages Translation

​
Custom components

Messages are for the native components. A custom component owns its own strings; make them configurable with props and read the session locale from useCheckoutSession().session.locale to pick the right one.