Localization for shipping methods 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

  1. Install the @shopify/i18n-as dependency.

  2. In your script project, create the following subdirectory to store all your locale files: locales/

  3. Create the locale configuration file (i18n.config.json):

    1. In your project's root directory, manually create a file and name it i18n.config.json.
    2. Open this file and add the following code:

    This sets the directory to the locale files.

  4. Create a locale file for each language and dialect that the store supports:

    1. 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 fi.json.

    2. Add translation keys to the file. The key field associates translatable content with its translations. The value field 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 Method is shown to the customer at checkout.

Add translation keys to your script

Both the Payment methods and Shipping methods APIs do the following:

  • take as input the order's locale with PurchaseProposal.locale
  • output renamed methods with Result.renameResponse
  1. In your script, import @shopify/as-i18n. For example:

  2. Wherever you want to use a translation, enter translate(locale, "key-name"). For example:

Test locales

When you write unit tests for a script that uses translations, include tests that the check the translation strings.

  1. Include the locale as the input to your test functions.

    For example, include .setLocale(locale) in Domain.TestHelper.PurchaseProposalBuilder:

  2. Write tests that check the output of the translated strings.

    For example:


The following is an example of a script that uses localization:

Next steps