Email Template Localization at Send Time
Localization happens when an email is sent, not when it is authored. Two independent mechanisms combine: the right-language subject and body are selected, and then culture-sensitive tokens inside them are rendered in the recipient's culture.
Understanding both matters, because they can disagree: a recipient can receive a correctly translated body whose custom labels are still in the source language.
Mechanism 1 - Selecting the Language Version
The platform resolves the recipient's language to a subject and body in three steps:
- Exact match on the language code, case-insensitively.
fr matches FR. - Primary-subtag fallback. The region is stripped:
pt-BR falls back to pt, es-MX to es. This is one level only - there is no cross-region fallback such as pt-BR to pt-PT. - Source. The parent template's own
Subject and Body.
No recipient language, an empty language, or a template with no translations all resolve to the source. A missing translation is never an error.
Where the recipient's language comes from
The recipient's culture is resolved from the user record, falling back in order:
- The user's own language preference.
- The organization's default language.
- The current UI culture of the executing request.
Selection does not mutate the template. When a translation is chosen, its text is copied onto a throwaway copy of the template for that send, so a loop over many recipients never modifies the shared record.
Mechanism 2 - Rendering in the Recipient's Culture
Once the version is selected, the recipient's culture is pushed onto the executing thread for the duration of the merge. This makes the following render in the recipient's language rather than the sender's:
- Custom labels referenced by token.
- Picklist value labels.
- Date and number formatting.
Custom-label and picklist translation is gated. It requires the organization to have at least one active language configured. With no active languages, version selection still works but labels and picklist values stay in the master language. This is the usual cause of a "the body is French but the labels are English" report.
Send Order
The full sequence for one recipient:
- Resolve the recipient's culture from their user record.
- Select the language version - exact, then subtag, then source.
- Copy the resolved text onto a per-send shadow of the template.
- Push the recipient's culture onto the thread.
- Merge tokens in the subject, then the body.
- Strip any token that did not resolve.
- Apply portal branding, for HTML templates only.
- Hand the message to the mail transport.
If you extend this path, preserve that order. In particular, branding must come after the merge, and the culture must be in effect for the whole merge.
Unresolved Tokens Are Removed
After the merge, any residual {!...} token is stripped from the outgoing subject and body. A token that cannot be resolved is therefore delivered as nothing, not as a literal {!Contact.Firstname}. This is deliberate: it prevents field names and schema details leaking to recipients.
The practical consequence for developers is that a mistyped token fails silently at send time. There is no error, no log entry visible to the administrator, and no visual marker in the delivered email. The Preview action in the Setup UI is the only place unresolved tokens are reported, so validate there before shipping a template.
Note that this stripping applies to the email path only. Other consumers of the merge engine leave unresolved tokens in place.
Merge Failure Behavior
The merge engine has two modes for handling a token that throws. The email path deliberately uses the tolerant one: each token is evaluated independently, and a failing token is blanked while the rest of the message survives. An email is never emptied because one token failed.
Subjects are merged without HTML encoding. Bodies are encoded when the template type is HTML, except where the source field is rich text, which is passed through raw.
Branding
For HTML templates, branding tokens in the body are resolved to the recipient's portal theme when the email is sent - colors are not baked into the saved body. Branding is applied only when the recipient maps to exactly one active hub; with zero or several hubs, or an unknown portal, the email renders unbranded rather than guessing.
Performance
- Batch senders should preload translations. Resolving a language queries the translation rows per call and is not cached. For a multi-recipient send, load the variants for all templates once and pass them in, rather than resolving per recipient.
- Render once per culture group, not once per recipient. Recipients sharing a language share a rendered message.
- Resolve addresses in one query. The recipient resolver looks up all addresses in a single query to avoid an N+1 pattern.
Do not await inside a culture scope. The recipient's culture is set on the current thread. Awaiting inside that scope can leak the culture onto a pooled thread and localize an unrelated request. Keep the merge synchronous.
Extending Localization Safely
- Change selection precedence in one place. The resolver is a single pure function; it is the only place the exact-then-subtag-then-source order is decided. Add coverage for all three paths.
- Adding a language needs no code. Activate it for the organization; the picker, validation and resolver all read the active-language set.
- Adding a template type is not a small change.
Type is a fixed two-value picklist that is immutable after create, and it drives the sanitize path, the AI prompt and the send-time encoding and branding branches. A third type touches authoring, validation and send. - New culture-sensitive tokens must read the current UI culture so the culture scope localizes them, and should honor the active-language gate where relevant.
See More
<< Managing Email Templates with the REST API | Merge Tokens and Functions Reference >>