--- title: Localization API description: The API for localizing your extension. api_version: 2025-07 api_name: customer-account-ui-extensions source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/platform-apis/localization-api md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/platform-apis/localization-api.md --- Migrate to Polaris Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-10/upgrading-to-2025-10) to upgrade your extension. # Localization API The API for localizing your extension. ## StandardApi The base API object provided to this and other `customer-account` extension targets. * **i18n** **I18n** **required** Utilities for translating strings, formatting currencies, numbers, and dates according to the buyer's locale. Supports both the buyer's locale and the extension's fallback locale. * **localization** **Localization** **required** The buyer's language, country, and locale context. For formatting utilities, use the `i18n` object instead. ### I18n Utilities for translating strings, formatting currencies, numbers, and dates according to the buyer's locale. Supports both the buyer's locale and the extension's fallback locale. * formatCurrency Returns a localized currency string. This function behaves like the standard \[\`Intl.NumberFormat()\`]\(https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/Intl/NumberFormat) with a style of \`currency\` applied. Uses the buyer's locale by default. ```ts (number: number | bigint, options?: { inExtensionLocale?: boolean; } & NumberFormatOptions) => string ``` * formatDate Returns a localized date string. This function behaves like the standard \[\`Intl.DateTimeFormat()\`]\(https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/Intl/DateTimeFormat) and uses the buyer's locale by default. Formatting \[options]\(https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/Intl/DateTimeFormat#using\_options) can be passed in as options. ```ts (date: Date, options?: { inExtensionLocale?: boolean; } & DateTimeFormatOptions) => string ``` * formatNumber Returns a localized number string. This function behaves like the standard \[\`Intl.NumberFormat()\`]\(https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/Intl/NumberFormat) with a style of \`decimal\` applied. Uses the buyer's locale by default. ```ts (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. ```ts I18nTranslate ``` ### I18nTranslate The signature for the \`i18n.translate()\` function. Returns translated content matching a key in a locale file, with support for pluralization and interpolation. ### Localization The buyer’s language, country, and locale context in the customer account. Use this to adapt content to the buyer’s region and language preferences. * country The buyer's country context in the customer account, as a \`StatefulRemoteSubscribable\` that updates if the buyer changes their country. The value is \`undefined\` if the country is unknown. ```ts StatefulRemoteSubscribable ``` * extensionLanguage 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 doesn't provide French translations at all, this value is the default locale for your extension (that is, the one matching your \`.default.json\` file). ```ts StatefulRemoteSubscribable ``` * language The language the buyer sees in the customer account pages. ```ts StatefulRemoteSubscribable ``` ### Country A buyer's country, identified by its ISO country code. * isoCode The ISO-3166-1 code for this country. ```ts CountryCode ``` ### CountryCode ```ts '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 Represents the buyer's language as a \[BCP-47 standard]\(https://en.wikipedia.org/wiki/IETF\_language\_tag) language tag. * isoCode The \[BCP-47]\(https://en.wikipedia.org/wiki/IETF\_language\_tag) language tag. May include a dash followed by an \[ISO 3166-1 Alpha-2]\(https://en.wikipedia.org/wiki/ISO\_3166-1\_alpha-2) region subtag. ```ts string ``` ## use​Language() Returns the buyer's language, as supported by the extension. If the buyer's actual language is not supported by the extension, it will return the fallback locale used for translations. ### Returns * **Language** ### ### LanguageRepresents the buyer's language as a [BCP-47 standard](https://en.wikipedia.org/wiki/IETF_language_tag) language tag. * **isoCode** **string** The [BCP-47](https://en.wikipedia.org/wiki/IETF_language_tag) language tag. May include a dash followed by an [ISO 3166-1 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) region subtag. ## use​Localization​Country() Returns the country of the buyer's current session, and automatically re-renders your component if the country changes. ### Returns * **Country | undefined** ## use​Extension​Language() Returns the language the buyer sees in the customer account hub. ### Returns * **Language** ### ### LanguageRepresents the buyer's language as a [BCP-47 standard](https://en.wikipedia.org/wiki/IETF_language_tag) language tag. * **isoCode** **string** The [BCP-47](https://en.wikipedia.org/wiki/IETF_language_tag) language tag. May include a dash followed by an [ISO 3166-1 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) region subtag. ## use​I18n() Returns utilities for translating content and formatting values according to the current localization of the user. ### Returns * **I18n** ### ### I18nUtilities for translating strings, formatting currencies, numbers, and dates according to the buyer's locale. Supports both the buyer's locale and the extension's fallback locale. * **formatCurrency** **(number: number | bigint, options?: { inExtensionLocale?: boolean; } & NumberFormatOptions) => string** Returns a localized currency string. This function behaves like the standard [`Intl.NumberFormat()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) with a style of `currency` applied. Uses the buyer's locale by default. * **formatDate** **(date: Date, options?: { inExtensionLocale?: boolean; } & DateTimeFormatOptions) => string** Returns a localized date string. This function behaves like the standard [`Intl.DateTimeFormat()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) and uses the buyer's locale by default. Formatting [options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat#using_options) can be passed in as options. * **formatNumber** **(number: number | bigint, options?: { inExtensionLocale?: boolean; } & NumberFormatOptions) => string** Returns a localized number string. This function behaves like the standard [`Intl.NumberFormat()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) with a style of `decimal` applied. Uses the buyer's locale by default. * **translate** **I18nTranslate** 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. ## use​Translate() Returns the `I18nTranslate` interface used to translate strings. ### Returns * **I18nTranslate** ### ### I18nTranslateThe signature for the `i18n.translate()` function. Returns translated content matching a key in a locale file, with support for pluralization and interpolation. * **export interface I18nTranslate { /** * This returns a translated string matching a key in a locale file. * * @example translate("banner.title") */ ( key: string, options?: {[placeholderKey: string]: ReplacementType | string | number}, ): ReplacementType extends string | number ? string : (string | ReplacementType)[]; }** Examples ### Examples * #### Translating strings ##### React ```jsx import { reactExtension, Text, useTranslate, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.order-status.block.render', () => , ); function Extension() { const translate = useTranslate(); return ( {translate('welcomeMessage')} ); } ``` ##### JavaScript ```js import {extension} from '@shopify/ui-extensions/customer-account'; export default extension( 'customer-account.order-status.block.render', (root, {i18n}) => { const welcomeMsg = i18n.translate( 'welcomeMessage', ); root.appendChild(root.createText(welcomeMsg)); }, ); ``` ##### locales/en.default.json ```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. ##### React ```jsx import { Banner, reactExtension, useI18n, useLocalizationCountry, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.order-index.block.render', () => , ); function Extension() { const i18n = useI18n(); const country = useLocalizationCountry(); if (country?.isoCode === 'CA') { return ( ); } return null; } ``` ##### JavaScript ```js import { extension, Banner, } from '@shopify/ui-extensions/customer-account'; export default extension( 'customer-account.order-index.block.render', (root, {i18n, localization}) => { const country = localization.country.current; if (country?.isoCode === 'CA') { const app = root.createComponent(Banner, { title: i18n.translate( 'canadaPostWarningMessage', ), }); root.appendChild(app); } }, ); ``` ##### locales/en.default.json ```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 in the translate method to get a pluralized string based on the current locale. ##### React ```jsx import { reactExtension, Banner, useApi, useTranslate, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.order-status.block.render', () => , ); function Extension() { const {i18n} = useApi(); const translate = useTranslate(); const points = 10000; const formattedPoints = i18n.formatNumber(points); // Translate the loyalty points message, using pluralization to differentiate messages const loyaltyPointsMsg = translate( 'loyaltyPoints', { count: points, formattedPoints, }, ); return ; } ``` ##### JavaScript ```js import { extension, Banner, } from '@shopify/ui-extensions/customer-account'; export default extension( 'customer-account.order-status.block.render', (root, {i18n}) => { const points = 10000; const formattedPoints = i18n.formatNumber(points); // Translate the loyalty points message, using pluralization to differentiate messages const loyaltyPointsMsg = i18n.translate( 'loyaltyPoints', { count: points, formattedPoints, }, ); const app = root.createComponent(Banner, { title: loyaltyPointsMsg, }); root.appendChild(app); }, ); ``` ##### locales/en.default.json ```json { "loyaltyPoints": { "one": "You have {{formattedPoints}} loyalty point", "other": "You have {{formattedPoints}} loyalty points" } } ```