---
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 in
  real time. The API enables both immediate locale access and dynamic updates
  when merchants change their language settings.
api_version: 2025-10
api_name: pos-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/standard-apis/locale-api
  md: >-
    https://shopify.dev/docs/api/pos-ui-extensions/latest/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 in real time. The API enables both immediate locale access and dynamic updates when merchants change their language settings.

#### Use cases

* **Internationalization:** Display text, dates, and numbers in the merchant's preferred language.
* **Regional logic:** Implement locale-specific logic like currency formatting or address validation.
* **Dynamic updates:** Update interfaces when merchants change their language settings.
* **Localized content:** Provide locale-aware product descriptions or receipt customizations.

Support

Targets (25)

### Supported targets

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

## LocaleApi

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

* current

  ReadonlySignalLike\<string>

  required

  Provides read-only access to the current IETF-formatted locale and allows subscribing to locale changes. The `value` property provides the current locale, and `subscribe` allows listening to changes. Use for internationalization, locale-specific formatting, and reactive updates when merchants change language settings.

### ReadonlySignalLike

Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern.

* subscribe

  Subscribes to locale changes and calls the provided function whenever the locale updates. Returns an unsubscribe function to clean up the subscription. Use to automatically update your extension content when merchants change their language settings during POS sessions.

  ```ts
  (fn: (value: T) => void) => () => void
  ```

* value

  The current value of the locale string in IETF format. For example, \`"en-US"\`, \`"fr-CA"\`, or \`"de-DE"\`. This property provides immediate access to the current locale without requiring subscription setup. Use for one-time locale checks or initial internationalization setup.

  ```ts
  T
  ```

```ts
export interface ReadonlySignalLike<T> {
  /**
   * The current value of the locale string in IETF format. For example, `"en-US"`, `"fr-CA"`, or `"de-DE"`. This property provides immediate access to the current locale without requiring subscription setup. Use for one-time locale checks or initial internationalization setup.
   */
  readonly value: T;
  /**
   * Subscribes to locale changes and calls the provided function whenever the locale updates. Returns an unsubscribe function to clean up the subscription. Use to automatically update your extension content when merchants change their language settings during POS sessions.
   */
  subscribe(fn: (value: T) => void): () => void;
}
```

Examples

### Examples

* #### Monitor locale changes

  ##### Description

  Subscribe to locale changes to monitor the merchant's language settings in real time. This example shows how to use \`shopify.locale.subscribe()\` and \`shopify.locale.ianaCode\` to detect when the merchant changes their language preference. This enables dynamic content localization and internationalized user experiences.

  ##### jsx

  ```jsx
  import {render} from 'preact';
  import {useState, useEffect} from 'preact/hooks';

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

  const Extension = () => {
    const [locale, setLocale] = useState(
      shopify.locale.current.value
    );

    useEffect(() => {
      const unsubscribe = shopify.locale.current.subscribe((newLocale) => {
        setLocale(newLocale);
      });
      return unsubscribe;
    }, []);

    return (
      <s-tile
        heading="My App"
        subheading={locale}
      />
    );
  };
  ```

## Best practices

* **Handle locale changes reactively:** Use the `subscribe` method to automatically update your extension content when merchants change their language settings.
* **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.
* **Cache localized content:** Consider caching translated content and locale-specific formatting to improve performance, but ensure you invalidate caches when locale changes occur through subscription updates.
* **Provide fallback locale handling:** Implement fallback behavior for unsupported locales or when localization resources are unavailable, defaulting to a supported language like English.