How Multilingual Templates Work
Opterius Commerce stores email templates per event and per locale. When an email is triggered, the system checks the client's locale setting and looks for a matching template. If a template exists for that locale, it is used. If not, the system falls back to the English (en) template.
This means you can run a fully bilingual or multilingual support operation without any code changes — just add templates for the locales you need.
Template Storage
Templates are stored in the email_templates database table. Each row represents one template and includes:
| Column | Description |
|---|---|
event |
The event identifier (e.g., invoice_paid). |
locale |
The locale code (e.g., en, fr, es, de). |
subject |
Subject line for this locale. |
body_html |
HTML body for this locale. |
body_plain |
Plain text body for this locale. |
The combination of event + locale must be unique.
Adding a Template for a New Language
- Go to Admin → Settings → Email Templates.
- Open any existing template for the event you want to translate.
- In the Language dropdown at the top of the editor, select the target locale (e.g.,
frfor French). - If no template exists for that locale yet, the editor pre-fills with the
encontent as a starting point. - Translate the subject and body.
- Click Save Template.
Repeat for each event you want to localise.
[!TIP] Start with the highest-volume events:
invoice_created,invoice_paid, andticket_reply. Clients see these most often.
Fallback Behaviour
If a client's locale is fr but no French template exists for the triggered event, the system automatically uses the en template instead.
Fallback chain: client locale → en
There is no multi-step fallback (e.g., fr-CA → fr → en). Only the exact locale match and the en baseline are checked. For regional variants, either create a template for the exact locale code (e.g., fr-CA) or ensure the en fallback is acceptable.
[!IMPORTANT] The
entemplate must always exist for every event. It is the universal fallback. Never delete theentemplate for any event.
Setting a Client's Locale
A client's locale is stored on their account and determines which template they receive. Locale can be set:
- By the client from their Profile → Language setting in the client portal.
- By an admin from Admin → Clients → [Client] → Edit → Language.
If no locale is set on a client account, en is used.
Supported Locales
The locales available in the language dropdown match the locales configured in config/app.php under available_locales. Out of the box, Commerce ships with:
| Code | Language |
|---|---|
en |
English |
fr |
French |
es |
Spanish |
de |
German |
pt |
Portuguese |
nl |
Dutch |
ar |
Arabic |
ja |
Japanese |
To add a locale not in this list, a developer must add it to config/app.php and add the corresponding language file in lang/. After that, it becomes available in the admin template editor dropdown.
[!TIP] For right-to-left languages (Arabic, Hebrew), ensure your HTML email template includes
dir="rtl"on the body element to display correctly in email clients.
Checking Which Templates Are Translated
From the Admin → Settings → Email Templates list, filter by locale using the locale selector at the top. Missing locales for an event indicate that the en fallback will be used for clients with that locale.