Overview

Cordial's flexible messaging platform makes it possible for you to deliver content in a contact's preferred language. This article will show you how.

Localized messages using a contact attribute and Smarty

How to go about delivering message content in different languages is commonly determined by the complexity of your multi-language message campaign. If your campaign requires supporting only a few languages, a suitable solution is to use a combination of a contact attribute and Smarty logic. The contact attribute is used to store the contact's preferred language while the Smarty logic tests the value of this attribute and displays the appropriate content.

Here are the steps for creating a message template that supports the use of three languages. This example uses English, Spanish, and French, but other languages can easily be substituted.

1. Create a contact attribute called "lang". Once created, this attribute can be referenced in a message template with the following Smarty code:

{$contact.lang}

This contact variable can be utilized in both the subject line as well as the body of a message.

2. Modify your contact imports, API calls, and JavaScript Listeners so the contact attribute you created in Step 1 is populated with a contact's preferred language.

It's common practice to use language abbreviations when storing language preferences.  For example, the languages English, Spanish, and French would be stored as "EN", "SP", and "FR", respectively.

3. Within the body of your message template, create a default language variable using the following Smarty code:

{$default_lang = "EN"} 

This default value will be used if a language preference has not been set for a contact.

4. Create an if statement using Smarty that checks the "lang" contact attribute and then assigns the variable's value to a new variable called "display_lang". The display_lang variable is then used in a second if statement that checks its value in order to display the appropriate message content. Here's the Smarty code.

{if !empty($contact.lang)}
      {$display_lang = $contact.lang} 
  {else}
      {$display_lang = $default_lang}
  {/if}
  {if $display_lang == "EN"}
      You've recently browsed the following items
  {elseif $display_lang == "SP"}
      Has navegado recientemente por los siguientes artículos
  {elseif $display_lang == "FR"}
      Vous avez récemment parcouru les articles suivants
{else}
    You've recently browsed the following items
{/if}

This logic can also be used in a message subject line.

Localized messages using supplements

If your messaging needs require supporting more than a small number of languages, using a Smarty if statement to determine what content to send to your customers can quickly become unwieldy.

Fortunately, there are alternative options within Cordial to support more complex language localization scenarios. One option is Cordial Supplements. Supplements are a useful mechanism for implementing complex multi-language email campaigns.

Here are the steps to create a localization language message using supplements.

1. Create a contact attribute called "lang". Once created, this attribute can be referenced in a message template with the following Smarty code:

{$contact.lang}

This contact variable can be utilized in both the subject line as well as the body of a message.

2. Create a supplement and name it "localized_language". Then create an indexed supplement field called "lang". Lastly, create two more supplement fields called "subject" and "body". These two fields should not be indexed.

When a supplement field is used to identify and retrieve supplement records, the field must be indexed. In this example we are going to search for records according to values present in the "lang" field, so this field will need to be indexed.

3. Import records into the supplement. These records should contain a value for the three fields in the supplement, "lang", "subject", and "body".

All supplement records must include a unique value in a field called ID. This value is usually an incrementing numeric value.

5. Within the body of your message template create a default language variable using the following Smarty code:

{$default_lang = "EN"} 

This default value will be used if a language preference has not been set for a contact.

6. Create an if statement that checks the "lang" contact attribute and assign its value to a variable called "display_lang". This variable is then used to retrieve supplement records from the supplement that was created in Step 2.

{if !empty($contact.lang)}
      {$display_lang = $contact.lang} 
  {else}
      {$display_lang = $default_lang}
  {/if}

7. The $utils->getSupplementRecords() call is used to retrieve the content and subject of the message. The first parameter of this call is the supplement key; the second argument is used to retrieve records by the value of an indexed field. In our example, we'll use the $display_lang variable created in Step 5 to retrieve the records. Here's the call:

$utils->getSupplementRecords("localized_language", ["lang" => $display_lang]) 

8. Display the supplement record in a message by storing the result of the $utils->getSupplementRecords call to a variable and then referencing this variable in the message template.

{$localized_content=$utils->getSupplementRecords('localized_language',["lang" => $display_lang])}
                  {$localized_content[0].body} 

Localized messages using an external JSON file

Externally hosted JSON feeds offer another option with which to implement message localization. In this scenario, the localized language content is stored in an externally hosted JSON feed and accessed via Cordial's getJson method. Here are the steps for creating a localized language message campaign using a JSON feed.

1. Create a contact attribute called "lang". Once created, this attribute can be referenced in a message template with the following Smarty code:

{$contact.lang}

This contact variable can be utilized in both the subject line as well as the body of a message.

2. Create an externally hosted JSON file. Below is an example of a typical feed.

[
    {
      "lang": "EN",
      "subject": "We saw you checking us out",
      "body": "Please review the following recently browse items"
    },
    {
      "lang": "SP",
      "subject": "Te vimos revisándonos",
      "body": "Por favor revise los siguientes elementos de búsqueda recientes"
    },
    {
     "lang": "FR",
      "subject": "Nous vous avons vu nous vérifier",
      "body": "Veuillez examiner les éléments de navigation récents suivants"
    }
  ]

3. When this type of JSON file is used, it's necessary to first retrieve the file using the $utils->getJson API call and then loop over the entire result set in order to display the correct localized language content. Here's an example of the Smarty code:

  {$localized_content=$utils->getJson('http://p5.zdassets.com/hc/theme_assets/656597/200049057/localized_content.json')} 
  {foreach $localized_content as $content}
      {if $content.lang = $display_lang}
      {$show_content = $content}
      {break}
  {/if}
{/foreach} 
{$show_content.subject} {$show_content.body} 

4. Alternatively, the JSON feed can be structured so that the language preference is a key to an object that contains the subject and body information. This format allows the the appropriate content to be accessed without the need for looping.

{
 "EN": {
 "subject": "We saw you checking us out",
 "body": "Please review the following recently browsed items"
 },
 "SP": {
 "subject": "Te vimos revisándonos",
 "body": "Por favor revise los siguientes elementos de búsqueda recientes"
 },
 "FR": {
 "subject": "Nous vous avons vu nous vérifier",
 "body": "Veuillez examiner les éléments de navigation récents suivants"
 }
}

This is how the JSON data is accessed within a message.

{$localized_content=$utils->getJson('http://p5.zdassets.com/hc/theme_assets/656597/200049057/localized_content.json')} 
  {$show_content = $localized_content[$display_lang]}
  {$show_content.subject} {$show_content.body}