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 in real time. The API enables both immediate locale access and dynamic updates when merchants change their language settings.

Anchor to Use casesUse 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 (28)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides the merchant's current locale information. Access the following properties on shopify to get locale data and subscribe to locale changes for content internationalization.

Anchor to current current <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 value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value.
```
(fn: (value: T) => void) => () => void
```
value
The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup.
```
T
```

Examples

jsx

import {render} from 'preact';

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

// Allows the use of `shopify.locale.current.value` as a stateful subscription.

import '@shopify/ui-extensions/preact';

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}

);

};

Examples

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

import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';
// Allows the use of `shopify.locale.current.value` as a stateful subscription.
import '@shopify/ui-extensions/preact';

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

Anchor to Best practicesBest 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.

Was this page helpful?