---
title: Locale API
description: >-
  The Locale API provides access to the merchant's current locale information in
  [IETF format](https://en.wikipedia.org/wiki/IETF_language_tag), 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.
api_version: 2025-07
api_name: pos-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/pos-ui-extensions/2025-07/target-apis/standard-apis/locale-api
  md: >-
    https://shopify.dev/docs/api/pos-ui-extensions/2025-07/target-apis/standard-apis/locale-api.md
---

# Locale API

The Locale API provides access to the merchant's current locale information in [IETF format](https://en.wikipedia.org/wiki/IETF_language_tag), 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 (25)

### Supported targets

* [pos.​cart.​line-item-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/cart-details#cart-details-action-menu-item-)
* [pos.​cart.​line-item-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/cart-details#cart-details-action-modal-)
* [pos.​customer-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/customer-details#customer-details-action-menu-item-)
* [pos.​customer-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/customer-details#customer-details-action-modal-)
* [pos.​customer-details.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/customer-details#customer-details-block-)
* [pos.​draft-order-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/draft-order-details#draft-order-details-action-menu-item-)
* [pos.​draft-order-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/draft-order-details#draft-order-details-action-modal-)
* [pos.​draft-order-details.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/draft-order-details#draft-order-details-block-)
* [pos.​exchange.​post.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/post-exchange#post-exchange-action-menu-item-)
* [pos.​exchange.​post.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/post-exchange#post-exchange-action-modal-)
* [pos.​exchange.​post.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/post-exchange#post-exchange-block-)
* [pos.​home.​modal.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/home-screen#home-screen-action-modal-)
* [pos.​home.​tile.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/home-screen#home-screen-tile-)
* [pos.​order-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/order-details#order-details-action-menu-item-)
* [pos.​order-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/order-details#order-details-action-modal-)
* [pos.​order-details.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/order-details#order-details-block-)
* [pos.​product-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/product-details#product-details-action-menu-item-)
* [pos.​product-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/product-details#product-details-action-modal-)
* [pos.​product-details.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/product-details#product-details-block-)
* [pos.​purchase.​post.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/post-purchase#post-purchase-action-menu-item-)
* [pos.​purchase.​post.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/post-purchase#post-purchase-action-modal-)
* [pos.​purchase.​post.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/post-purchase#post-purchase-block-)
* [pos.​return.​post.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/post-return#post-return-action-menu-item-)
* [pos.​return.​post.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/post-return#post-return-action-modal-)
* [pos.​return.​post.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/post-return#post-return-block-)

## LocaleApi

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

* 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

### 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

  ```tsx
  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

  ```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);
  });
  ```

## Best 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.

## Limitations

* 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.