Sending multilingual emails

For stores that offer content translated into different languages, it can be important to also send customer emails in their preferred language.

When building an email task that supports multiple languages, there are two important pieces:

1. Retrieving the customer's language preference
2. Allowing the task to be configured for multiple languages 

Retrieving the customer's language preference

As of this writing, Shopify only makes the customer's locale information available via GraphQL (see Querying Shopify). Further, this is only available in version 2020-01 and later of the Shopify API (see Choosing a Shopify API version).

You can use something like this to retrieve the customer's locale:

{% capture query %}
  query {
    customer(id: {{ customer.admin_graphql_api_id | json }}) {
      locale
    }
  }
{% endcapture %}

{% assign result = query | shopify %}

{% if event.preview %}
  {% capture result_json %}
    {
      "data": {
        "customer": {
          "locale": {{ options.email_subject_translations__keyval_required.first.first | json }}
        }
      }
    }
  {% endcapture %}

  {% assign result = result_json | parse_json %}
{% endif %}

{% assign locale = result.data.customer.locale %}

Note: We've elected to include a {% if event.preview %} block, a common technique when generating preview actions based on dynamic API data (see Preview Actions).

Task configuration

Generally, this is as simple as adding keyval options to your task, allowing the merchant to configure the task with a locale on the left, and text on the right. To this end, you could use variables like options.email_subject_translation__keyval and options.email_subject_translation__keyval, as in this example:

{% capture query %}
  query {
    customer(id: {{ customer.admin_graphql_api_id | json }}) {
      locale
    }
  }
{% endcapture %}

{% assign result = query | shopify %}

{% assign email_subject = options.email_subject_translations__keyval_required[locale] %}
{% assign email_body = options.email_body_translations__keyval_multiline_required[locale] %}

{% action "email" %}
  {
    "to": {{ customer.email | json }},
    "subject": {{ email_subject | json }},
    "body": {{ email_body | newline_to_br | json }},
    "reply_to": {{ shop.customer_email | json }},
    "from_display_name": {{ shop.name | json }}
  }
{% endaction %}

This results in a task configuration screen resembling the following:

It's also a good idea to ask for a default locale, in the event that a customer passes through whose locale doesn't have a translation.

{% assign default_locale = options.default_locale__required %}

{% if options.email_subject_translations__keyval_required[default_locale] == blank %}
  {% error "Please add an email subject for your default locale." %}
{% elsif options.email_body_translations__keyval_multiline_required[default_locale] == blank %}
  {% error "Please add an email body for your default locale." %}
{% endif %}

{% assign email_subject = options.email_subject_translations__keyval_required[locale] %}
{% assign email_body = options.email_body_translations__keyval_multiline_required[locale] %}

{% if email_subject == blank %}
  {% log message: "Couldn't find an email subject for this locale; falling back to the default", locale: locale %}
  {% assign email_subject = options.email_subject_translations__keyval_required[default_locale] %}
{% endif %}

{% if email_body == blank %}
  {% log message: "Couldn't find an email subject for this locale; falling back to the default", locale: locale %}
  {% assign email_body = options.email_body_translations__keyval_multiline_required[locale] %}
{% endif %}

Example

For a complete example, involving all the techniques on this page, see this task: Send a welcome email to new customers, in their language.