Localizing checkout UI extensions
What is localization?Anchor link to section titled "What is localization?"
Localization is the process of adapting content to meet the language and cultural requirements of a specific country or region. Shopify localizes checkout UI extensions by resolving customer and shop locales against the extensions's translation data.
The following diagram shows customers in France and Canada that are interacting with a store in Germany. The customers receive localized experiences based on the translation data that's supplied by an app extension.
How it worksAnchor link to section titled "How it works"
You supply translation data for your extension's strings in
.json-formatted locale files, which are stored in the extension's
When a customer checks out, the checkout UI extension queries the locale files for a match against locale data and translates the extension UI.
To choose a translation, Shopify evaluates locale data in the following order of precedence:
The customer locale. Example:
The non-regional customer locale. Example:
The shop locale. Example:
The non-regional shop locale. Example:
The extension's default locale.
Locale filesAnchor link to section titled "Locale files"
Locale files are UTF-8-encoded JSON files that contain a set translations for your UI extension's strings. You can create non-regional, regional, and default locales.
Translations consist of key/value pairs. You can supply singular and plural translations.
Non-regional localeAnchor link to section titled "Non-regional locale"
Use an IETF BCP 47 language tag:
Regional localeAnchor link to section titled "Regional locale"
ISO 3166-1 region code after the language tag:
Default localeAnchor link to section titled "Default locale"
.default between the locale and the
.json file extension:
PluralizationAnchor link to section titled "Pluralization"
The implementation of plural translation keys follows the language plural rules included in the Common Locale Data Repository. You can specify any pluralization key that
Intl.PluralRules.select() supports and that's appropriate for the locale.
The following are additional details for localizing pluralized content:
The call to
translate()must have a single count option.
countto determine a plural key for the given locale.
The translation must define all possible plural keys for the given locale. For example:
LimitationsAnchor link to section titled "Limitations"
Checkout branding is available only to Shopify Plus merchants.
Localization is only supported for checkout UI extensions. Localization for post-purchase extensions isn't supported. Shopify Functions have limited support for localization.
Merchants can't override or add translations.
Complex pluralization, like for dynamic numeric ranges, isn't supported. For example, you can't localize a phrase that lists a numeric range of items left in stock. This is because the range will change as items are sold, and for some languages, the localizer would need to update the grammar as well.
Translations can't contain HTML.
i18nfunctions to localize content. However, if you need to use
Intlfunctions for more advanced formatting, only the following are supported:
- Learn how to localize a checkout UI extension.