---
title: Localize a customer account UI extension
description: Learn how to localize your customer account UI extension for common use cases, including pluralization and number and currency formatting.
source_url:
  html: https://shopify.dev/docs/apps/build/customer-accounts/localization/localize
  md: https://shopify.dev/docs/apps/build/customer-accounts/localization/localize.md
---

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

## What 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 development store.

* Define translation data and localize the following elements:

  * Numbers using a `formatNumber` function similar to the [`Intl` object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl)
  * Currency using a `formatCurrency` `Intl` object
  * Singular and plural values

* Deploy your extension code to Shopify.

## Requirements

[Create a Partner account](https://www.shopify.com/partners)

[Create a development store](https://shopify.dev/docs/apps/tools/development-stores)

The development store should be pre-populated with [test data](https://shopify.dev/docs/api/development-stores/generated-test-data), including an order associated with the email address you'll use to log in to the customer account experience.

[Shopify CLI](https://shopify.dev/docs/apps/tools/cli/installation)

You'll need to use the [latest version of Shopify CLI](https://shopify.dev/docs/api/shopify-cli#upgrade).

[Scaffold an app](https://shopify.dev/docs/apps/build/scaffold-app)

Scaffold an app that uses Shopify CLI.

[Learn how localization works](https://shopify.dev/docs/apps/build/customer-accounts/localization)

[Manage languages](https://help.shopify.com/en/manual/international/localization-and-translation#managing-languages)

You'll need to add and publish a second language to your development store. You'll also need to [activate the language](https://help.shopify.com/en/manual/international/localization-and-translation#manage-markets-languages) in your development store's primary market.

## Project

[View on GitHub](https://github.com/Shopify/customer-account-tutorials/tree/main/preact/example-customer-account--localize--preact)

### Create 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](#define-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

   ```terminal
   cd <directory>
   ```

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

   ## Terminal

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

   ```text
   └── 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

   ```terminal
   shopify app dev
   ```

   To learn about the processes that are executed when you run `dev`, refer to the [Shopify CLI command reference](https://shopify.dev/docs/api/shopify-cli/app/app-dev).

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

### Set up the target for your extension

Set up the extension target for your customer account UI extension. [Extension targets](https://shopify.dev/docs/api/customer-account-ui-extensions/targets) control where your extension renders in the customer account flow.

The example code uses the following extension 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.

## /preact/example-customer-account--localize--preact/extensions/localize-example/shopify.extension.toml

```toml
api_version = "2025-10"


[[extensions]]
name = "localize-example"
handle = "localize-example"
type = "ui_extension"
uid = "e0260bd4-f328-fedf-994f-bfeb7e42f14a9089f017"


[[extensions.targeting]]
module = "./src/LocalizeExtension.jsx"
target = "customer-account.profile.block.render"


[extensions.capabilities]
api_access = true
```

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`](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions) is the configuration file for your extension.

## /preact/example-customer-account--localize--preact/extensions/localize-example/src/LocalizeExtension.jsx

```jsx
import '@shopify/ui-extensions/preact';
import {render} from "preact";


export default function() {
  render(<LocalizeExtension />, document.body)
}


function LocalizeExtension() {
  const balance = 9.99;
  const formattedBalance = shopify.i18n.formatCurrency(balance);
  
  const points = 10000;
  const formattedPoints = shopify.i18n.formatNumber(points);


  return (
    <s-banner heading={shopify.i18n.translate("bannerHeading")}>
      <s-stack gap="base">
        <s-text>
          {shopify.i18n.translate("loyaltyPoints", {
            count: points,
            formattedPoints
          })}
        </s-text>
        
        <s-text>
          {shopify.i18n.translate("balanceRemaining", {
            formattedBalance
          })}
        </s-text>
      </s-stack>
    </s-banner>
  );
}
```

### Build the profile block extension

#### Build the UI

Using Polaris web components, add a banner 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](https://shopify.dev/docs/api/customer) 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](https://shopify.dev/docs/api/customer-account-ui-extensions#security). Polaris web components allow you to create a UI that feels seamless within the customer account experience, and that inherits a merchant's brand settings.

[s-banner](https://shopify.dev/docs/api/checkout-ui-extensions/polaris-web-components/structure/section)[s-stack](https://shopify.dev/docs/api/checkout-ui-extensions/polaris-web-components/structure/stack)[s-text](https://shopify.dev/docs/api/checkout-ui-extensions/polaris-web-components/titles-and-text/text)

## /preact/example-customer-account--localize--preact/extensions/localize-example/src/LocalizeExtension.jsx

```jsx
import '@shopify/ui-extensions/preact';
import {render} from "preact";


export default function() {
  render(<LocalizeExtension />, document.body)
}


function LocalizeExtension() {
  const balance = 9.99;
  const formattedBalance = shopify.i18n.formatCurrency(balance);
  
  const points = 10000;
  const formattedPoints = shopify.i18n.formatNumber(points);


  return (
    <s-banner heading={shopify.i18n.translate("bannerHeading")}>
      <s-stack gap="base">
        <s-text>
          {shopify.i18n.translate("loyaltyPoints", {
            count: points,
            formattedPoints
          })}
        </s-text>
        
        <s-text>
          {shopify.i18n.translate("balanceRemaining", {
            formattedBalance
          })}
        </s-text>
      </s-stack>
    </s-banner>
  );
}
```

### Define 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.

#### Set 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`.

#### 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()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/select) supports and that's appropriate for the locale.

In subsequent steps, you'll use these keys to translate [`balance`](#translate-the-balance-remaining-message) and [`points`](#translate-the-loyalty-points-message-with-plural-values).

#### 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()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/select) supports and that's appropriate for the locale.

### Localize 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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) object.

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

* **`en`**: `$9.99`
* **`fr`**: `9,99`

## /preact/example-customer-account--localize--preact/extensions/localize-example/src/LocalizeExtension.jsx

```jsx
import '@shopify/ui-extensions/preact';
import {render} from "preact";


export default function() {
  render(<LocalizeExtension />, document.body)
}


function LocalizeExtension() {
  const balance = 9.99;
  const formattedBalance = shopify.i18n.formatCurrency(balance);
  
  const points = 10000;
  const formattedPoints = shopify.i18n.formatNumber(points);


  return (
    <s-banner heading={shopify.i18n.translate("bannerHeading")}>
      <s-stack gap="base">
        <s-text>
          {shopify.i18n.translate("loyaltyPoints", {
            count: points,
            formattedPoints
          })}
        </s-text>
        
        <s-text>
          {shopify.i18n.translate("balanceRemaining", {
            formattedBalance
          })}
        </s-text>
      </s-stack>
    </s-banner>
  );
}
```

### Localize 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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) object.

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

* **`en`**: `10,000`
* **`fr`**: `10 000`

## /preact/example-customer-account--localize--preact/extensions/localize-example/src/LocalizeExtension.jsx

```jsx
import '@shopify/ui-extensions/preact';
import {render} from "preact";


export default function() {
  render(<LocalizeExtension />, document.body)
}


function LocalizeExtension() {
  const balance = 9.99;
  const formattedBalance = shopify.i18n.formatCurrency(balance);
  
  const points = 10000;
  const formattedPoints = shopify.i18n.formatNumber(points);


  return (
    <s-banner heading={shopify.i18n.translate("bannerHeading")}>
      <s-stack gap="base">
        <s-text>
          {shopify.i18n.translate("loyaltyPoints", {
            count: points,
            formattedPoints
          })}
        </s-text>
        
        <s-text>
          {shopify.i18n.translate("balanceRemaining", {
            formattedBalance
          })}
        </s-text>
      </s-stack>
    </s-banner>
  );
}
```

### Translate 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.

## /preact/example-customer-account--localize--preact/extensions/localize-example/src/LocalizeExtension.jsx

```jsx
import '@shopify/ui-extensions/preact';
import {render} from "preact";


export default function() {
  render(<LocalizeExtension />, document.body)
}


function LocalizeExtension() {
  const balance = 9.99;
  const formattedBalance = shopify.i18n.formatCurrency(balance);
  
  const points = 10000;
  const formattedPoints = shopify.i18n.formatNumber(points);


  return (
    <s-banner heading={shopify.i18n.translate("bannerHeading")}>
      <s-stack gap="base">
        <s-text>
          {shopify.i18n.translate("loyaltyPoints", {
            count: points,
            formattedPoints
          })}
        </s-text>
        
        <s-text>
          {shopify.i18n.translate("balanceRemaining", {
            formattedBalance
          })}
        </s-text>
      </s-stack>
    </s-banner>
  );
}
```

### Translate 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.

## /preact/example-customer-account--localize--preact/extensions/localize-example/src/LocalizeExtension.jsx

```jsx
import '@shopify/ui-extensions/preact';
import {render} from "preact";


export default function() {
  render(<LocalizeExtension />, document.body)
}


function LocalizeExtension() {
  const balance = 9.99;
  const formattedBalance = shopify.i18n.formatCurrency(balance);
  
  const points = 10000;
  const formattedPoints = shopify.i18n.formatNumber(points);


  return (
    <s-banner heading={shopify.i18n.translate("bannerHeading")}>
      <s-stack gap="base">
        <s-text>
          {shopify.i18n.translate("loyaltyPoints", {
            count: points,
            formattedPoints
          })}
        </s-text>
        
        <s-text>
          {shopify.i18n.translate("balanceRemaining", {
            formattedBalance
          })}
        </s-text>
      </s-stack>
    </s-banner>
  );
}
```

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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/select).

### Preview the extension

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

#### Start 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

   ```bash
   shopify app dev
   ```

3. If prompted, select a development store.

4. Press `p` to open the developer console.

5. In the developer console page, click the preview link for one of your extension targets.

The customer accounts experience opens.

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

#### Test 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.

## /preact/example-customer-account--localize--preact/extensions/localize-example/shopify.extension.toml

```toml
api_version = "2025-10"


[[extensions]]
name = "localize-example"
handle = "localize-example"
type = "ui_extension"
uid = "e0260bd4-f328-fedf-994f-bfeb7e42f14a9089f017"


[[extensions.targeting]]
module = "./src/LocalizeExtension.jsx"
target = "customer-account.profile.block.render"


[extensions.capabilities]
api_access = true
```

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

### Next Steps

[![](https://shopify.dev/images/icons/32/build.png)![](https://shopify.dev/images/icons/32/build-dark.png)](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/localization)

[Review the APIs](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/localization)

[Use JavaScript APIs to access translations for localizing customer account UI extensions.](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/localization)

[![](https://shopify.dev/images/icons/32/blocks.png)![](https://shopify.dev/images/icons/32/blocks-dark.png)](https://shopify.dev/docs/apps/customer-accounts/best-practices/deciding-extension-placement)

[Extension placement](https://shopify.dev/docs/apps/customer-accounts/best-practices/deciding-extension-placement)

[Explore extension placement options and make informed decisions on where to position them.](https://shopify.dev/docs/apps/customer-accounts/best-practices/deciding-extension-placement)

[![](https://shopify.dev/images/icons/32/blocks.png)![](https://shopify.dev/images/icons/32/blocks-dark.png)](https://shopify.dev/docs/api/customer-account-ui-extensions/targets)

[Extension targets](https://shopify.dev/docs/api/customer-account-ui-extensions/targets)

[Learn about the extension targets offered for customer accounts.](https://shopify.dev/docs/api/customer-account-ui-extensions/targets)

[![](https://shopify.dev/images/icons/32/heart.png)![](https://shopify.dev/images/icons/32/heart-dark.png)](https://shopify.dev/docs/apps/customer-accounts/best-practices/ux-guidelines)

[UX guidelines](https://shopify.dev/docs/apps/customer-accounts/best-practices/ux-guidelines)

[Follow our UX guidelines for customer accounts to ensure a consistent and satisfying user experience.](https://shopify.dev/docs/apps/customer-accounts/best-practices/ux-guidelines)

[![](https://shopify.dev/images/icons/32/blocks.png)![](https://shopify.dev/images/icons/32/blocks-dark.png)](https://shopify.dev/docs/api/customer-account-ui-extensions/polaris-web-components)

[Polaris web components](https://shopify.dev/docs/api/customer-account-ui-extensions/polaris-web-components)

[Learn about the components you can use to build customer account UI extensions.](https://shopify.dev/docs/api/customer-account-ui-extensions/polaris-web-components)