Localized email notifications

Chris -

If you have an international user base, you likely want your email notifications to be in the recipient’s preferred language too. Previously, building email notifications that localize to your users’ language required more effort to set up. Email theme headers and subject lines don’t support conditional logic, which could leave you maintaining complex workarounds just to send emails in the right language.

That changes today. You can now automatically send the right message in the right language to every recipient. App custom fields can now be localized, making it straightforward to build multilingual email themes, including subject lines. 

How it works

On the Settings page of your TalkJS dashboard, you can specify app metadata for your TalkJS app, including custom fields. Metadata include the ability to define custom fields, which are available as app.custom.<CUSTOM_FIELD> in your email themes and notification header macros.

You can now define locale variants for any custom field in your app metadata, by appending a locale suffix to the field name. For example, if your platform default is English and you’d like to add French and traditional Chinese translations, you can add the following:

{
  "newMessagesText": "You have new messages",
  "newMessagesText:fr": "Vous avez de nouveaux messages",
  "newMessagesText:zh-TW": "你有新訊息"
}

With these locales specified, you can then reference the base field name as normal in your email theme, in the Themes section of your dashboard:

{{app.custom.newMessagesText}}

That's it. TalkJS now automatically picks the right value based on each recipient's locale when rendering an email.

How TalkJS resolves the right value

When rendering an email, TalkJS walks through a straightforward fallback chain to find the best match for each recipient:

  1. Recipient's full locale (such as zh-TW)
  2. Language code (such as zh)
  3. Your app's default locale
  4. Unlocalized fallback field

This means a traditional Chinese-speaking recipient sees "你有新訊息" in the subject line, while an English-speaking recipient sees "You have new messages". You only need to maintain a single email theme to cover both.

Regional locale variants are handled gracefully too. For a recipient with locale zh-TW, TalkJS first tries newMessagesText:zh-TW, then newMessagesText:zh, before falling back further. So you can define broad language defaults and override them for specific regions where needed.

Where this applies

Locale-aware resolution works anywhere app.custom.<field> is supported across TalkJS, including in the chat UI and other theme contexts. But it's most impactful in email theme headers and subject lines, where previously templating logic was unavailable.

If you're sending notifications to a multilingual user base, this is the most straightforward way to make sure every recipient gets a coherent, correctly localized email.

Get started with localized email themes.