Localization practices for Shopify Functions
This guide describes specific localization practices that you can use when creating Shopify Functions.
Localizing title and descriptionAnchor link to section titled "Localizing title and description"
description properties in the
shopify.extension.toml display to merchants in the Shopify admin. To create the best experience for merchants, it's important to localize the values of
Use the following process to provide translations for the
shopify.extension.toml, replace the values for
descriptionwith values prefixed with
t:. The prefix indicates the translation key that Shopify uses when displaying the properties. The following example shows how define the properties:
localesfolder within your function extension to contain translation resources.
Create a JSON file for the default language and translations for these fields.
The name of the file should follow the format
<language-iso>.default.json. Shopify uses these translations for the language in the file name, and for any languages which you don't provide. The keys in the JSON document should match the translation keys used in your
shopify.extension.toml. The following example shows how to set up a JSON file:
Create JSON translation resources for additional languages.
The name of these files should follow the format
<language-iso>.json. Shopify uses these translations for the language in the file name. The keys in the JSON document should match the translation keys used in your
shopify.extension.toml. The following example shows how to create JSON translation resources in French:
Providing translated contentAnchor link to section titled "Providing translated content"
Shopify provides the current locale to function input queries as part of the
Localization object. For example, the Order Discount API returns
Localization from the
localization field on its Input root. Your function should use this locale to provide translated content in function output for any messages that display to customers.
Shopify recommends using language-native libraries to embed translated content in your function WebAssembly module.
Converting money valuesAnchor link to section titled "Converting money values"
When selling to multiple markets, you need to be aware of the currency displayed to the customer at checkout. Function input queries provide monetary values in the customer's displayed currency. Likewise, monetary values output from functions must be in the customer's currency.
You can use the function input's
presentment_currency_rate property for the conversion rate between the store currency and the currency displayed to the customer. You must multiply any merchant-configured amounts by the
presentment_currency_rate when comparing monetary values with the cart, or when outputting value discounts.
For example, if your app allows merchants to configure a fixed amount for a discount function, then you can use a numeric metafield and populate the metafield with the value in the store currency. When your function executes, it must multiply the configured value by the
presentment_currency_rate input to compare the configured subtotal to the customer's cart subtotal in the customer's display currency.
The following example shows how to apply the
presentment_currency_rate on a value discount: