Rendering of personalized email content populated via FreeMarker code is dependent on many elements, but two of the most ubiquitous are field types referenced and CRM language settings. As a global organization, we have customers using ClickDimensions in a myriad of languages. However, when it comes to FreeMarker, language translation can make it a little challenging, especially when users set their CRM language differently than the base language. This post explores some common misconceptions or confusions that may arise when using FreeMarker in an environment where the CRM base language and user languages may differ.

Please note that language settings are a native CRM function and not a ClickDimensions function.

You can see what your environment’s CRM base language is, as well as change your user interface language by going to Settings, located in the gear icon on the right-hand side of the top navigation menu bar, and clicking Options. The navigation shown below is from a Dynamics 365 environment.

Next, click on the Languages tab. The CRM base language is set upon configuration of the environment and cannot be changed. A CRM user’s user interface language options (languages to choose from) will depend on what language packs are installed. The screenshot below is from an environment where the base language is English and the user language is set to French.

When users of a CRM environment are going to be using it in different languages, potential exists for confusion to occur. For instance, when users are trying to test a ClickDimensions email send with personalized content via FreeMarker, the resulting language of the content may be unexpected — meaning, the users sending that email are expecting to see data in one language, but the received email has data in a different language. This sounds like a trick, but nothing is actually changing because it all boils down to what language the CRM is being viewed in and what type of field the data is being pulled from. You can think of a user language setting as a language facade, where it is just showing everything to a CRM user in their preferred language.

Text Fields

If your email FreeMarker is referencing a text field on the lead or contact record, the FreeMarker will pull in the field’s text value(s) exactly as it appears, regardless of the CRM base language or user language. This is because the text field value does not change depending on the language of the CRM. Regardless of what the CRM’s language is set to, the text value will be whatever was input into that field.

Let’s say you are a company headquartered in Paris with employees and customers in France and the United States. Your CRM’s base language is in French and your users in the U.S. have their user languages set to English. Therefore, the users in Paris will see their CRM environment and all the data in French, while the users in the U.S. will see their CRM environment and data in English instead. The language of the data within the environment does not actually change.

Your company uses the native CRM text field of Salutation to insert salutations dynamically into emails to their recipients (using FreeMarker of course), like Mr. and Ms. in English or M. and Mme. in French. Because your company is detailed, your salutation field values are intentionally inserted to be congruent with the language of the customer. So, if a French user looks at a contact record of a U.S. customer, the salutation value will be in English while the field’s display name will be in French, along with the rest of the record. Then, if a U.S. user were to look at that same customer’s record, they will see the record appear in English, with the salutation value in English as well. In the comparison screenshot below you can see what the record and salutation field look like when the CRM is viewed in English versus French. You will notice that while the word “Salutation” gets translated from English to French, the value of the text field, “Ms.,” stays in English.

When the French user wants to send an email to a contact like Emily’s above, using FreeMarker for the Salutation field ( ${[0]!””} ), they can rest easy knowing that the value they see in the contact’s record will be the value populated as the email’s salutation. Because no matter what language they are viewing CRM in, that text field’s value is the true value. The email received by Emily will have the Ms. English value as the salutation.

Option Fields: Option Sets

If your email FreeMarker is referencing a type of options field on the lead or contact record, the behavior can be a little confusing regarding the value that is expected to populate in a ClickDimensions email. Factors like whether the CRM field is a default or custom field and if the CRM is being viewed in the base language or a different user language, is what can make it confusing. Out of the box, default fields are in the base language. Natively, the values in default option fields like Option Sets will translate when the user language is set to a different language than the base language, but custom option fields will not translate. CRM administrators can import translations for items like custom fields, but out-of-the-box, this is what to expect: For default CRM fields (like Status Reason), when you have a CRM with users setting their user language different from the base language, the value will translate when the user language changes. Again, custom fields will not. In the screenshot below, you’ll see an environment in the languages of English and French, where the contact record has default and custom fields.

As an example, imagine a company (for context, everything is in English) that has three different service package levels – Gold, Silver and Platinum. In this case, they have a custom option set field called Service Level that has been set on each customer’s lead or contact record.

If we look at the custom option set field’s properties, you can see here that this field’s options each have their labels written in English. The Gold service package level option is currently selected.

The label is key here, as those are the field’s real/front facing values. When referencing an options type of field with FreeMarker in a ClickDimensions email send, the FreeMarker will pull in the label of that field’s selected option. Whatever appears in the field’s properties – label field, is what will populate into an email. So, with the custom option set Service Level field above being created in English, FreeMarker will pull any of the three English values, like the value of Gold, into the email as is, in English.

In the following paragraphs, I outline a few different base language scenarios to illustrate how the email content is expected to appear depending on the CRM user’s user language.

Non-English Base Language Scenario

Let’s go back to the scenario I mentioned earlier with French and U.S. users in a French base language environment, where the U.S. users have their user languages set to English. A user on your U.S. team wants to send out ClickDimensions emails that indicate to the customer their current service level, in the language of that customer’s preference. The Service Level field in this company’s environment was set up by the French CRM admin who created it all it in French. The admin thought ahead and knew that U.S. users would be viewing the CRM in English, so he modified the CRM’s translations so this custom field could all be translated to English. So, when the U.S. user views a contact record, the Service Level field and its options will appear in English.

For the email, the U.S. user inserts FreeMarker to pull the service level field value for a U.S. Contact, whose level they see as Silver. Before sending the email to the contact, they wanted to test everything out by sending an email to themselves first and it’s good that they did. The populated FreeMarker value in the received email was the French word “Argent.” What the user forgot was that they have their user language set to English and are not viewing CRM in its French base language. So, when they saw the customer’s level as Silver in the contact record, they were expecting that to populate in the email.

In the Takeaways section later in this blog post, I will illustrate how you can fix or work around this situation.

English Base Language Scenario

For this next scenario, let’s imagine we have a company with U.S. users and French users, but because the company is headquartered in the U.S., the base language for the CRM is in English. However, the CRM admin is still in France. So, when the admin is configuring custom fields, such as our Service Level field in the prior example, the base language is in English but the field values themselves are in French. As you can see in the screenshot below, which is taken from an environment with a base language of English, we have a custom option set field with our service package levels.

When testing, the FreeMarker will pull the French values here into the final email because that’s what was input into the field properties, regardless of base or user language.

Remember, for default option set fields, those will translate when viewed in the user language. So, for any fields that translate in the user language, users might not always know if the field is currently translated into their language or not. For custom fields, it can be equally hard to tell if the values were set up in French or if the values are actually in English, if the admin has configured those to translate. You can always ask your CRM admin to look at the field’s properties to know what language the values are in or you can switch the user language back to be the same as the base language and look at the field’s values. Again, a great way to tell in these situations is to process the ClickDimensions email send as a send to yourself and see what the final result is.

Option Fields: Two Options

Two option fields work the same way as option sets. FreeMarker will pull the field’s label in the language that the field options were either built in (custom fields) or came in out of the box (default fields). So, if the CRM’s base language is in French, and the CRM admin built the values in French, then the values pulled by the FreeMarker will be in French. Additionally, labels can be customized. Below are the properties for a default two option CRM field, Do Not Allow Bulk Email. There are three types of option fields—option sets, two options and checkboxes—and they all align with this behavior.

By clicking Edit, you can see the label of the field and you are able to change it if you wish.

Takeaways or Additional Options for Populating Desired Language Content

If your company inserts text values that are already in the specific customer’s preferred language, then a text field is the easiest way to ensure your FreeMarker pulls in text in the language you want. Whatever is put in the text field is the value that will be in the final email. In this method, what you see is what you get, because no matter what language the CRM is being viewed in, the field value will appear the same.

You could use conditional statements to render the desired
information. For example, you could add FreeMarker that looks to see if a custom field has been configured for your contacts and leads that indicates that individual’s language preference. So, if language = French
and the service level = Silver and have it
to display “Argent” for those individuals, and language = English and service level = Silver and force it to display “Silver” for those individuals (or whatever the value of the picklist field may be). This article and this blog post both go into detail on conditional FreeMarker statements.

Additionally, your CRM admin could create separate option set fields for English and French values, but it is important to remember customizations can only be done in the base language. So, in our imaginary scenario with the French CRM admin setting up the Service Level field in all French, they would need to create an additional Service Level field for English values. So, U.S. users could then reference it via FreeMarker in ClickDimensions email sends for U.S. customers.

Lastly, we always recommend segmenting your emails when all else fails. Divide your marketing list into service level and/or by language to ensure the correct emails go to the correct recipients.

Happy Marketing!