diplomail (Stage E): LibreTranslate client + async translation worker

Synchronous translation on read (Stage D) blocks the HTTP handler on
translator I/O. Stage E switches to "send moments-fast, deliver
when translated": recipients whose preferred_language differs from
the detected body_lang are inserted with available_at=NULL, and an
async worker turns them on once a LibreTranslate call materialises
the cache row (or fails terminally after 5 retries).

Schema delta on diplomail_recipients: available_at,
translation_attempts, next_translation_attempt_at, plus a snapshot
recipient_preferred_language so the worker queries do not need a
join. Read paths (ListInbox, GetMessage, UnreadCount) filter on
available_at IS NOT NULL. Push fan-out is moved from Service to the
worker so the recipient only sees the toast when the inbox row is
actually visible.

Translator backend is now a configurable choice: empty
BACKEND_DIPLOMAIL_TRANSLATOR_URL → noop (deliver original);
populated → LibreTranslate HTTP client. Per-attempt timeout, max
attempts, and worker interval all live in DiplomailConfig. The HTTP
client itself is unit-tested via httptest (happy path, BCP47
normalisation, unsupported pair, 5xx, identical src/dst, missing
URL); worker delivery + fallback paths are covered by the
testcontainers-backed e2e tests in diplomail_e2e_test.go.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/internal/diplomail/admin_send.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"strings"
+	"time"
 
 	"github.com/google/uuid"
 	"go.uber.org/zap"
@@ -41,7 +42,7 @@ func (s *Service) SendAdminPersonal(ctx context.Context, in SendAdminPersonalInp
 	if err != nil {
 		return Message{}, Recipient{}, err
 	}
-	rcptInsert := buildRecipientInsert(msgInsert.MessageID, recipient)
+	rcptInsert := buildRecipientInsert(msgInsert.MessageID, recipient, msgInsert.BodyLang, s.nowUTC())
 
 	msg, recipients, err := s.deps.Store.InsertMessageWithRecipients(ctx, msgInsert, []RecipientInsert{rcptInsert})
 	if err != nil {
@@ -51,7 +52,7 @@ func (s *Service) SendAdminPersonal(ctx context.Context, in SendAdminPersonalInp
 		return Message{}, Recipient{}, fmt.Errorf("diplomail: send admin personal: unexpected recipient count %d", len(recipients))
 	}
 
-	s.publishMessageReceived(ctx, msg, recipients[0])
+	if recipients[0].AvailableAt != nil { s.publishMessageReceived(ctx, msg, recipients[0]) }
 	return msg, recipients[0], nil
 }
 
@@ -90,7 +91,7 @@ func (s *Service) SendAdminBroadcast(ctx context.Context, in SendAdminBroadcastI
 	}
 	rcptInserts := make([]RecipientInsert, 0, len(members))
 	for _, m := range members {
-		rcptInserts = append(rcptInserts, buildRecipientInsert(msgInsert.MessageID, m))
+		rcptInserts = append(rcptInserts, buildRecipientInsert(msgInsert.MessageID, m, msgInsert.BodyLang, s.nowUTC()))
 	}
 
 	msg, recipients, err := s.deps.Store.InsertMessageWithRecipients(ctx, msgInsert, rcptInserts)
@@ -98,7 +99,7 @@ func (s *Service) SendAdminBroadcast(ctx context.Context, in SendAdminBroadcastI
 		return Message{}, nil, fmt.Errorf("diplomail: send admin broadcast: %w", err)
 	}
 	for _, r := range recipients {
-		s.publishMessageReceived(ctx, msg, r)
+		if r.AvailableAt != nil { s.publishMessageReceived(ctx, msg, r) }
 	}
 	return msg, recipients, nil
 }
@@ -162,14 +163,14 @@ func (s *Service) SendPlayerBroadcast(ctx context.Context, in SendPlayerBroadcas
 	}
 	rcptInserts := make([]RecipientInsert, 0, len(members))
 	for _, m := range members {
-		rcptInserts = append(rcptInserts, buildRecipientInsert(msgInsert.MessageID, m))
+		rcptInserts = append(rcptInserts, buildRecipientInsert(msgInsert.MessageID, m, msgInsert.BodyLang, s.nowUTC()))
 	}
 	msg, recipients, err := s.deps.Store.InsertMessageWithRecipients(ctx, msgInsert, rcptInserts)
 	if err != nil {
 		return Message{}, nil, fmt.Errorf("diplomail: send player broadcast: %w", err)
 	}
 	for _, r := range recipients {
-		s.publishMessageReceived(ctx, msg, r)
+		if r.AvailableAt != nil { s.publishMessageReceived(ctx, msg, r) }
 	}
 	return msg, recipients, nil
 }
@@ -223,14 +224,14 @@ func (s *Service) SendAdminMultiGameBroadcast(ctx context.Context, in SendMultiG
 		}
 		rcptInserts := make([]RecipientInsert, 0, len(members))
 		for _, m := range members {
-			rcptInserts = append(rcptInserts, buildRecipientInsert(msgInsert.MessageID, m))
+			rcptInserts = append(rcptInserts, buildRecipientInsert(msgInsert.MessageID, m, msgInsert.BodyLang, s.nowUTC()))
 		}
 		msg, recipients, err := s.deps.Store.InsertMessageWithRecipients(ctx, msgInsert, rcptInserts)
 		if err != nil {
 			return nil, 0, fmt.Errorf("diplomail: insert multi-game broadcast for %s: %w", game.GameID, err)
 		}
 		for _, r := range recipients {
-			s.publishMessageReceived(ctx, msg, r)
+			if r.AvailableAt != nil { s.publishMessageReceived(ctx, msg, r) }
 		}
 		out = append(out, msg)
 		totalRecipients += len(recipients)
@@ -362,14 +363,14 @@ func (s *Service) publishGameLifecycle(ctx context.Context, ev LifecycleEvent) e
 	}
 	rcptInserts := make([]RecipientInsert, 0, len(members))
 	for _, m := range members {
-		rcptInserts = append(rcptInserts, buildRecipientInsert(msgInsert.MessageID, m))
+		rcptInserts = append(rcptInserts, buildRecipientInsert(msgInsert.MessageID, m, msgInsert.BodyLang, s.nowUTC()))
 	}
 	msg, recipients, err := s.deps.Store.InsertMessageWithRecipients(ctx, msgInsert, rcptInserts)
 	if err != nil {
 		return fmt.Errorf("diplomail lifecycle: insert %s system mail: %w", ev.Kind, err)
 	}
 	for _, r := range recipients {
-		s.publishMessageReceived(ctx, msg, r)
+		if r.AvailableAt != nil { s.publishMessageReceived(ctx, msg, r) }
 	}
 	return nil
 }
@@ -389,12 +390,12 @@ func (s *Service) publishMembershipLifecycle(ctx context.Context, ev LifecycleEv
 	if err != nil {
 		return err
 	}
-	rcptInsert := buildRecipientInsert(msgInsert.MessageID, target)
+	rcptInsert := buildRecipientInsert(msgInsert.MessageID, target, msgInsert.BodyLang, s.nowUTC())
 	msg, recipients, err := s.deps.Store.InsertMessageWithRecipients(ctx, msgInsert, []RecipientInsert{rcptInsert})
 	if err != nil {
 		return fmt.Errorf("diplomail lifecycle: insert %s system mail: %w", ev.Kind, err)
 	}
-	if len(recipients) == 1 {
+	if len(recipients) == 1 && recipients[0].AvailableAt != nil {
 		s.publishMessageReceived(ctx, msg, recipients[0])
 	}
 	return nil
@@ -457,21 +458,68 @@ func (s *Service) buildAdminMessageInsert(callerKind string, callerUserID *uuid.
 // buildRecipientInsert turns a MemberSnapshot into a RecipientInsert.
 // The race-name snapshot is nullable so a kicked player with no race
 // name on file is still addressable.
-func buildRecipientInsert(messageID uuid.UUID, m MemberSnapshot) RecipientInsert {
+//
+// `bodyLang` is the detected language of the message body. When the
+// recipient's preferred_language matches body_lang (or body_lang is
+// undetermined), the function fills AvailableAt with `now` so the
+// recipient row is materialised already-delivered; otherwise
+// AvailableAt stays nil and the translation worker takes over.
+func buildRecipientInsert(messageID uuid.UUID, m MemberSnapshot, bodyLang string, now time.Time) RecipientInsert {
 	in := RecipientInsert{
-		RecipientID:       uuid.New(),
-		MessageID:         messageID,
-		GameID:            m.GameID,
-		UserID:            m.UserID,
-		RecipientUserName: m.UserName,
+		RecipientID:                uuid.New(),
+		MessageID:                  messageID,
+		GameID:                     m.GameID,
+		UserID:                     m.UserID,
+		RecipientUserName:          m.UserName,
+		RecipientPreferredLanguage: normaliseLang(m.PreferredLanguage),
 	}
 	if m.RaceName != "" {
 		race := m.RaceName
 		in.RecipientRaceName = &race
 	}
+	if needsTranslation(bodyLang, in.RecipientPreferredLanguage) {
+		// AvailableAt left nil → worker will deliver after the
+		// translation cache is materialised (or after fallback).
+	} else {
+		t := now.UTC()
+		in.AvailableAt = &t
+	}
 	return in
 }
 
+// needsTranslation reports whether a recipient with preferredLang
+// needs to wait for a translated rendering before the message is
+// considered delivered. Undetermined body language and empty
+// recipient preferences are short-circuited to "no translation
+// needed" so we never block delivery on something the detector
+// could not label.
+func needsTranslation(bodyLang, preferredLang string) bool {
+	bodyLang = normaliseLang(bodyLang)
+	preferredLang = normaliseLang(preferredLang)
+	if bodyLang == "" || bodyLang == LangUndetermined {
+		return false
+	}
+	if preferredLang == "" || preferredLang == LangUndetermined {
+		return false
+	}
+	return bodyLang != preferredLang
+}
+
+// normaliseLang strips any region subtag and lowercases the result so
+// `en-US` and `EN` both collapse to `en`. The diplomail layer uses
+// ISO 639-1 codes; whatlanggo and LibreTranslate share that
+// vocabulary.
+func normaliseLang(tag string) string {
+	tag = strings.TrimSpace(tag)
+	if tag == "" {
+		return ""
+	}
+	if i := strings.IndexAny(tag, "-_"); i > 0 {
+		tag = tag[:i]
+	}
+	return strings.ToLower(tag)
+}
+
 func validateCaller(callerKind string, callerUserID *uuid.UUID, callerUsername string) error {
 	switch callerKind {
 	case CallerKindOwner: