Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

Locale API

The Locale API provides access to the merchant's current locale information in IETF format, allowing you to internationalize your extension content and respond to locale changes through subscription callbacks. The API provides both immediate locale access and change notifications for dynamic internationalization.

Anchor to Use casesUse cases

Internationalization: Internationalize content by displaying text and numbers in the merchant's preferred format.
Regional logic: Implement locale-specific business logic like currency formatting.
Dynamic updates: Dynamically update interfaces when merchants change language settings.
Localized content: Provide locale-aware product descriptions or customer communications.

Support

Targets (25)

Supported targets

Anchor to PropertiesProperties

The Locale API object provides access to the merchant's current locale information. Access the following properties on the API object to retrieve locale data and subscribe to locale changes for dynamic internationalization.

Anchor to subscribable subscribable RemoteSubscribable<string> required: Provides the current IETF-formatted locale (for example, "en-US") and allows you to subscribe to locale changes. Supports only one subscription at a time. To enable multiple subscriptions, use makeStatefulSubscribable on the RemoteSubscribable object. Using makeStatefulSubscribable or related hooks counts as an active subscription.

Examples

import React from 'react';

import {

reactExtension,

useLocaleSubscription,

useApi,

Tile,

} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {

const locale = useLocaleSubscription();

return (

<Tile

title='My App'

subtitle={locale}

enabled

);

};

export default reactExtension('pos.home.tile.render', () => <SmartGridTile />);

Examples

Track locale changes in real time

Description

Subscribe to locale changes to dynamically update your extension's content when the merchant switches languages. This example demonstrates monitoring locale updates and displaying the current locale in IETF format, allowing you to provide properly localized content and adapt to language preferences in real time.

React

import React from 'react';
import {
  reactExtension,
  useLocaleSubscription,
  useApi,
  Tile,
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const locale = useLocaleSubscription();

  return (
    <Tile
      title='My App'
      subtitle={locale}
      enabled
    />
  );
};

export default reactExtension('pos.home.tile.render', () => <SmartGridTile />);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: api.locale.subscribable.initial,
    enabled: true,
  });

  api.locale.subscribable.subscribe((newLocale: string) => {
    tile.updateProps({
      subtitle: newLocale,
    });
  });

  root.append(tile);
});

Anchor to Best practicesBest practices

Implement proper formatting: Use the IETF locale format to implement proper date formatting, number formatting, currency display, and text direction based on the merchant's language and region preferences.
Provide fallback locale handling: Implement fallback behavior for unsupported locales or when localization resources are unavailable, defaulting to a supported language like English.

Anchor to LimitationsLimitations

The Locale API provides read-only access to locale information and can't be used to change the merchant's locale settings, which must be configured through POS system settings.
RemoteSubscribable supports only one subscription at a time. Use makeStatefulSubscribable if you need multiple components to subscribe to locale changes simultaneously.
The locale format follows IETF standards, but the specific locales available depend on POS system configuration and may vary between different Shopify POS installations.

Was this page helpful?