Feature: Template-level i18n — auto-select or translate email content based on contact language

[Swahjak]

Context

With the recent additions of console i18n (#176, v26.12) and automatic contact language sync via the notification center (#232, v27.2), contacts now reliably have a language field. However, as discussed in #153, there is still no built-in way to send the right email content based on that language — the gap between knowing a contact's language and acting on it remains.

Today the workaround is:

• Transactional: create a separate template per language, select the right template ID in your backend code
• Broadcasts: create a segment per language, send separate broadcasts with different templates

This works but is manual, error-prone, and doesn't scale well as the number of languages grows.

Prior art

Novu's Translations feature solves this with a translation keys approach: templates reference translatable strings via {{t.key}} variables, and translation files (JSON, one per locale) provide the actual content. The system selects the right translation at render time based on the subscriber's locale. This is worth looking at for inspiration, though the specifics below are adapted to Notifuse's architecture (Liquid, MJML, contact.language).

Proposal

Two possible approaches (not mutually exclusive):

Option A: Translation keys with a string catalog

Templates reference translatable strings via a dedicated syntax (e.g. a Liquid t object or filter), and translations are managed as key-value pairs per locale.

Template authoring — the email builder uses translation keys instead of hardcoded text:

{{ t.welcome.subject }}
{{ t.welcome.greeting }}, {{ contact.first_name }}!
{{ t.welcome.body }}

Translation files — JSON (or similar) per locale, scoped to the template or workspace:

// en.json
{
  "welcome": {
    "subject": "Welcome!",
    "greeting": "Hello",
    "body": "Thanks for signing up."
  }
}

// fr.json
{
  "welcome": {
    "subject": "Bienvenue !",
    "greeting": "Bonjour",
    "body": "Merci de vous être inscrit."
  }
}

Editor integration ideas:

• A translations panel in the template editor to manage keys and their per-locale values
• Autocomplete when typing {{ t. in text blocks
• A locale preview switcher to preview the rendered template in each language
• Marking translations as "outdated" when the default locale value changes

Import/export — bulk upload/download translation files (JSON) per template or workspace, similar to how template import/export already works.

Option B: Template variants

A template gets linked language variants under a single identifier. When the transactional API (or broadcast engine) renders a template, it resolves the variant matching contact.language.

This is simpler conceptually (each variant is a full template in the visual editor) but means maintaining N copies of the layout/structure, not just the text.

Language resolution & fallback

Whichever approach is chosen, a sensible fallback chain is important:

1. Exact match on contact.language (e.g. pt-BR)
2. Base language match (e.g. pt)
3. Template default language (e.g. en)

If no translation exists at all, render the default language rather than failing or sending blank content.

API surface

The transactional API shouldn't need to change — language selection should be automatic based on contact.language:

{
  "template_id": "welcome_email",
  "contact": { "email": "user@example.com", "language": "fr" }
}

The system looks up the fr translation/variant of welcome_email and falls back to the default if none exists. No routing logic needed on the caller's side.

Use cases

• Transactional emails (primary): password resets, order confirmations, welcome emails — content should match the user's language without the sender maintaining routing logic
• Broadcasts: send a single campaign that automatically delivers the right language variant per recipient, instead of creating N broadcasts × N segments

Current state

Piece	Status
contact.language field	Exists, synced via notification center (v27.2)
Console i18n (admin UI)	Done (v26.12)
Template-level i18n	Missing
Auto-routing by language	Missing

[jolic]

I would prefer "Option A" as it's simple to translate a simple json and we're done.

I asked a similar question here (at the bottom):
#267

It would be nice to clarify how a POST to trigger a transasctional email should be made that the template engine knows how to handle that? I mean also custom keys like {..."customertype": "vip"....}.
Can the template access a custom json key?

According to https://docs.notifuse.com/features/templates#available-data-structure the template has access to:

{
  "contact": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "list": {
    "id": "newsletter",
    "name": "Newsletter"
  },
  "unsubscribe_url": "https://your_notifuse_endpoint.your_website.com/notification-center?action=unsubscribe&email=john.doe@example.com&lid=newsletter&lname=Newsletter&wid=workspace123&mid=msg_123&email_hmac=abc123",
  "confirm_subscription_url": "https://your_notifuse_endpoint.your_website.com/notification-center?action=confirm&email=john.doe@example.com&lid=newsletter&lname=Newsletter&wid=workspace123&mid=msg_123&email_hmac=abc123",
  "notification_center_url": "https://your_notifuse_endpoint.your_website.com/notification-center?email=john.doe@example.com&email_hmac=abc123&wid=workspace123"
}

but according to https://docs.notifuse.com/api-reference/send-a-transactional-notification there are a lot of more json keys which can be provided (see the example).

[pierre-b]

Hi everyone, i18n of templates is certainly a must-have advanced feature.

Now that the core product is ready (segments, contacts timeline, custom events, automations, blog....) we can focus on this kind of advanced features.

Having a JSON mapping of translations per template is not possible because email content is "rich" (span, div, color styles etc...) and we can't edit rich content in a JSON string.

Right now with liquid markup you can conditionally render different languages in a single template, but it becomes complex to manage with more than 3 languages (if else if else if else...).

So remains option B.

I'll meditate about the best implementation we could get... My thought is most businesses are small and only use a single language, so adding "language variants" should be optional and not clutter the template form too much.

EDIT: having language-based variants in a template does not exist in ActiveCampaign/Brevo/MailterLite/Mailchimp...

[jolic]

Having a JSON mapping of translations per template is not possible because email content is "rich" (span, div, color styles etc...) and we can't edit rich content in a JSON string.

Why not?

As I understood @Swahjak it could look like:

...
<div>
    {{ welcome.subject }}
</div>
...

and welcome.subject will be replaced with "Welcome!" or "Bienvenue !".
The logic of the template should read a "language" key of the contact.language setting which is set bay the API-POST.

pseudo
...
switch (contact.language) {
   case "FR-fr":
      ->load "FR-fr.json"
      break
   default:
      ->load "EN-en.json"
}

(language json see above)

Wouldn't that be an "easy" to implement solution?

[pierre-b]

It works as long as the strings are simple, but we need to handle rich MJML content like:
<p>Hello <strong>John</strong>, <a target="_blank" rel="noopener noreferrer nofollow" href="https://www.test.com">click here</a> to get <span style="color: rgb(214, 31, 105); background-color: rgb(253, 246, 178);"><strong>20% discount</strong></span>,</p>

So far the easiest approach, used by 90% of emailing platforms is:

{% if contact.language == "en" %}Welcome{% endif %}
{% if contact.language == "fr" %}Bonjour{% endif %}
...

[jolic]

Hmm...

If I understand your example:

<p>Hello <strong>John</strong>, 
<a target="_blank" rel="noopener noreferrer nofollow" href="https://www.test.com">click here</a>
 to get 
<span style="color: rgb(214, 31, 105); background-color: rgb(253, 246, 178);"><strong>20% discount</strong>
</span>,
</p>

wouldn't that be written as

<p>{{ common.hello }} <strong>{{ contact.first_name }}</strong>, 
<a target="_blank" rel="noopener noreferrer nofollow" href="{{ contact.link_to_click }}">{{ common.click_here }}</a>
 {{ common.to_get }} 
<span style="color: rgb(214, 31, 105); background-color: rgb(253, 246, 178);"><strong>{{ common.discount_20 }}</strong>
</span>,
</p>

?

Or does your rendered example look complete different in the editor?

[Swahjak]

I also wonder how "rich" the content would have to be. Most i18n solutions work in a very similar fashion when for example looking at react, blade, twig (I'm not that familiar with liquid). The examples from novu show them using variables in the translation (first translate, then resolve the variable). For html one could simply write the html to the translation string. You could go as far as having a function and passing placeholder as an argument, but i dont think I (in my humble experience) have seen solutions that allow for rich html.

Edit: some typos.

[jolic]

I like the way Novu is solving the i18n stuff like:

https://www.youtube.com/watch?v=v5H8Eyc0prY&t=46s

and

https://docs.novu.co/platform/workflow/translations

@pierre-b if you have time please have a look at this.
Maybe there is a possibility to implement a solution like that...

[Swahjak]

Implementation Draft — Feedback Welcome

Here's an initial draft of the template i18n implementation based on this issue. We went with Option A (translation keys with a string catalog) as a starting point. This is very much a first pass — there's plenty of room to iterate, simplify, or rethink parts of this. Feedback on the approach and details is very welcome.

Why Option A as a starting point?

As discussed in the thread, translation keys let you keep the rich HTML/MJML structure in the template while externalizing only the text strings. This avoids duplicating entire template layouts (Option B) and scales cleanly as languages are added. The approach mirrors how i18n works in frameworks like React, Twig, and Blade — and aligns with Novu's implementation that was referenced.

That said, the UX for managing translations, the editor integration, and the overall workflow could all be improved significantly. This is a foundation to build on, not a finished product.

How it works (current draft)

Templates reference translatable strings using a Liquid t filter:

{{ "welcome.heading" | t }}
{{ "welcome.greeting" | t: name: contact.first_name }}

Translations are stored as nested JSON per locale. The system resolves the best locale from contact.language with a fallback chain:

1. Exact match (e.g. pt-BR)
2. Base language match (e.g. pt)
3. Template default language
4. Workspace default language

Two-level translation storage

• Template translations — per-template, stored in a new translations JSONB column. These take priority.
• Workspace translations — shared across all templates in a workspace (new workspace_translations table). These serve as a fallback, useful for common strings like greetings, footer text, unsubscribe labels, etc.

At render time, workspace and template translations are merged (template wins on conflicts), so you get shared defaults with per-template overrides.

What's in the PRs

PR	Scope
#271	Full backend + frontend implementation: domain utilities, Liquid t filter, V28 migration, workspace translation CRUD (repository, service, HTTP), email/broadcast rendering integration, translations panel in template editor, workspace language settings
Notifuse/liquidgo#3	Upstream fix: evaluate and pass keyword args to Liquid filter functions (required for `{{ "key"
Notifuse/docs#7	Documentation: new Template Translations page, cross-references from existing pages, OpenAPI spec updates

No API changes needed for callers

As proposed in the issue, the transactional API doesn't change. Language selection is automatic based on contact.language — no routing logic needed on the caller's side:

{
  "template_id": "welcome_email",
  "contact": { "email": "user@example.com", "language": "fr" }
}

Same for broadcasts — a single campaign automatically delivers the right language per recipient.

Frontend UX (basic first pass)

• Translations panel in the template editor (3rd tab) with a flat key editor, per-locale columns, search, and JSON import/export
• Workspace language settings page to configure the default language and manage shared translations

Known areas for improvement

This is an initial proposal — things we know could be better or worth discussing:

• Editor integration: No autocomplete for {{ "key" | t }} yet, no visual indicators for untranslated keys in the MJML editor
• Translation workflow: No "outdated" marking when the default locale value changes (as suggested in the issue)
• Locale preview: No preview switcher to render the template in different languages from the editor
• Bulk management: Import/export exists but the UX could be more polished
• Validation: No warnings when a template uses t keys that don't have translations for all configured locales
• Subject line i18n: Template subject line translation support may need more thought

Would love feedback on the overall direction, the data model, and what should be prioritized for improvement.

[pierre-b]

The example I gave about the HTML is a typical content generated by the Tiptap editor in the mj-text blocks in the email editor. Read ending-tags: https://documentation.mjml.io/#ending-tags

Novu is a notification center where every message (=notification) is just a string reused again and again. Notifuse users mostly send newsletters where each campaign has unique & rich content (=a lot of HTML).

Therefore we can't use a translation dictionary to translate HTML.

So far I'm thinking to either:

1. document the use of Liquid tags to conditionally render content {% if contact.language == "en" %}english content here{% endif %}. It already works, it's simple & efficient...
2. add a new workspace-level setting "available languages" that would automatically add a template variant in the "template form" per language configured

With option 2, when you create a template your will customize the default language, and have the possibility to create optional variants per configured language. The translated variants will be stored in the same template row in the DB and selected at sending time according to the contact.language field value.

[jolic]

I know that this works

{% if contact.language == "en" %}english content here{% endif %}

but when you want to add 5 languages you need to change all templates to

{% if contact.language == "en" %}english content here{% endif %}
{% if contact.language == "de" %}german content here{% endif %}
{% if contact.language == "es" %}spanish content here{% endif %}
{% if contact.language == "cz" %}czech content here{% endif %}
{% if contact.language == "fr" %}french content here{% endif %}

That's a mess!

Not usable. Not intuitive. Not scalable. Error prone.