Skip to main content

Localize a customer account UI extension

In this tutorial, you'll use JavaScript API functions to localize an extension that displays a customer's loyalty point balance on the Profile page. You'll localize the extension text, the number format of the loyalty points balance, and the monetary value of the points. You'll also provide translations for singular and plural values. You can use what you learn here to localize other extensions.

Anchor to What you'll learnWhat you'll learn

In this tutorial, you'll learn how to do the following tasks:

  • Create a customer account UI extension that renders in the Profile page with some basic localization.

  • Run the extension locally and test it on a dev store.

  • Define translation data and localize the following elements:

    • Numbers using a formatNumber function similar to the Intl object
    • Currency using a formatCurrency Intl object
    • Singular and plural values

  • Deploy your extension code to Shopify.

Requirements

Create a Partner account
Create a development store

The development store should be pre-populated with test data, including an order associated with the email address you'll use to log in to the customer account experience.

Shopify CLI

You'll need to use the latest version of Shopify CLI.

Scaffold an app

Scaffold an app that uses Shopify CLI.

Learn how localization works
Manage languages

You'll need to add and publish a second language to your dev store. You'll also need to activate the language in your dev store's primary market.

Project

View on GitHub

Anchor to Create a customer account UI extension for the profile block targetCreate a customer account UI extension for the profile block target

Note

If you already have a customer account UI extension that you want to localize, then you can skip to defining translations.

To create a customer account 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

    cd <directory>

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

    Terminal

    shopify app generate extension --template customer_account_ui --name customer-account-ui-extension

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

    Customer account UI extension file structure

    └── my-app
    └── extensions
    └── my-customer-account-ui-extension
    ├── src
    │ └── CustomerAccount.jsx // The index page of the customer account UI extension
    ├── locales
    │ ├── en.default.json // The default locale for the customer account UI extension
    │ └── fr.json // The locale file for non-regional French translations
    ├── shopify.extension.toml // The config file for the customer account UI extension
    └── package.json

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

    Terminal

    shopify app dev

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

  2. Press p to open the Dev Console.

  3. In the extension list for your app, click on the preview link for your extension.

Anchor to Set up the target for your extensionSet up the target for your extension

Set up the target for your customer account UI extension. Targets control where your extension renders in the customer account flow.

The example code uses the following target:

customer-account.profile.block.render

In your extension's configuration file, for the customer-account.profile.block.render target, create an [[extensions.targeting]] section with the following information:

target: An identifier that specifies where you're injecting code into Shopify.

module: The path to the file that contains the extension code.

Create a file in your extension's src directory for the target. In this example, you'll create a file for the profile block extension. Make sure that the name of the files match the module paths that you specified.

shopify.extension.toml is the configuration file for your extension.

Anchor to Build the profile block extensionBuild the profile block extension

Anchor to Build the UIBuild the UI

Using web components, add a banner component to the Profile page to let the customer know how many points they've earned and their remaining balance.

In this example, the number of points and remaining balance is hardcoded. In a production-ready application, you'd retrieve this information by making an API call to your server, or to the Customer Account API if you're storing loyalty points in metafields.

Customer account UI extensions are limited to specific UI components exposed by the platform for security reasons. Web components allow you to create a UI that feels seamless within the customer account experience, and that inherits a merchant's brand settings.

BannerStackText

Anchor to Define translationsDefine translations

To define translations, you'll adjust the [locale].json files in the extensions/<name-of-customer-account-ui-extension>/locales folder within your app.

Tip

In this tutorial, you'll keep French (fr, non-regional) as an available locale. However, you can also create translations for additional locales.

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 support 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

In this step, you'll learn how to resolve localized 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

In this step, you'll learn how to translate 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

In this step, you'll learn how to translate the loyaltyPoints message, which supports pluralization.

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.

Note

When working with translation keys with pluralization, you must provide the count property. This allows the translate function to determine which pluralization to use, according to Intl Pluralization Rules.

Anchor to Preview the extensionPreview the extension

Preview your extension to make sure that it works as expected.

Anchor to Start your serverStart your server

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

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

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

    Terminal

    shopify app dev

  3. If prompted, select a development store.

  4. Press p to open the Dev Console.

  5. In the extension list for your app, click on the preview link for your extension.

The customer accounts experience opens.

Navigate to the Profile page of a customer account to see your extension in action.

Anchor to Test the extension functionalityTest the extension functionality

The customer account UI extension should now render localized content for en and fr.

To test the extension, add ?locale=fr to the URL.

Anchor to Tutorial complete!Tutorial complete!

Nice work - what you just built could be used by Shopify merchants around the world! Keep the momentum going with these related tutorials and resources.

Anchor to Next StepsNext Steps

Review the APIs

Use JavaScript APIs to access translations for localizing customer account UI extensions.

Extension placement

Explore extension placement options and make informed decisions on where to position them.

Targets

Learn about the targets offered for customer accounts.

UX guidelines

Follow our UX guidelines for customer accounts to ensure a consistent and satisfying user experience.

Web components

Learn about the components you can use to build customer account UI extensions.

Was this page helpful?