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.

Use 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 (17)

Supported targets

Anchor to propertiesProperties

The LocaleApi object provides access to current locale information and change notifications. Access these properties through api.locale to retrieve and monitor locale data.

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?