Localization for scripts
You can localize payment and shipping method names in your scripts and make these scripts available to stores that serve multiple languages and cultures.
How it works
Instead of hard-coding the translated text strings in the script, create separate resource files for each locale that the store supports. In these locale files, enter the translation keys and values. The translated values are included in the script when it's pushed.
When the script runs at checkout, it reads the order's locale and offers the method names in the customer's preferred language.
A locale file is a JSON file that contains a set of translations for the text strings used in a script. You need separate locale files for every language that the store supports. There is no default locale file. Instead, the names of the translation keys are used as the default values when the script doesn't support a locale.
Create the locale files
In your script project, create the following subdirectory to store all your locale files: locales/
Create the locale configuration file (i18n.config.json):
- In your project's root directory, manually create a file and name it i18n.config.json.
- Open this file and add the following code:
This sets the directory to the locale files.
Create a locale file for each language and dialect that the store supports:
Create the files manually and name them using the standard IETF language tag format. The first subtag uses a 2-letter language code (ISO 639-1) and the second subtag uses a two-letter country code (ISO 3166-1 alpha-2) written in upper case.
For example, for "French - Canada" you would use
fr-CA.json, for "English - Great Britain" you would use
en-GB.json, and for "Finnish - all regions" you would use
Add translation keys to the file. The
keyfield associates translatable content with its translations. The
valuefield shows the translatable content itself.
For example, in en.json:
For example, in fr.json:
When the value for a given key is missing, or an unsupported locale is passed to the script, then the key name is used as the translation value. Name your translation keys by setting them equal to their default translation values.
For example, suppose that a store supports English, French, and Portuguese locales. The script calls
translate(locale, "Renamed Method")and there are only locale files for English and French. When the locale is Portuguese, then
Renamed Methodis shown to the customer at checkout.
Add translation keys to your script
- take as input the order's locale with
- output renamed methods with
In your script, import
@shopify/as-i18n. For example:
Wherever you want to use a translation, enter
translate(locale, "key-name"). For example:
When you write unit tests for a script that uses translations, include tests that the check the translation strings.
localeas the input to your test functions.
For example, include
Write tests that check the output of the translated strings.
The following is an example of a script that uses localization: