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. Customers write in their language, admin reads in English. Admin replies in English, customers receive in their language.
• 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 Opt-out Pages — Both LPO and CPMP opt-out pages fully translated.
• Document Library — Card titles, descriptions, badges, and navigation all multi-lingual. Individual documents remain in English (noted to users).

The only content that remains English-only is the technical documentation itself — because the audience for those documents is developers who read English. Everything customer-facing is translated.

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.

Email Types

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 ?lang= query param)

Email Template Translation (Support)

The Go server contains a getSupportEmailStrings(lang) function with hardcoded translations for all 12 languages. This covers all email chrome: headings, greetings, body text, labels, button text, and footer. The user's actual message content is passed through as-is (or translated via AWS Translate for replies).

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.

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
2. Server stores original English in support_replies.message
3. If preferred_lang != "en": AWS Translate converts to customer's language, stored in support_replies.message_translated
4. Email notification sent with 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

Newsletter content is composed in the TBCC Newsletter Console using a Quill rich text editor. The admin writes in English. Future enhancement: AWS Translate integration for broadcast content, sending each subscriber their preferred language version.

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"]
        GT --> SES
        ET --> SES
        AT -->|reply translation| SES
    end

    subgraph Admin["TBCC Admin"]
        NC["Newsletter Console
Quill Editor"]
        SC["Support Console"]
        NC --> SES
        SC -->|English reply| AT
    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 API fill:#635bff,stroke:#4b44cc,color:#fff
        

10. Translation Caching Strategy

11. Cost Analysis