Objectif Lune joins Upland Software.Learn more >

Back to all How-tos

Localizing templates using JSON

Original author: Evelyne Lachance

As for template translation, this How-To is relevant for OL Connect versions 2018.2 and older. In newer versions, a translation feature is available! See this article to know more.

OL Connect already has an awesome way that helps you output into specific locales: in the Edit, Locale dialog. Here you can specify in which locale (which is all about formatting and language) any specific record fields will output. Then, in any Text script, you can use the Format column to specify a formatting option such as the date or time display.

But what about the template’s contents? If you have text in your template and require it to be localized in different languages, here’s a method that will help you out.

Step 1: Preparing the localization data

There are of course many different formats in which localization data can be formatted. However, because Connect works with popular web technologies like JavaScript, the most effective data format to be used in the software is JSON.

JSON data is truly simple to work with, and only requires a very basic syntax to understand. It’s easier than XML, and that’s a pretty good feat!

Here’s a very simple example of a JSON structure containing a company name along with 3 employees under that company:

{"company_name": "OL Sporting Goods",
 "company_web": "http://www.olsportinggoods.com",
 "employees": [
     {"first_name": "John", "last_name": "Jobs", "ext": 625},
     {"first_name": "Anna", "last_name": "Wellington", "ext": 315},
     {"first_name": "Steve", "last_name": "Doe", "ext": 644},

Now, the keen eyes in the audience may have realized one or more of the following things:

  • Yes, absolutely, this looks a lot like a Record with a detail table.
  • The “ext” property is numerical, and does not require double-quotes. JSON supports integers and a few other data types (but not many, it is meant to be a simple format). More details here.
  • Only 5 characters are really used, other than the variable names and the values:
    • {} wraps around a list of key/value pairs.
    • [] wraps around a list, creating a table (what we call “detail tables” or “nested tables”).
    • "" goes around any key (property) or string value.
    • : is the delimiter between a key and its value
    • , goes between each key/value pair, and between each table.

So what does this mean for a localized template? Well, consider the following 2 JSON structures:

    "lineamount": "Amount",
    "linedesc": "Description",
    "welcome": "Welcome <strong>@CustomerName@</strong>!"


    "lineamount": "Montant",
    "linedesc": "Description",
    "welcome": "Bienvenue <strong>@CustomerName@</strong>!"

Obviously, these are the English and French versions of the same strings, which we can use within a template as sources for localization. To do this, simply add new JSON Snippets by right-clicking in the Snippets resource folder, and select New JSON Snippet. The first one should be named en-CA.json, the second fr-CA.json. And we’re finally ready to move on to the next step!

Step 2: Adding the classes and IDs to localized content

In order to properly run the script that localizes the contents, each separate element that contains text that requires translation should have the localized class, and an ID that relates to a key within the JSON snippet, for example linedesc. For example:

<span id="amount" class="localized">Amount</span>
<span id="linedesc" class="localized">LineDesc</span>
<span id="welcome" class="localized">Welcome</span>

As long as the appropriate class and ID have been applied, the next part should be done in a jiffy. Note that in the example above we’re only using the <span> element, but any element can do (p, div, td, etc.)

Step 3: Initiating the localization script

The last part is to create a simple script that will apply the proper localized string to each of the elements. And when I say simple, I really mean it. Create a new script with the selector as .localized, which is the common class we added to each element.

var translations = loadjson('Snippets/' + record.fields.LanguageCode + '.json');

results.each(function() {
    if (this.attr('id') in translations) {

Here is a quick explanation of how this script works:

  • It reads the “LanguageCode” field in the record, which we assume contains the language tag such as en-CA or fr-CA.
  • It loads the appropriate JSON file from the Snippets folder, for example Snippets/en-CA.json and keeps it in memory as the translation object.
  • For each of the elements found by the script’s selector, it does the following:
    • Check if the ID corresponds to a localized string in the JSON
    • Replace the contents of the element with the localized string.

What about your data?

If you’re wondering if there’s any way to localize the data coming in from your source, here’s the deal: you shouldn’t even think about it. The data coming from your own system should already be localized, and if it’s not, Connect is not going to give you an easy way to fix this. Essentially, a Designer template should never contain data, only the design elements (which includes translated strings in the document itself). While you could theoretically save JSON strings on your system or in your template and call them dynamically (such as the description for each of your products), these things can change and having them separate from the rest of your data can be a real pain.

Leave a Reply

Your email address will not be published. Required fields are marked *