Localization practices for Shopify Functions

The function name and 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 name and description.

Use the following process to provide translations for the name and description properties:

1. In shopify.extension.toml, replace the values for name and description with 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:

2. Create a locales folder within your function extension to contain translation resources.

3. 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:

4. 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:

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.

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: