is composite identifier.

import { createHash } from 'crypto';

export function computeTranslationKey(sourceLang: string, targetLang: string, body: string): string {
  const normalized = body.trim().replace(/\s+/g, ' ').toLowerCase();
  const payload = `${sourceLang}:${targetLang}:${normalized}`;
  return createHash('sha256').update(payload).digest('hex').slice(0, 16);
}

The cache table should persist indefinitely. While chat messages are unique, bios, profile intros, and repeated phrases (e.g., "How are you?", "Nice to meet you") appear frequently across different user pairs. The marginal storage cost is negligible compared to LLM inference savings.

2. Server-Side Translation Orchestration

Streaming translation creates visual fragmentation. Instead, resolve the full translation server-side before delivering the message payload. This aligns with the user's mental model: a message is sent, processed, and received as a complete unit.

import { Anthropic } from '@anthropic-ai/sdk';
import { createClient } from '@supabase/supabase-js';

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const supabaseAdmin = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_SERVICE_ROLE!);

export async function resolveTranslation(
  sourceLang: string,
  targetLang: string,
  messageBody: string
): Promise<string> {
  const cacheKey = computeTranslationKey(sourceLang, targetLang, messageBody);
  
  const { data: cached } = await supabaseAdmin
    .from('translation_registry')
    .select('translated_body')
    .eq('cache_key', cacheKey)
    .single();

  if (cached?.translated_body) return cached.translated_body;

  const response = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    system: `Translate the following message from ${sourceLang} to ${targetLang}. Preserve tone, slang, emojis, and cultural context. Output only the translated text.`,
    messages: [{ role: 'user', content: messageBody }],
  });

  const translated = response.content[0].type === 'text' ? response.content[0].text : '';
  
  await supabaseAdmin.from('translation_registry').upsert({
    cache_key: cacheKey,
    source_lang: sourceLang,
    target_lang: targetLang,
    translated_body: translated,
  }, { onConflict: 'cache_key' });

  return translated;
}

Architecture Rationale:

• Using the service-role client for cache reads/writes bypasses RLS overhead during high-throughput operations.
• upsert with onConflict prevents race conditions when concurrent requests hit the same cache key.
• System prompt explicitly instructs tone preservation, which traditional engines consistently drop.

3. Atomic Safety Pipeline

Scam detection must occur before message persistence. Implement the pipeline as a Supabase RPC or server-side mutation that runs checks synchronously. This ensures flagged content never enters the primary messages table.

export async function runSafetyPipeline(messageBody: string): Promise<{ status: 'allow' | 'flag' | 'block'; reasons: string[] }> {
  const reasons: string[] = [];
  
  // Financial/crypto pattern detection
  const financialRegex = /\b(?:IBAN|SWIFT|BTC|ETH|USDT|0x[a-fA-F0-9]{40})\b/;
  if (financialRegex.test(messageBody)) reasons.push('financial_reference');

  // Contact handle extraction
  const contactRegex = /(?:@?\w{3,}\s*[\.:]?\s*(?:telegram|whatsapp|signal|discord)|\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/i;
  if (contactRegex.test(messageBody)) reasons.push('external_contact');

  // LLM toxicity assessment
  const toxicityCheck = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 64,
    system: 'Rate the toxicity/scam likelihood of this message from 0 to 10. Return only the number.',
    messages: [{ role: 'user', content: messageBody }],
  });

  const score = parseInt(toxicityCheck.content[0].type === 'text' ? toxicityCheck.content[0].text : '0', 10);
  if (score >= 8) reasons.push('high_toxicity');
  else if (score >= 5) reasons.push('moderate_toxicity');

  if (reasons.includes('high_toxicity') || reasons.includes('financial_reference')) {
    return { status: 'block', reasons };
  }
  if (reasons.length > 0) {
    return { status: 'flag', reasons };
  }
  return { status: 'allow', reasons: [] };
}

Architecture Rationale:

• Combining regex for deterministic patterns (crypto addresses, IBANs) with LLM scoring for contextual threats reduces false positives.
• Thresholds (≥8 block, ≥5 flag) are calibrated to minimize disruption while catching sophisticated social engineering.
• Flagged messages should automatically insert a row into a moderation_queue table for human review, creating an audit trail without blocking legitimate users prematurely.

4. Row-Level Security Hardening

RLS policies must account for token format variations. Legacy HS256 tokens sometimes return NULL for auth.uid() inside SQL contexts, even when the application layer recognizes the user. Always verify ownership in TypeScript before executing sensitive writes, and use service-role clients for cache operations that bypass RLS intentionally.

Pitfall Guide

Pitfall	Explanation	Fix / Best Practice
Streaming Translation UX Fragmentation	Token-by-token rendering breaks the conversational mental model. Users perceive piecemeal text as slower and more confusing, even if total latency is identical.	Render server-side. Wait for full translation before delivering the message payload. Optimize perceived speed with optimistic UI skeletons, not partial text.
Cache Key Collisions Across Contexts	Hashing only the message body ignores language direction and cultural context. "Cool" translated to Japanese differs from "Cool" translated to French, and bidirectional caches collide.	Key by (source_lang, target_lang, normalized_body). Include directionality explicitly. Never reuse translations across mismatched language pairs.
RLS auth.uid() Nullification	Supabase's auth.uid() can return NULL in SQL contexts when legacy token formats or custom JWT claims are used. Policies silently fail or allow unauthorized writes.	Use service-role client for server-side cache operations. Always re-verify user.id === record.owner_id in TypeScript before mutations. Implement WITH CHECK policies for inserts.
Over-Reliance on Regex for Scam Detection	Regex catches known patterns but fails on obfuscated text, translated scams, or contextual manipulation. Generates false positives on legitimate financial discussions.	Combine deterministic regex with LLM toxicity scoring. Use regex for hard blocks (crypto wallets, IBANs) and LLM for contextual flags. Maintain a keyword taxonomy that evolves with scam trends.
Auto-Translate Fatigue for Bilingual Users	Forcing translation on users who understand both languages feels patronizing and increases cognitive load. Reduces engagement in cross-cultural matches.	Make translation opt-in per conversation. Store user preference in user_settings. Default to original text with a one-click toggle.
Unbounded LLM Toxicity Costs	Running toxicity checks on every message without sampling or caching inflates API costs. Low-risk messages (greetings, weather) don't need scoring.	Implement risk-based sampling. Only score messages containing URLs, contact handles, or flagged keywords. Cache toxicity results for identical message hashes.
Ignoring Cache Invalidation for Profile Content	Bios and intros change frequently, but chat caches persist indefinitely. Stale translations degrade user experience when profiles are updated.	Separate cache tables: chat_translation_cache (append-only) and profile_translation_cache (versioned). Invalidate profile cache on UPDATE triggers.

Production Bundle

Action Checklist

• Implement content hashing with language directionality and body normalization
• Configure Supabase translation_registry table with composite unique constraint on cache key
• Set up server-side translation orchestration using Claude Sonnet with tone-preserving system prompts
• Build atomic safety pipeline combining regex pattern detection and LLM toxicity scoring
• Define moderation queue automation: flagged messages auto-insert into moderation_queue with reasons
• Harden RLS policies: add WITH CHECK clauses, verify ownership in TypeScript, use service-role for cache ops
• Implement opt-in translation toggle per conversation with user preference persistence
• Add risk-based sampling for toxicity checks to control LLM inference costs

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High-volume casual chat (dating/social)	Server-side LLM + content hash cache	Preserves tone, reduces redundant calls, aligns with conversational UX	~$1.20/1k msgs (cached)
Enterprise compliance (finance/legal)	Traditional MT + strict regex + human review	Predictable output, audit trails, lower liability	~$0.50/1k msgs + review overhead
Low-budget MVP / internal tool	Edge-cached MT + basic keyword filter	Fastest deployment, minimal infra, acceptable for formal text	~$0.30/1k msgs
Multilingual support desk	LLM streaming + real-time agent assist	Agents need partial context quickly; streaming aids response drafting	~$6.00/1k msgs

Configuration Template

-- Supabase: translation_registry table
CREATE TABLE translation_registry (
  cache_key TEXT PRIMARY KEY,
  source_lang TEXT NOT NULL,
  target_lang TEXT NOT NULL,
  translated_body TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_tr_lang_pair ON translation_registry(source_lang, target_lang);

-- Supabase: moderation_queue table
CREATE TABLE moderation_queue (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  message_id UUID REFERENCES messages(id),
  reporter_id UUID REFERENCES auth.users(id),
  reasons TEXT[] NOT NULL,
  status TEXT DEFAULT 'pending' CHECK (status IN ('pending', 'approved', 'rejected')),
  reviewed_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- RLS: translation_registry (read-only for clients, service-role for writes)
ALTER TABLE translation_registry ENABLE ROW LEVEL SECURITY;
CREATE POLICY "translation_cache_read" ON translation_registry FOR SELECT USING (true);
CREATE POLICY "translation_cache_write" ON translation_registry FOR INSERT/UPDATE USING (auth.jwt() ->> 'role' = 'service_role');

Quick Start Guide

1. Initialize the cache layer: Create the translation_registry table in Supabase. Add the composite index and RLS policies from the configuration template.
2. Deploy the orchestration service: Implement the resolveTranslation and runSafetyPipeline functions in a Next.js Route Handler or Server Action. Wire Anthropic Claude Sonnet with your API key.
3. Integrate with messaging flow: Intercept message sends on the client. Pass source/target languages and body to the server. Await full translation + safety verdict before persisting to the messages table.
4. Configure moderation routing: Set up a Supabase Edge Function or cron job to poll moderation_queue for pending status. Notify admin users via Web Push or email when new flags appear.
5. Validate with production traffic: Monitor cache hit rates, toxicity score distribution, and translation latency. Adjust regex patterns and LLM thresholds based on false positive/negative ratios. Deploy opt-in toggle to user settings.