Localize a POS UI extension

In this tutorial, you'll use JavaScript API functions to localize a POS UI extension that applies a discount to the cart. You'll localize extension text, format discount percentages and monetary values, and handle plural forms for item counts. 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 POS UI extension that appears on the smart grid 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

Scaffold an app

Scaffold an app using Shopify CLI. This tutorial is compatible with the extension-only template.

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 POS smart grid extensionCreate a POS smart grid extension

Note

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

Anchor to Create the extensionCreate the extension

Navigate to your app directory.

Terminal
cd <directory>
Run the following command to create a new extension:

Terminal
shopify app generate extension
Select POS smart grid.

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 with a locales folder added:

POS UI extension file structure
└── my-app
└── extensions
└── my-pos-ui-extension
├── src
│ ├── Modal.jsx // The modal component of the POS UI extension
│ └── Tile.jsx // The tile component of the POS UI extension
├── locales
│ ├── en.default.json // The default locale for the POS UI extension
│ └── fr.json // The locale file for non-regional French translations
├── shopify.extension.toml // The config file for the POS UI extension
└── package.json
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.
Press p to open the developer console. In the developer console page, 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 POS UI extension. Targets control where your extension renders in the POS.

The example code uses these targets:

pos.home.tile.render
pos.home.modal.render

Anchor to Configure the tile targetConfigure the tile target

In your extension's shopify.extension.toml configuration file, create [[extensions.targeting]] sections 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.

You'll create two targeting sections, one for pos.home.tile.render and one for pos.home.modal.render.

Anchor to Configure the modal targetConfigure the modal target

Add another [[extensions.targeting]] section for the pos.home.modal.render target. This target renders the modal that opens when the tile is tapped.

Anchor to Build the POS smart grid extensionBuild the POS smart grid extension

In this step, you'll build the UI components for your POS extension. You'll create a Tile that appears on the smart grid and a Modal that opens when the tile is tapped.

Anchor to Build the Tile UIBuild the Tile UI

The Tile component renders on the POS smart grid and opens a Modal when tapped. Add the following code to create a tile that displays discount information and triggers the discount modal.

/example-pos-ui-extensions--localize--preact/extensions/my-pos-ui-extension/src/Tile.jsx

import {render} from 'preact';

import {useState, useEffect} from 'preact/hooks';

// Allows the use of `shopify.cart.current.value` as a stateful subscription.

import '@shopify/ui-extensions/preact';

export default async () => {

render(<Extension />, document.body);

}

function Extension() {

const {i18n} = shopify;

const shouldDisable = (subtotal) => {

return Number(subtotal) <= 100;

};

const [disabled, setDisabled] = useState(shouldDisable(shopify.cart.current.value.subtotal));

useEffect(() => {

const unsubscribe = shopify.cart.current.subscribe((cart) => {

setDisabled(shouldDisable(cart.subtotal));

});

return unsubscribe;

}, []);

return (

<s-tile

heading={i18n.translate('name')}

subheading={i18n.translate('availableDiscounts')}

onClick={() => shopify.action.presentModal()}

disabled={disabled}

);

}

Anchor to Build the modal UIBuild the modal UI

Using web components, add buttons and text to the modal. This example also uses a tile component to trigger the modal.

Button Text Scroll box

Anchor to Define translationsDefine translations

To define translations, you'll adjust the [locale].json files in the extensions/<name-of-pos-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 you 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 itemCount.

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

Now add the translation strings you need to support French translations, zero, 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 localize the currency:

Add the formatCurrency function provided by i18n. The function wraps the standard Intl object.

Depending on the current locale, 10 resolves to the following localized currency formats:

en: $10.00
fr: 10,00 $

Anchor to Localize numbersLocalize numbers

In this step, you'll resolve localized numbers:

Localize number formatting using the formatNumber function provided by i18n. The function wraps the standard Intl object.

Depending on the current locale, 25.5 resolves to one of the following localized number formats:

en: 25.5
fr: 25,5

Anchor to Translate the discount applied messageTranslate the discount applied message

In this step, you'll translate the discount applied message:

Call the translate function, which sends the discountApplied variable so that it can be used in the translation string.

Anchor to Translate the items in cart messageTranslate the items in cart message

In this step, you'll translate the itemCount message, which supports pluralization:

Use the translate function to pass in the count of how many items are in the cart. The i18n system uses count to render the appropriate plural form in the current locale.

Note

When working with translation keys with pluralization, you must provide the count property. This enables 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 it works as expected.

Anchor to Start your serverStart your server

Navigate to your app directory and start your development server.
Press p to open the developer console.
In the developer console, click on view mobile or scan the provided QR code to preview your extension.

Anchor to Test the extension functionalityTest the extension functionality

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

To test the extension, change the language in your device settings.

Anchor to Deploy and releaseDeploy and release

Congratulations! You've created a POS UI extension with region-specific localization. Now you can deploy and release your extension.

/example-pos-ui-extensions--localize--preact/extensions/my-pos-ui-extension/shopify.extension.toml

api_version = "2025-10"

[[extensions]]

type = "ui_extension"

# Change the merchant-facing name of the extension in locales/en.default.json

name = "t:name"

uid = "11fd348b-1de3-4793-6892-baa416fc3df29b4377b5"

handle = "discount"

description = "Add discount"

# module: file that contains your extension’s source code

# target: location where your extension appears in POS

[[extensions.targeting]]

module = "./src/Tile.jsx"

target = "pos.home.tile.render"

[[extensions.targeting]]

module = "./src/Modal.jsx"

target = "pos.home.modal.render"

/example-pos-ui-extensions--localize--preact/extensions/my-pos-ui-extension/src/Tile.jsx

import {render} from 'preact';

import {useState, useEffect} from 'preact/hooks';

// Allows the use of `shopify.cart.current.value` as a stateful subscription.

import '@shopify/ui-extensions/preact';

export default async () => {

render(<Extension />, document.body);

}

function Extension() {

const {i18n} = shopify;

const shouldDisable = (subtotal) => {

return Number(subtotal) <= 100;

};

const [disabled, setDisabled] = useState(shouldDisable(shopify.cart.current.value.subtotal));

useEffect(() => {

const unsubscribe = shopify.cart.current.subscribe((cart) => {

setDisabled(shouldDisable(cart.subtotal));

});

return unsubscribe;

}, []);

return (

<s-tile

heading={i18n.translate('name')}

subheading={i18n.translate('availableDiscounts')}

onClick={() => shopify.action.presentModal()}

disabled={disabled}

);

}

/example-pos-ui-extensions--localize--preact/extensions/my-pos-ui-extension/locales/en.default.json

{

"name": "Discount",

"itemCount": {

"zero": "No items in cart",

"one": "{{count}} item in cart",

"other": "{{count}} items in cart"

"availableDiscounts": "View discount options",

"discountApplied": "Discount applied!",

"modalTitle": "Choose a discount"

}

/example-pos-ui-extensions--localize--preact/extensions/my-pos-ui-extension/locales/fr.json

{

"name": "Réduction",

"itemCount": {

"zero": "Aucun article dans le panier",

"one": "{{count}} article dans le panier",

"other": "{{count}} articles dans le panier"

"availableDiscounts": "Voir les options de réduction",

"discountApplied": "Réduction appliquée!",

"modalTitle": "Choisir une réduction"

}

Was this page helpful?

Anchor to What you'll learnWhat you'll learn

Requirements

Project

Anchor to Create a POS smart grid extensionCreate a POS smart grid extension

Anchor to Create the extensionCreate the extension

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

Anchor to Configure the tile targetConfigure the tile target

Anchor to Configure the modal targetConfigure the modal target

Anchor to Build the POS smart grid extensionBuild the POS smart grid extension

Anchor to Build the Tile UIBuild the Tile UI

Anchor to Build the modal UIBuild the modal UI

Anchor to Define translationsDefine translations

Anchor to Set the default localeSet the default locale

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

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

Anchor to Localize the currencyLocalize the currency

Anchor to Localize numbersLocalize numbers

Anchor to Translate the discount applied messageTranslate the discount applied message

Anchor to Translate the items in cart messageTranslate the items in cart message

Anchor to Preview the extensionPreview the extension

Anchor to Start your serverStart your server

Anchor to Test the extension functionalityTest the extension functionality

Anchor to Deploy and releaseDeploy and release

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

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