Localize a checkout UI extension

To create a checkout UI extension, you can use Shopify CLI, which generates starter code for building your extension and automates common development tasks.

1. Navigate to your app directory:

   Terminal

   Copy

   $

   $

   cd <directory>

2. Run the following command to create a new checkout UI extension:

   Terminal

   Copy

   $

   $

   shopify app generate extension --template checkout_ui --name my-checkout-ui-extension

3. Select Checkout UI.

   You should now have a new extension directory in your app's directory. The extension directory includes the extension script at src/Checkout.jsx. The following is an example directory structure:

   Checkout UI extension file structure

   Copy

   99

   1

   2

   3

   4

   5

   6

   7

   8

   9

   10

   └── my-app

   └── extensions

   └── my-checkout-ui-extension

   ├── src

   │ └── Checkout.jsx OR Checkout.js // The index page of the checkout UI extension

   ├── locales

   │ ├── en.default.json // The default locale for the checkout UI extension

   │ └── fr.json // The locale file for non-regional French translations

   ├── shopify.extension.toml // The config file for the checkout UI extension

   └── package.json

4. Start your development server to build and preview your app:

   Terminal

   Copy

   $

   $

   shopify app dev

   To learn about the processes that are executed when you run dev, refer to the Shopify CLI command reference.

5. Press p to open the developer console. In the developer console page, click on the preview link for your extension.

Anchor to Set the default localeSet the default locale

Your default locale specifies which locale Shopify should use when no other appropriate locale can be matched. In this example, English (en) is already the default locale. However, you can set any locale to be your default locale.

To change your default locale, go to the locales folder and change the [locale].json filename to [locale].default.json.

Anchor to Add translation strings for ,[object Object]Add translation strings for en.default.json

Add the translation strings we need to support English translations, including the zero, one, and other plural rules.

You can specify any pluralization key that Intl.PluralRules.select() supports and that's appropriate for the locale.

In subsequent steps, you'll use these keys to translate balance and points.

Anchor to Add translation strings for ,[object Object]Add translation strings for fr.json

Now add the translation strings we need to supoort French translations, many, one and other plural rules.

Similar to English, you can specify any pluralization key that Intl.PluralRules.select() supports and that's appropriate for the locale.

Anchor to Localize the currencyLocalize the currency

Now that you've defined translations, you'll learn how to localize currency.

You'll add the formatCurrency function provided by i18n. The function wraps the standard Intl object.

Depending on the current locale, 9.99 will now resolve to the following localized currency formats:

• en: $9.99

• fr: 9,99

Anchor to Localize numbersLocalize numbers

You'll localize number formatting using the formatNumber function provided by i18n. The function wraps the standard Intl object.

Depending on the current locale, 10000 will resolve to one of the following localized number formats:

• en: 10,000

• fr: 10 000

Anchor to Translate the balance remaining messageTranslate the balance remaining message

You'll also call the translate function, which sends the formattedBalance variable so that it can be used in the translation string.

Anchor to Translate the loyalty points message with plural valuesTranslate the loyalty points message with plural values

You'll use the translate function to pass in the count of how many points are available. You'll use formattedPoints to render the points in the current locale.

Anchor to Start your serverStart your server

Run the Shopify CLI dev command to build your app and preview it on your development store.

Make sure that you select a development store that has enabled the feature preview for Checkout and Customer Accounts Extensibility.

1. In a terminal, navigate to your app directory.

2. Either start or restart your server to build and preview your app:

   Terminal

   Copy

   9

   1

   shopify app dev

3. Press p to open the developer console.

4. In the developer console page, click on the preview link for the custom header extension.

   The checkout opens.

This section describes how to solve some potential errors when you run dev for an app that contains a checkout UI extension.

Anchor to Property token errorProperty token error

If you receive the error ShopifyCLI:AdminAPI requires the property token to be set, then you'll need to use the --checkout-cart-url flag to direct Shopify CLI to open a checkout session for you.

Anchor to Missing checkout linkMissing checkout link

If you don't receive the test checkout URL when you run dev, then verify the following:

• You have a development store populated with products.

• You're logged in to the correct Partners organization and development store. To verify, check your app info using the following command:

  Terminal

  Copy

  $

  $

  shopify app info

Otherwise, you can manually create a checkout with the following steps:

1. From your development store's storefront, add some products to your cart.

2. From the cart, click Checkout.

3. From directory of the app that contains your extension, run dev to preview your app:

   Terminal

   Copy

   $

   $

   shopify app dev

4. On the checkout page for your store, change the URL by appending the ?dev=https://{tunnel_url}/extensions query string and reload the page. The tunnel_url parameter allows your app to be accessed using a unique HTTPS URL.

   You should now see a rendered order note that corresponds to the code in your project template.

Anchor to Test the extension functionalityTest the extension functionality

The checkout UI extension should now render localized checkout content for en and fr:

To test the extension, preview the language from your development store admin.