If you communicate with a global audience, formatting dates in a way that’s appropriate for the recipient’s language and location can be a big challenge. Different locales order the elements of the date differently, use different punctuation, have different conventions for capitalization, and so on.

Tackling this problem recently for a Marketo client, I knew I could use Velocity (email scripting) to switch the date format dynamically, but I didn’t realize how easy it could be. If you can supply a date field and the person’s locale, Velocity can output all the different date formats like magic.

What Is a Locale?

Locale is a concept used in programming to enable language and location-specific formatting, such as date and time conventions, monetary formatting, etc. They’re described using standardized shortcodes*, which typically specify a language or a language/country combination.

Here are some example locales:

  • de – German
  • de_AT – German (Austria)
  • en_GB – English (United Kingdom)
  • en_US – English (United States)
  • fr – French
  • fr_CA – French (Canada)

The locales supported by a programming language may vary, but about 150 locales are known to be supported in Marketo’s implementation of Velocity.

How Velocity Works

  1. Create a velocity token with a general calendar configuration.
  2. Assign locales.
  3. Create a velocity token for each date field you want to localize.

Create a Velocity Token with Calendar Variables

To work with dates in Velocity, set several global variables in a universal token, which can then be referenced as needed. This prevents repetition and makes the system easier to maintain.

Full credit here goes to the Veloci-Master, Sanford Whiteman, as I’ve adopted a number of his recommendations on working with dates as well as annotation conventions. (He also graciously peer-reviewed this post.)

Create a new email script token at the highest folder level of the Marketing Activities tree that will encompass the program you want to use it in.

Name: {{my.universal-velocity-calendar-config}}

Value:

## @version v1 YYYY-MM-DD
## @name {{my.universal-velocity-calendar-config}}
## @author [your name]
## @requires
##    [none]
## @exports
##    [none]
## Description: Sets a series of default variables to enable use of calendar objects.

#set( $defaultTimeZone = $date.getTimeZone().getTimeZone(“America/New_York”) )
#set( $defaultLocale = $date.getLocale() )
#set( $calNow = $date.getCalendar() )
#set( $ret = $calNow.setTimeZone($defaultTimeZone) )
#set( $calConst = $field.in($calNow) )
#set( $ISO8601DateOnly = “yyyy-MM-dd” )
#set( $ISO8601DateTime = “yyyy-MM-dd’T’HH:mm:ss” )
#set( $ISO8601DateTimeWithSpace = “yyyy-MM-dd HH:mm:ss” )
#set( $ISO8601DateTimeWithMillisUTC = “yyyy-MM-dd’T’HH:mm:ss.SSSZ” )

Editing Script Token in Marketo

Assign Locales

As mentioned above, locales are standardized shortcodes specifying a language or language/country combination.

The way you assign locales to your Marketo person records can vary based on your instance. Your ability to do this accurately will depend on the quality of your system’s data (most likely data regarding a person’s country and language preference).

Here are a few possible ways to assign the locale:

  • Use a data management program with smart campaigns to populate a field on the person record.
  • Create mapping logic within a universal velocity token, mapping the values in the relevant fields to locales, and then assigning a locale variable.
  • Create a segmentation to assign the locale.

I prefer using segmentation, as it makes it easier for less technical users to view and update the locale logic without touching code.

Creating a Locale Segmentation

First, identify the locales you wish to support and the combination of fields that will define those locales. You can use a worksheet like this one to plan it out.

Creating a Locale Segmentation in Marketo

Important! The segments should ideally be named exactly the same as the locale shortcode.

This allows you to use the segment value as the locale with no further modification. Otherwise, you’ll need extra code to map the value in Velocity to the correct shortcode value.

You should also consider the order of the segmentations and the filter logic carefully.

  • More specific segments should come first and be more restrictive in their filters. For example, the fr_CA (French Canadian) segment comes before the fr (French) segment and is restricted only to people who have BOTH French as their preferred language and Canada as their country.
  • Also, ensure that any languages that span multiple countries have a “catch-all,” unrestricted by country, that will select people with that language but no country information. In the worksheet linked above, the fr (French) segment comes after any other french locales. It does not include a country filter to ensure that people with that language but no country information are bucketed correctly.

Create a Velocity Token to Assign the Locale

Once you’ve created your segmentation, it’s a straightforward matter to assign the locale in Velocity based on the segment name.

Create a new email script token at the highest folder level of the Marketing Activities tree that will encompass the program you want to use it in. This will be a universal token you can reference wherever you work with dates.

Name: {{my.universal-velocity-set-locale}}

Value:

## @version v1 YYYY-MM-DD
## @name {{my.universal-velocity-set-locale}}
## @author [Your Name]
## @requires
##    {{my.universal-velocity-calendar-config}}
## @exports
##    Lead.Segmentation_Locale_####
## Description: Set display locale based on the locale segmentation. If the person is in the default segment, use the system locale. DO NOT CHANGE.

#if ( !$lead.Segmentation_Locale_####.equals(“Default”))
#set( $displayLocale = $convert.toLocale($lead.Segmentation_Locale_####) )
#else
#set( $displayLocale = $defaultLocale)
#end

Make sure to replace the highlighted parts with the name of the segmentation in your instance and check off the export tree segmentation.

Check off export tree segmentation in Marketo

Create a Velocity Token to Output Your Localized Date Field

As a final step, you need a token to output the date field based on the person’s locale.

All Marketo fields are imported into Velocity as strings (text), so the code will first take the date field you specify and convert it into a “live” calendar object. This means Velocity will interpret the date correctly and perform date operations with it (for example, identify what date of the week it is or convert it into various formats).

Create a new email script token at the highest folder level of the Marketing Activities tree that will encompass the program you want to use it in. It is usually wise to make the date fields universal, so users don’t need to recreate them each time they’re needed.

Name: {{my.universal-velocity-loc-name of field-date format}}

Value:

## @version v1 YYYY-MM-DD]
## @name {{my.universal-velocity-loc-name of field-date format}}
## @author [Your Name]
## @requires
##    {{my.universal-velocity-calendar-config}}
##    {{my.universal-velocity-set-locale}}
## @exports
##    Lead.display name of field in export tree
## Description: Displays localized short/medium/long version of name of field.

## Convert name of field field to a live calendar date. First check if it is empty.

#if ( !$lead.field name.isEmpty() )
#set( $dateVariableName = $convert.toCalendar(
$convert.parseDate(
$lead.field name,
$ISO8601DateOnly,
$defaultLocale,
$defaultTimeZone
)
) )
#end

## Print the date using the correct format for the person’s locale. First check if it is empty or NULL.

#if ( $dateVariableName.isEmpty() || !$dateVariableName )
#set ($output = ‘Not Available’)
#else
#set($output = ${date.format(‘long_date’, $dateVariableName, $displayLocale, $defaultTimeZone)})
#end
$output

Make sure to update the highlighted parts based on the field you are trying to localize and check off the field you are trying to localize in the export tree.

Check off the field localized in Marketo

In this example, we are using the extended version of the date. You can change this to other formats easily. Different format options are illustrated in this date format document.

Using Your Token in Marketo

Put the token in a Marketo email, and the date will be localized automatically as the email is compiled.

The text before the date has been rendered in different languages using standard Dynamic Content, based on the same locale segmentation in the screenshots below.

Default (US English):

Marketo email - the date in English

British English:

Marketo email - the British date

Spanish:

Marketo email - the date in Spanish

German:

Marketo email - the date in German

Danish:

Marketo email - the date in Danish

Icelandic:

Marketo email - the date in Icelandic

*Note:   These shortcodes are extremely similar to *BCP 47 language tags* that you might see in other contexts like web pages, except BCP 47 uses a hyphen (-) while Velocity uses an underscore(_) between parts.

Additional Marketo email tips:

How to Use Emojis in Your Marketo Emails

Improving Your Email Performance Checklist

 

Need help eliminating Marketo infrastructure uncertainties, safeguarding against campaign errors, improving marketing performance, or executing high-volume campaigns? Our team of Marketo consultants can help— contact us! 

 

Contents Show