Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Documented editing email templates one language at a time
Damian Legawiec684f9cf96ff5
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yamlindex 5317b183c4..8dfb2c66da 100644--- a/docs/api-reference/admin.yaml+++ b/docs/api-reference/admin.yaml@@ -7415,6 +7415,7 @@ paths:default_subject: Order {{ order.number }} confirmeddefault_body: "<mj-section><mj-column><mj-text>Thanks for your order,{{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"+ published_language:default_changed: falsebase_subject:base_body:@@ -7588,6 +7589,7 @@ paths:</mj-section></mj-body></mjml>+ published_language:default_changed: falsebase_subject:base_body:@@ -7678,6 +7680,7 @@ paths:default_subject: Order {{ order.number }} confirmeddefault_body: "<mj-section><mj-column><mj-text>Thanks for your order,{{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"+ published_language:default_changed: truebase_subject: Reset {{ store.name }}base_body: "<mj-section><mj-column><mj-text>Default</mj-text></mj-column></mj-section>"@@ -7776,6 +7779,7 @@ paths:default_subject: Order {{ order.number }} confirmeddefault_body: "<mj-section><mj-column><mj-text>Thanks for your order,{{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"+ published_language:default_changed: falsebase_subject:base_body:@@ -7860,6 +7864,7 @@ paths:default_subject: Order {{ order.number }} confirmeddefault_body: "<mj-section><mj-column><mj-text>Thanks for your order,{{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"+ published_language:default_changed: falsebase_subject:base_body:@@ -7978,6 +7983,7 @@ paths:default_subject: Order {{ order.number }} confirmeddefault_body: "<mj-section><mj-column><mj-text>Thanks for your order,{{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"+ published_language:default_changed: falsebase_subject:base_body:@@ -8056,6 +8062,7 @@ paths:default_subject: Order {{ order.number }} confirmeddefault_body: "<mj-section><mj-column><mj-text>Thanks for your order,{{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"+ published_language: anydefault_changed: truebase_subject: Reset {{ store.name }}base_body: "<mj-section><mj-column><mj-text>Default</mj-text></mj-column></mj-section>"@@ -8636,6 +8643,7 @@ paths:default_subject: Order {{ order.number }} confirmeddefault_body: "<mj-section><mj-column><mj-text>Thanks for your order,{{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"+ published_language: anydefault_changed: truebase_subject: Reset {{ store.name }}base_body: "<mj-section><mj-column><mj-text>Default</mj-text></mj-column></mj-section>"@@ -52478,6 +52486,9 @@ components:nullable: truedefault_body:type: string+ published_language:+ type: string+ nullable: truedefault_changed:type: booleanbase_subject:@@ -52502,6 +52513,7 @@ components:- published_at- default_subject- default_body+ - published_language- default_changed- base_subject- base_bodydiff --git a/docs/plans/6.0-email-template-editor.md b/docs/plans/6.0-email-template-editor.mdindex e09586799a..6da81d9866 100644--- a/docs/plans/6.0-email-template-editor.md+++ b/docs/plans/6.0-email-template-editor.md@@ -27,6 +27,8 @@ Every transactional email Spree sends renders from a Liquid template written in- **A published template must render.** Publishing validates by rendering with sample data under strict variables: a Liquid syntax error, an unknown variable, an unknown filter or invalid MJML is refused with the line and message, so a merchant can never break an email that is already being sent. Drafts may be saved in any state, since they are work in progress. Production sends stay lenient (an unknown variable prints nothing), as today.- **One template serves every language, with optional per-language versions** (2026-09-30). A saved template applies to every language, using translation keys (`{{ 'key' | t }}`) or plain text; a merchant can add a version for one language when its copy must differ. The lookup tries the email's language first, then the every-language version, then the files.- **`locale` is never NULL:** the every-language version stores `locale = 'any'`, because a unique index treats NULLs as distinct and would let two every-language rows exist for one key.+ - **Superseded in part (2026-10-01): merchants edit one language at a time, in readable text.** Translation keys such as `{{ 'order_mailer.confirm_email.dear_customer' | t: name: order.customer_name }}` stay in Spree's own files, which is how they ship translated into every language, but a merchant can neither read them nor change the text behind them. When a merchant edits a template for a language, the editor writes those keys out as text in that language (`Dear {{ order.customer_name }},`), in the subject and the body, and the edit becomes that language's version. Languages nobody edited keep Spree's translated default. The editor no longer offers "All languages"; the API still accepts `any`, and a version for every language published earlier keeps applying to languages without their own. This matches how other platforms handle it: none shows translation keys to merchants, and each language is edited as its own copy.+ - **Accepted trade-off:** the same change in five languages is made five times.- **History is the live row plus an append-only revisions table** (2026-09-30). `spree_email_templates` holds what is published, so the lookup on every send is one indexed read; `spree_email_template_revisions` records each publish. Rejected: one versions table with a current flag, which makes every send query the latest version and needs the flag kept consistent under concurrent publishes.- **Reverting keeps the row, marked reverted, so history survives** (2026-10-01). A published template has a `status` (`published` or `reverted`, declared with `has_status`); reverting to the default sets it to `reverted` and deletes the draft. The lookup reads only `published` rows, and publishing again later reuses the same row, so its revisions stay reachable. Rejected: deleting the row, which made the email's history unreachable from its screen.- **Drafts carry a version number and who saved them last** (2026-10-01). `lock_version` refuses a save made from a stale copy (409), and `updated_by` lets the editor say "Last saved by Ann, 5 minutes ago" and name who changed the draft in that refusal. One shared draft per store, email and language stays; two admins editing at once get a clear conflict instead of silently overwriting each other.diff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex 694d882a17..2373b3883c 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -99,6 +99,16 @@ Rejected:**Plans amended:** `6.0-tax-provider.md` (contract, Internal refund limit, "Post-sale tax", lifecycle integration points, Phase 6 follow-ups, Constraints on Current Work), `6.0-returns-exchanges-claims.md` (key decisions, ReturnLineItem, ExchangeLineItem and ClaimLineItem notes, refunding, exchange workflow, Constraints on Current Work, resolved question 7).+## 2026-10-01: Merchants edit email templates one language at a time, in readable text++**Context:** Spree's email templates print their text through translation keys (`{{ 'order_mailer.payment_link_email.message' | t: store_name: store.name }}`), so one file serves every language. In the dashboard editor a merchant cannot read those keys, and cannot change the text behind them. Other platforms with an email editor show merchants plain text and treat each language as its own copy.++**Decision:** Spree's files keep their translation keys. When a merchant edits a template for a language, the editor writes the keys out as text in that language, in the subject and the body, with each value as the variable the template passed (`Dear {{ order.customer_name }},`); the edit is that language's version. A key that cannot be written out exactly (a plural form, a missing translation) is left as it was. The editor no longer offers "All languages"; the API keeps accepting `any`, and a version for every language published earlier still applies to languages without their own, which the editor says.++**Consequences:** Languages nobody edited keep Spree's translated default, so an English edit never reaches French customers in English. The same change in several languages is made in each. Supersedes the "one template for every language" part of the 2026-09-30 entry for the dashboard.++**Plans amended:** `6.0-email-template-editor.md`.+## 2026-10-01: Building the email editor settled its API shape, branding and sample data**Context:** Implementing `6.0-email-template-editor.md` met details the design left loose: how the API names a template and its language, how the editor shows what an upgrade changed in a default, where branding is edited, what a new store previews, and whether the generated email types get Zod schemas.diff --git a/docs/user/settings/emails.mdx b/docs/user/settings/emails.mdxindex 0b7a9b65a5..6ca79c2490 100644--- a/docs/user/settings/emails.mdx+++ b/docs/user/settings/emails.mdx@@ -79,7 +79,7 @@ Click **Send test email** to receive the email at your own address before publis### Languages-A template applies to every language your store sells in. To word one language differently, choose it in the language switcher and edit that version; the other languages keep using the shared one.+Each language is edited separately. Choose a language in the switcher, and the template opens in that language's words, ready to change. Customers in languages you have not edited keep receiving Spree's own wording in their language, so an English edit never reaches your French customers in English. To make the same change in several languages, edit each one.### History and reverting