The Trinity Beast — Multi-Lingual Communications

Table of Contents

• 1. Overview — Design Philosophy
• 2. Supported Languages
• 3. Static Website Translation (JSON i18n Engine)
• 4. Email Communication System
• 5. AWS Translate Integration
• 6. Support Ticket Translation Flow
• 7. Impact Map — Real-Time Caption Translation
• 8. Newsletter System — Multi-Lingual Delivery
• 9. Full Architecture Diagram
• 10. Translation Caching Strategy
• 11. Cost Analysis

List of Diagrams

• Diagram 5.1 — AWS Translate Integration Flow
• Diagram 9.1 — Full Multi-Lingual Communications Architecture

1. Overview — Design Philosophy

The Trinity Beast serves 12 languages across every touchpoint:

• Website UI — Static JSON translation files loaded by the i18n engine (v4). Every page, every label, every button.
• Email Communications — Support confirmations, reply notifications, and newsletter welcome emails all render in the recipient's preferred language.
• Support Tickets — Bi-directional translation via AWS Translate, live on every submission and reply. Customers write in their language, admin reads in English. Admin replies in English, customers receive in their language. Rhema (Bedrock) categorizes tickets and drafts responses alongside this — see section 6 for exactly how the two fit together.
• Impact Map — Pin captions translated on-the-fly via AWS Translate with ElastiCache caching. Legend, labels, and privacy notice all served from static i18n.
• Newsletter Broadcasts — Translated once per send via Bedrock, stored in Aurora, and read back at delivery time with zero AI calls per recipient. Only into languages actual subscribers use.
• Newsletter Opt-out Pages — Both LPO and CPMP opt-out pages fully translated.
• Document Library — Card titles, descriptions, badges, and navigation all multi-lingual, and every individual document — this one included — is fully translated into all 11 other languages by the custom Bedrock document translation engine and served at /docs/{lang}/.
• Session Reports — The one page type that is not pre-translated and stored, by design: session reports are generated and published continuously, far too often to run through the document translation pipeline. Each one instead carries a live Google Translate widget covering all 12 supported languages, so a report is readable in any of them immediately on publish rather than on the next translation batch.

Two live translation engines do different jobs here, and the distinction matters: AWS Translate does literal, synchronous language conversion for support tickets and map captions — short text, translated on the exact request that needs it. Bedrock handles everything that benefits from understanding rather than literal conversion — drafting Rhema's support replies (Qwen 3 235B), translating full newsletter HTML once per send rather than per recipient, and translating the entire document library (also Qwen 3 235B, via the sentinel-preprocessing engine described in the TBI Translation Engine document). Neither approach is used for the other's job, and nothing customer-facing is English-only — the one exception, session reports, is covered live rather than pre-translated, for the reason above.

2. Supported Languages

All 12 languages are supported by AWS Translate, ensuring both static and dynamic translation coverage.

3. Static Website Translation (JSON i18n Engine)

The website uses a custom i18n engine (v5) that loads language-specific JSON files and applies translations to DOM elements via data-i18n attributes. Translation data is served from Valkey via the API first, with S3 as fallback — enabling instant updates without a deploy.

Architecture

How It Works

• Page Load: i18n.js reads cpmp_site.lang from localStorage (JSON object). Falls back to legacy cpmp-lang flat key (auto-migrated on first visit), then browser language detection.
• Translation Source: Fetches GET /public/lang/{code} from the API (Valkey-backed) first. Falls back to lang/{code}.json from S3 if the API returns empty or fails.
• DOM Application: All elements with data-i18n="section.key" have their text content replaced. data-i18n-html for HTML content. data-i18n-placeholder for form placeholders.
• Language Switch: User clicks a flag in the dropdown. New JSON loaded, DOM re-applied, preference saved to cpmp_site.lang in localStorage.
• RTL Detection: If language is ar, ur, or pa, the dir="rtl" attribute is set and css/rtl.css activates mirrored layouts.
• Caching: JSON files cached in memory (window.cpmpI18n._cache) — no re-fetch on page navigation within the same session.

Key Coverage

4. Email Communication System

All outbound email from The Trinity Beast is sent via Amazon SES and rendered in the recipient's preferred language. Nothing is translated at send time — every string is pre-translated and cached, so no email send ever waits on an AI call.

Two stores serve this, split by who originates the mail. Stripe checkout receipts (subscription, donation, LRS, webhook, plan switch) are assembled by the receipt Lambda from pre-translated frames in Valkey and delivered asynchronously through SQS. Server-originated mail (support, refund, TBTS welcome, magic link, reactivation) is assembled by the LPO server from the centralized email:tpl:* template registry. Both are zero-Bedrock at send time, and both fall back gracefully when their cache is unavailable.

Correspondence Language Resolution

Every server-originated email needs to pick a language before it can render, and that language is deliberately not the same thing as the customer's api_lang — api_lang governs API response messages only, while correspondence (emails, newsletters, support replies) uses preferred_lang. The resolver (correspondenceLang) walks a short, explicit fallback chain rather than assuming a single always-populated column:

1. users.preferred_lang, when the caller already has it in hand for this account
2. newsletter_subscribers.preferred_lang, the most recent by subscribed_at, looked up by email — a customer may not have a users row at all (e.g. a donor with no API key) but still have a language on record from a newsletter signup
3. en — final fallback

Email Types

Receipt Email Architecture (Zero Bedrock)

All receipt emails (the first 6 types above) are assembled from pre-translated parts stored in Valkey. No AI translation at send time. The pipeline:

1. Receipt Lambda builds the complete localized email by reading email:frames (12 languages × 69 keys) from Valkey and combining frame labels with dynamic values (name, amount, API key, date).
2. SQS — the finished email is enqueued to trinity-beast-email-queue (~20 ms, durable).
3. Email-sender Lambda picks up the message (batch 6, 3s window) and delivers via SES.
4. Customer inbox — fully localized email arrives within 3–6 seconds of checkout.

Pre-Translated Data Sources

Language Preference Storage

Every user interaction stores the language preference:

• support_tickets.preferred_lang — set from the form submission's cpmp_site.lang (read from localStorage)
• newsletter_subscribers.preferred_lang — set at subscription time
• users.preferred_lang — set from Stripe checkout locale (passed via client_reference_id on checkout URL)

Centralized Email Templates (Valkey email:tpl:*)

Emails sent by the LPO server — as opposed to the receipt Lambda — draw their localized strings from a centralized, Valkey-backed template registry. This replaced a set of hardcoded Go switch statements that had to be recompiled and redeployed for every copy change. Now the copy lives in JSON on S3, syncs to Valkey, and the server reads it at send time.

The Registry — 6 Templates × 12 Languages = 72 Entries

Each template is one Valkey hash. The hash field is the language code; the value is a JSON object of string keys. Source files live in cpmp-redesign/email-templates/.

The Loader — internal/email/loader.go

A single shared EmailLoader is constructed once at server startup and hung on HandlerDeps. Every email builder receives it and resolves its strings through the same three-step chain:

1. In-memory cache — a sync.Map keyed by template:lang with a 5-minute TTL. Repeat sends in the same window never touch the network.
2. Valkey read — HGET email:tpl:{template} {lang}. On a cache miss for a non-English language, the loader automatically retries with en.
3. Hardcoded Go fallback — if Valkey is unreachable or the template is absent entirely, the original hardcoded string functions still ship in the binary and serve the email. The customer always receives their message.

Loader Integration Pattern

Every migrated builder follows an identical shape — try the loader, fall back to hardcoded, merge key by key. A missing individual key falls back independently, so a partially translated template still renders completely:

// Resolve strings with graceful degradation at every level
func getRefundStringsFromLoader(loader *email.Loader, lang string) refundEmailStrings {
    if loader == nil {
        return GetRefundEmailStrings(lang)          // no loader wired (tests)
    }
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
    defer cancel()

    tpl := loader.GetStrings(ctx, "refund", lang)
    if tpl == nil {
        return GetRefundEmailStrings(lang)          // Valkey miss or outage
    }

    fallback := GetRefundEmailStrings(lang)
    getOr := func(key, def string) string {         // per-key fallback
        if v, ok := tpl[key]; ok && v != "" {
            return v
        }
        return def
    }

    return refundEmailStrings{
        subjectFull:   getOr("subject_full", fallback.subjectFull),
        headingFull:   getOr("heading_full", fallback.headingFull),
        // ... 20 more keys
    }
}

Public builders accept the loader as a variadic trailing parameter, which keeps existing call sites and unit tests compiling unchanged while letting handlers pass h.EmailLoader:

func BuildTranslationRefundHTML(lang, docName string, /* ... */ loader ...*email.Loader) string
func BuildSubscriptionRefundHTML(lang, tier string, /* ... */ loader ...*email.Loader) string
func RefundSubject(lang string, isPartial bool, docName string, loader ...*email.Loader) string
func buildTBTSWelcomeEmailHTML(name, apiKey string, loader ...*email.Loader) string

Two Template Systems, Two Owners

The platform runs two distinct localization stores. They are not duplicates — they serve different processes with different constraints:

The receipt Lambda is a short-lived function outside the VPC that must assemble and enqueue an email in milliseconds, so it loads one blob and caches it for its container lifetime. The LPO server is long-running with many distinct email types, so per-template hashes let it fetch only what a given send needs.

Keeping the Three Stores in Sync

There is a subtlety here that cost us two separate defects, and it is worth understanding precisely. The frames a receipt email needs actually live in three places that must agree: the keys the Go code asks for at send time (each frame(lang, "...") call in the receipt Lambda), the email-frames.json data file that defines them, and the Valkey email:frames blob the Lambda actually reads. Nothing in the build enforces that these three stay aligned — email:frames is a hand-maintained blob, edited and pushed by a human, not generated from the code. When a new email type ships, its keys have to be added to the data file and pushed to Valkey as separate, easily-forgotten steps.

Both failure shapes happened. First, an email family was coded and referenced but its keys were never added to the data — so the customer saw the raw key name (lifetime_heading) instead of a heading. Then, after the data file and S3 were corrected, the entire family was still missing from Valkey for all 12 languages — the file update never landed in the store the Lambda reads — so every language's email silently fell back to the binary's hardcoded English. A configured, committed, deployed set of translations was simply absent from the one place that mattered, and nothing reported it. This is the same lesson the logging layer taught: the presence of a definition says nothing about whether the running system can see it.

The guard is a reconciliation audit that reads no rendered email and instead asks the only questions that matter — does every key the code uses exist in the data, and does every language/key pair in the data exist, identical, in live Valkey? It also checks that every language defines the full key set, that translated values preserve their {name} / {refund} placeholders, and that the binary's English safety net actually covers every key the code can request. It is part of the standard hygiene sweep:

# Reconcile Go code keys ↔ email-frames.json ↔ live Valkey email:frames
bash scripts/kcc.sh frames-check

# Runs automatically as one of the five audits in:
bash scripts/kcc.sh audit-all

Updating Copy

# 1. Edit the source JSON
vim cpmp-redesign/email-templates/refund.json

# 2. Push to S3 + Valkey (all templates, all 12 languages)
bash scripts/kcc.sh push-email-templates

# 3. Live within 5 minutes (loader cache TTL) — no redeploy

Email Template Translation (Newsletters)

Newsletter welcome emails use SES templated sending with field values loaded from the email_translations Aurora table. Each template has 6-11 translatable fields per language (heading, subject, body, button labels, unsubscribe text).

5. AWS Translate Integration

AWS Translate provides real-time neural machine translation for dynamic content that cannot be pre-translated in static JSON files. It handles exactly two things in this system, both literal short-text conversion on a live request: support ticket messages (section 6) and impact map pin captions (section 7). Newsletter broadcast translation is a separate engine entirely — Bedrock, translated once at send time and stored rather than called per request — covered in section 8, not here.

Integration Points

Technical Implementation

• SDK: github.com/aws/aws-sdk-go-v2/service/translate
• Authentication: ECS Task Role (ecsTaskRole) with translate:TranslateText permission
• Region: us-east-2 (same as all other services)
• Fallback: If translation fails, the original text is returned (graceful degradation)
• Text Limit: 2,000 characters per request (enforced server-side)

flowchart LR
    subgraph Customer["Customer (any language)"]
        C1[Submits ticket in Urdu]
        C2[Receives reply in Urdu]
    end

    subgraph Server["ECS Container"]
        S1[Support Handler]
        S2[translateText fn]
        S3[Reply Handler]
    end

    subgraph AWS["AWS Services"]
        T[Amazon Translate API]
        EC[ElastiCache
Translation Cache]
    end

    subgraph Admin["Admin (English)"]
        A1[Reads ticket in English]
        A2[Replies in English]
    end

    C1 -->|"POST /support/submit"| S1
    S1 -->|"ur → en"| S2
    S2 --> T
    S2 -->|"message_en"| A1
    A2 -->|"POST /support/reply"| S3
    S3 -->|"en → ur"| S2
    S2 -->|"message_translated"| C2

    style C1 fill:#10b981,stroke:#059669,color:#fff
    style C2 fill:#10b981,stroke:#059669,color:#fff
    style A1 fill:#FF9900,stroke:#cc7a00,color:#fff
    style A2 fill:#FF9900,stroke:#cc7a00,color:#fff
    style S1 fill:#1e293b,stroke:#334155,color:#e2e8f0
    style S2 fill:#635bff,stroke:#4b44cc,color:#fff
    style S3 fill:#1e293b,stroke:#334155,color:#e2e8f0
    style T fill:#60a5fa,stroke:#3b82f6,color:#fff
    style EC fill:#a855f7,stroke:#7c3aed,color:#fff
        

6. Support Ticket Translation Flow

Inbound (Customer → Admin)

1. Customer selects their language via the flag dropdown (stored in cpmp_site.lang in localStorage)
2. Support form renders in their language (static i18n)
3. Customer writes message using Quill rich text editor
4. Form submits with preferred_lang read from cpmp_site.lang
5. Server stores original message in support_tickets.message
6. If preferred_lang != "en": AWS Translate converts to English, stored in support_tickets.message_en
7. Admin views ticket in TBCC — sees English translation + original

Outbound (Admin → Customer)

1. Admin writes reply in English via TBCC Support Console — or Rhema (Bedrock, Qwen 3 235B) auto-drafts a reply already written directly in the customer's language, and posts it through the same reply endpoint
2. Server stores the reply text as submitted in support_replies.message
3. If preferred_lang != "en": AWS Translate converts en → preferred_lang, stored in support_replies.message_translated
4. Email notification sent with the translated reply body + translated chrome (heading, labels, buttons)
5. Customer receives email entirely in their language

Database Schema

7. Impact Map — Real-Time Caption Translation

The Impact Map translates pin captions on-the-fly when a user taps a pin in a non-English language.

Static Elements (i18n JSON)

• Privacy & Safety Notice modal (title, text, button)
• Legend panel (all 7 impact types, Show All, Media Filter, note)
• Detail panel labels (Date, Region)
• Impact type headings in the detail panel

Dynamic Elements (AWS Translate)

• Pin captions (e.g., "Family Freed - Ledger crossed out forever")
• Translated on first tap, cached in ElastiCache for 30 days
• Original English shown below the translation as context

Translation Endpoint

The endpoint checks ElastiCache first (key: translate:{lang}:{text_hash}). On cache miss, calls AWS Translate and caches the result for 30 days. On cache hit, returns immediately with no API call.

8. Newsletter System — Multi-Lingual Delivery

Welcome Emails

When a user subscribes to either newsletter (CPMP Mission or LPO), a welcome email is sent in their preferred language using SES templated sending.

• Template: SES email template with {{variable}} placeholders
• Translation Source: email_translations Aurora table (template_name + lang + field_name → field_value)
• Fallback: If requested language not found, falls back to English
• Fields: heading, subject, body, button labels, unsubscribe text

Newsletter Broadcasts — Pre-Translated via Bedrock, Not AWS Translate

Newsletter content is composed in the TBCC Newsletter Console using a Quill rich text editor. The admin writes in English. Translation is a separate, explicit admin action — POST /newsletter/{id}/translate — that runs once per send, not once per recipient, and stores its output rather than calling an AI model on delivery.

1. The English newsletter is saved as the lang='en' row in newsletter_translations.
2. The handler reads newsletter_subscribers for the distinct non-English preferred_lang values actually in use by opted-in subscribers of that newsletter type — it never translates into a language nobody has selected. If every subscriber is English, translation is skipped entirely and nothing is sent to Bedrock.
3. The request returns immediately (202 Accepted); translation runs in a background goroutine so the admin isn't blocked.
4. For each target language, the subject and HTML body are translated together in a single Bedrock call (qwen.qwen3-235b-a22b-2507-v1:0) — the same model used for Rhema and AutoOps threat analysis elsewhere in this platform. The prompt preserves every HTML tag, inline style, and bgcolor attribute exactly, and protects the same brand-term list as the document translation engine (The Trinity Beast, CPMP, exchange names, AWS service names, node names).
5. Each translated result is stored as its own row in newsletter_translations (auto_translated=true, reviewed=false).
6. At send time, NewsletterSendHandler loads every stored translation into memory once and picks each recipient's row by their preferred_lang, falling back to the English row if their language was never translated. Zero AI calls happen at send time — the same pre-translate-and-store pattern the rest of this document describes for email.

Opt-Out Pages

Both newsletter opt-out pages (newsletter-optout-lpo.html and newsletter-optout-cpmp.html) are fully multi-lingual via the static i18n engine. The user sees the unsubscribe confirmation in their selected language.

9. Full Architecture Diagram

Complete view of how language flows through every layer of The Trinity Beast communications system.

flowchart TD
    subgraph User["User Browser"]
        LS["localStorage
cpmp_site.lang (website)
cpmp_user.lang (dashboard)"]
        DD[Flag Dropdown
Language Selector]
        DD --> LS
    end

    subgraph Static["Static Translation Layer"]
        JSON["lang/{code}.json
12 files × 1,000+ keys (S3 fallback)"]
        VAPI["GET /public/lang/{code}
Valkey lang:{code} (primary)"]
        I18N["i18n.js Engine v5"]
        RTL["css/rtl.css
RTL Support"]
        VAPI --> I18N
        JSON -->|fallback| I18N
        I18N --> Pages["All Pages
data-i18n attributes"]
        LS --> I18N
    end

    subgraph Dynamic["Dynamic Translation Layer"]
        API["/translate endpoint"]
        EC["ElastiCache
translate:{lang}:{hash}
30-day TTL"]
        AT["Amazon Translate
API"]
        API --> EC
        EC -->|miss| AT
        AT --> EC
    end

    subgraph Email["Email Layer"]
        SES["Amazon SES"]
        ET["email_translations
Aurora Table
12 langs × 2 templates"]
        GT["getSupportEmailStrings()
12 languages hardcoded"]
        NT["newsletter_translations
Aurora Table
pre-translated per send"]
        GT --> SES
        ET --> SES
        NT --> SES
        AT -->|reply translation| SES
    end

    subgraph Bedrock["Bedrock (Qwen 3 235B)"]
        RH["Rhema
drafts reply in
customer's language"]
        NB["Newsletter translate
once per send,
stored not called live"]
    end

    subgraph Admin["TBCC Admin"]
        NC["Newsletter Console
Quill Editor"]
        SC["Support Console"]
        NC -->|"POST /newsletter/{id}/translate"| NB
        NB --> NT
        SC -->|English reply| AT
        RH -->|"draft, already in
target language"| SC
    end

    subgraph Map["Impact Map"]
        Pins["Pin Captions
(English in Aurora)"]
        Pins -->|tap| API
        API -->|translated| Panel["Detail Panel"]
    end

    LS -->|preferred_lang| Email

    style LS fill:#FF9900,stroke:#cc7a00,color:#fff
    style DD fill:#FF9900,stroke:#cc7a00,color:#fff
    style JSON fill:#10b981,stroke:#059669,color:#fff
    style I18N fill:#10b981,stroke:#059669,color:#fff
    style VAPI fill:#a855f7,stroke:#7c3aed,color:#fff
    style AT fill:#60a5fa,stroke:#3b82f6,color:#fff
    style EC fill:#a855f7,stroke:#7c3aed,color:#fff
    style SES fill:#f59e0b,stroke:#d97706,color:#fff
    style ET fill:#1e293b,stroke:#334155,color:#e2e8f0
    style GT fill:#1e293b,stroke:#334155,color:#e2e8f0
    style NT fill:#1e293b,stroke:#334155,color:#e2e8f0
    style RH fill:#c026d3,stroke:#a21caf,color:#fff
    style NB fill:#c026d3,stroke:#a21caf,color:#fff
    style API fill:#635bff,stroke:#4b44cc,color:#fff
        

10. Translation Caching Strategy

11. Cost Analysis