Mailings now aware of the recipients' language

2016-11-18 12:56
Written by
samuelsov - member of the CiviCRM community - view blog guidelines

CiviCRM support for multiple languages and locales has been present for many years already. Features like multilingual donation forms, for instance, are now both common and easy to use. Some usages, however, have remained a source of minor headaches. With the release of CiviCRM 4.7.13, a small step has been made in order to fix a major annoyance that affected multilingual emails.

(billet disponible en français)

The annoyance

Until now, there was no effective way for CiviCRM to determine the target language of mail merge tokens when mass emailing. Consequently, many emails would end up with :

  • badly translated tokens (ex: prefixes such as « Mrs » appeared in English instead of being translated to « Mme » when sending out content written in French)
  • links that didn't point to content in the right language (ex: ubsubscribe pages could be shown in an unfamiliar language)

Without a reliable method to decide on the target language of a message, token substitutions would be applied based on the site's default language. This limitation has now been fixed. Organizations that must reach out to a linguistically diverse network can do so with the certainty of reaching out to their constituents in a language they understand.

The solution

Specifying the language of each mailing

a) Set a language for each bulk email

When sending out a mass email, it is now required to specify the language of that message.

Envoi massif avec choix de langue pour champs de fusion


This language is also exposed in the mailing search form to help track messages based on language.

Recherche d'envoi avec filtre de langue


Since each mailing is now targeted based on a unique language, every message should be correctly localized.

b) Choose a language strategy for scheduled reminders

The language of scheduled reminders can be set according to either one of those three options:

  • Use any one of the available languages: when a message is written in a single language, token substitutions will be applied according to this language
  • Use the contact's preferred language: when a message includes conditional statements based on language, token substitutions will be performed according to the contact's communications preferences
  • Use system defaults: when a message doesn't contain any link or token or its content is linguistically neutral, this option remains valid
Rappel de message avec choix de langue pour champs de fusion


Grouping recipients by language

A small tip on grouping recipients

Whenever a multilingual email is sent out to various users, it is recommended to send out multiple messages, each written in their target's language. In order to do this, it may be essential to filter each list of recipients according to their preferred language. In other words, there must exist one smart group per language.

Since language is rarely the only criterion used for grouping recipients, one of the following tactics may be required in order to target each group in their proper languages:

  • multiply each smart group by the number of available languages, so that each group exists for each language
  • add a smart group for each supported language and exclude the languages that do not apply for each mailing (ex: when sending an English message to the participants of an event from a trilingual website, we may substract those contacts whose preferred language is French or Spanish)

An ongoing improvement

In any case, these tactics remain a tedious and error prone process. In order to alleviate this situation, a new option has been introduced to filter recipients based on their preferred language. This new filter is therefore combined with the *restrict to group* option. At the moment of writing, however, this feature is only available for scheduled reminders.

Rappel de message avec filtre des destinataires par langue de préférence


We'd like to thank the National Democratic Institute (NDI) for their financial support, which helped us to acclerate the implementation those improvements.



Anonymous (not verified)
2019-02-15 - 03:17

Hi Samuelsov,

This looks great and I was really excited to use it. But after spending 40 hours on this, I have seen that it was in vain because it isn't working as expected.

I was expecting this feature to take the receiver's preferred language into consideration when sending the mail, and omit the those who didn't have that language. For example, if I have contact A who's preferred language is French and contact B who's preferred language is English, and I send a French e-mail to a mailing list with both contacts, that contact B would not receive the e-mail - but in our tests both contacts receive it.

Any idea why this is happening?

Was this the intended behaviour?

Hi longtrog,

Thanks for your feedback.

What you need to know :

  1. For schedule reminder, we have 2 different fields, one for contact filtering based on language (Recipients language) and one for tokens replacement (Communication language). This is probably what you would like for mass mailing.
  2. For mass mailing, it's different, the language is only used to specified in which language the tokens are generated. It is not a contact filter. The reason is that there are use cases where we want to send messages to people in a language that is not their primary language and that's why we assumed that the group filter was a better tool to filter the contacts as needed.

To do what you want, what we usually do is :

  • create smart groups for your different preferred language : e.g. Preferred language = French and Preferred language = English
  • when doing the mass mailing, include the groups we want to send the message to and exclude the language we don't want (e.g. Exclude group French for mass mailing in English)

As mentionned it's an ongoing improvement and we are open to update the behavior. The obvious way to do it is to add the Recipient language filter to the bulk mailing screen. Do you think it would resolve your problem ? Do you have something else in mind ?