Choose a version:

Localization

The API for localizing your extension.

Anchor to standardapiStandardApi

The base API object provided to this and other customer-account extension targets.

Anchor to i18n i18n required: Utilities for translating content and formatting values according to the current localization of the user.
Anchor to localization localization required: Details about the language of the buyer.

I18n

formatCurrency
Returns a localized currency value. This function behaves like the standard `Intl.NumberFormat()` with a style of `currency` applied. It uses the buyer's locale by default.
```
(number: number | bigint, options?: { inExtensionLocale?: boolean; } & NumberFormatOptions) => string
```
formatDate
Returns a localized date value. This function behaves like the standard `Intl.DateTimeFormatOptions()` and uses the buyer's locale by default. Formatting options can be passed in as options.
```
(date: Date, options?: { inExtensionLocale?: boolean; } & DateTimeFormatOptions) => string
```
formatNumber
Returns a localized number. This function behaves like the standard `Intl.NumberFormat()` with a style of `decimal` applied. It uses the buyer's locale by default.
```
(number: number | bigint, options?: { inExtensionLocale?: boolean; } & NumberFormatOptions) => string
```
translate
Returns translated content in the buyer's locale, as supported by the extension. - `options.count` is a special numeric value used in pluralization. - The other option keys and values are treated as replacements for interpolation. - If the replacements are all primitives, then `translate()` returns a single string. - If replacements contain UI components, then `translate()` returns an array of elements.
```
I18nTranslate
```

export interface I18n {
  /**
   * Returns a localized number.
   *
   * This function behaves like the standard `Intl.NumberFormat()`
   * with a style of `decimal` applied. It uses the buyer's locale by default.
   *
   * @param options.inExtensionLocale - if true, use the extension's locale
   */
  formatNumber: (
    number: number | bigint,
    options?: {inExtensionLocale?: boolean} & Intl.NumberFormatOptions,
  ) => string;

  /**
   * Returns a localized currency value.
   *
   * This function behaves like the standard `Intl.NumberFormat()`
   * with a style of `currency` applied. It uses the buyer's locale by default.
   *
   * @param options.inExtensionLocale - if true, use the extension's locale
   */
  formatCurrency: (
    number: number | bigint,
    options?: {inExtensionLocale?: boolean} & Intl.NumberFormatOptions,
  ) => string;

  /**
   * Returns a localized date value.
   *
   * This function behaves like the standard `Intl.DateTimeFormatOptions()` and uses
   * the buyer's locale by default. Formatting options can be passed in as
   * options.
   *
   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat0
   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat#using_options
   *
   * @param options.inExtensionLocale - if true, use the extension's locale
   */
  formatDate: (
    date: Date,
    options?: {inExtensionLocale?: boolean} & Intl.DateTimeFormatOptions,
  ) => string;

  /**
   * Returns translated content in the buyer's locale,
   * as supported by the extension.
   *
   * - `options.count` is a special numeric value used in pluralization.
   * - The other option keys and values are treated as replacements for interpolation.
   * - If the replacements are all primitives, then `translate()` returns a single string.
   * - If replacements contain UI components, then `translate()` returns an array of elements.
   */
  translate: I18nTranslate;
}

I18nTranslate

This defines the i18n.translate() signature.

export interface I18nTranslate {
  /**
   * This returns a translated string matching a key in a locale file.
   *
   * @example translate("banner.title")
   */
  <ReplacementType = string>(
    key: string,
    options?: {[placeholderKey: string]: ReplacementType | string | number},
  ): ReplacementType extends string | number
    ? string
    : (string | ReplacementType)[];
}

Localization

country
The country context of the buyer sees in the customer account. It will update if the buyer changes the country in the customer account If the country is unknown, then the value is undefined.
```
SubscribableSignalLike<Country | undefined>
```
extensionLanguage
This is the buyer's language, as supported by the extension. If the buyer's actual language is not supported by the extension, this is the fallback locale used for translations. For example, if the buyer's language is 'fr-CA' but your extension only supports translations for 'fr', then the `isoCode` for this language is 'fr'. If your extension does not provide french translations at all, this value is the default locale for your extension (that is, the one matching your .default.json file).
```
SubscribableSignalLike<Language>
```
language
The language the buyer sees in the customer account hub.
```
SubscribableSignalLike<Language>
```

export interface Localization {
  /**
   * The language the buyer sees in the customer account hub.
   */
  language: SubscribableSignalLike<Language>;

  /**
   * This is the buyer's language, as supported by the extension.
   * If the buyer's actual language is not supported by the extension,
   * this is the fallback locale used for translations.
   *
   * For example, if the buyer's language is 'fr-CA' but your extension
   * only supports translations for 'fr', then the `isoCode` for this
   * language is 'fr'. If your extension does not provide french
   * translations at all, this value is the default locale for your
   * extension (that is, the one matching your .default.json file).
   */
  extensionLanguage: SubscribableSignalLike<Language>;

  /**
   * The country context of the buyer sees in the customer account.
   * It will update if the buyer changes the country in the customer account
   * If the country is unknown, then the value is undefined.
   */
  country: SubscribableSignalLike<Country | undefined>;
}

SubscribableSignalLike

Represents a read-only value managed on the main thread that an extension can subscribe to. Example: Checkout uses this to manage the state of an object and communicate state changes to extensions running in a sandboxed web worker. This interface is compatible with [Preact's ReadonlySignal](https://github.com/preactjs/signals/blob/a023a132a81bd4ba4a0bebb8cbbeffbd8c8bbafc/packages/core/src/index.ts#L700-L709). Some fields are deprecated but still supported for backwards compatibility. In version 2025-10, [`StatefulRemoteSubscribable`](https://github.com/Shopify/remote-dom/blob/03929aa8418a89d41d294005f219837582718df8/packages/async-subscription/src/types.ts#L17) was replaced with `ReadonlySignalLike`. Checkout will remove the old fields some time in the future.

current
```
T
```
destroy
```
() => Promise<void>
```
subscribe
Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value.
```
(fn: (value: T) => void) => () => void
```
value
The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup.
```
T
```

export interface SubscribableSignalLike<T> extends ReadonlySignalLike<T> {
  /**
   * @deprecated Use `.value` instead.
   */
  readonly current: T;
  /**
   * @deprecated No longer needed. Use Preact Signal management instead.
   */
  destroy(): Promise<void>;
}

Country

isoCode
The ISO-3166-1 code for this country.
```
CountryCode
```

export interface Country {
  /**
   * The ISO-3166-1 code for this country.
   * @see https://www.iso.org/iso-3166-country-codes.html
   */
  isoCode: CountryCode;
}

CountryCode

'AC' | 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AN' | 'AO' | 'AR' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BV' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PS' | 'PT' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TA' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VN' | 'VU' | 'WF' | 'WS' | 'XK' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' | 'ZZ'

Language

isoCode
The BCP-47 language tag. It may contain a dash followed by an ISO 3166-1 alpha-2 region code.
```
string
```

export interface Language {
  /**
   * The BCP-47 language tag. It may contain a dash followed by an ISO 3166-1 alpha-2 region code.
   *
   * @example 'en' for English, or 'en-US' for English local to United States.
   * @see https://en.wikipedia.org/wiki/IETF_language_tag
   * @see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
   */
  isoCode: string;
}

Examples

/* See the locales/en.default.json tab for the translation keys and values for this example */

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

import {render} from 'preact';

export default async () => {

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

};

function Extension() {

return (

<s-text>

{shopify.i18n.translate('welcomeMessage')}

</s-text>

);

}

Examples

Translating strings

Extension.jsx

/* See the locales/en.default.json tab for the translation keys and values for this example */
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  return (
    <s-text>
      {shopify.i18n.translate('welcomeMessage')}
    </s-text>
  );
}

locales/en.default.json

{
  "welcomeMessage": "Welcome to our store!"
}

Getting the country of the customer

Description

You can access the current country of a customer to implement country specific logic.

Extension.jsx

/* See the locales/en.default.json tab for the translation keys and values for this example */
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const countryCode =
    shopify.localization?.country?.value?.isoCode;

  if (countryCode === 'CA') {
    return (
      <s-banner status="warning">
        {shopify.i18n.translate(
          'canadaPostWarningMessage',
        )}
      </s-banner>
    );
  }
}

locales/en.default.json

{
  "canadaPostWarningMessage": "Canada Post has issued a red delivery service alert for Ontario due to a severe snowstorm, suspending package delivery and collection for the week."
}

Translating strings with pluralization

Description

You can use the count option to get a pluralized string based on the current locale.

Extension.jsx

/* See the locales/en.default.json tab for the translation keys and values for this example */
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const points = 10000;
  const formattedPoints =
    shopify.i18n.formatNumber(points);

  // Translate the loyalty points message, using pluralization to differentiate messages
  const loyaltyPointsMsg = shopify.i18n.translate(
    'loyaltyPoints',
    {
      count: points,
      formattedPoints,
    },
  );

  return <s-banner>{loyaltyPointsMsg}</s-banner>;
}

locales/en.default.json

{
  "loyaltyPoints": {
    "one": "You have {{formattedPoints}} loyalty point",
    "other": "You have {{formattedPoints}} loyalty points"
  }
}

Was this page helpful?