Building a Production Multilingual Translation SaaS with Claude API — Glossaries, Style, and Domain Adaptation in Practice

// Placeholder approach (Markdown / plain text)
type ProtectedText = {
  protectedText: string;
  placeholders: Record<string, string>;
};
 
export function protectInlineMarkup(input: string): ProtectedText {
  const placeholders: Record<string, string> = {};
  let counter = 0;
 
  // Protect URL portion of Markdown links [text](url)
  let protectedText = input.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match, text, url) => {
    const key = `__URL_${counter++}__`;
    placeholders[key] = url;
    return `[${text}](${key})`;
  });
 
  // Protect variable placeholders {name}
  protectedText = protectedText.replace(/\{[a-zA-Z_][a-zA-Z0-9_]*\}/g, (match) => {
    const key = `__VAR_${counter++}__`;
    placeholders[key] = match;
    return key;
  });
 
  // Protect inline code `...`
  protectedText = protectedText.replace(/`[^`]+`/g, (match) => {
    const key = `__CODE_${counter++}__`;
    placeholders[key] = match;
    return key;
  });
 
  return { protectedText, placeholders };
}
 
export function restoreInlineMarkup(translated: string, placeholders: Record<string, string>): string {
  let restored = translated;
  for (const [key, original] of Object.entries(placeholders)) {
    if (!restored.includes(key)) {
      throw new TranslationIntegrityError(`Placeholder lost: ${key}`);
    }
    restored = restored.replaceAll(key, original);
  }
  return restored;
}
 
class TranslationIntegrityError extends Error {}

type GlossaryEntry = {
  source: string;
  target: string;
  caseSensitive?: boolean;
  context?: string;
};
 
export function selectRelevantGlossary(
  sourceText: string,
  glossary: GlossaryEntry[]
): GlossaryEntry[] {
  const lower = sourceText.toLowerCase();
  return glossary.filter((entry) => {
    const target = entry.caseSensitive ? sourceText : lower;
    const term = entry.caseSensitive ? entry.source : entry.source.toLowerCase();
    return target.includes(term);
  });
}
 
export function buildGlossaryInstruction(entries: GlossaryEntry[]): string {
  if (entries.length === 0) return '';
  const lines = entries.map((e) => {
    const ctx = e.context ? ` (context: ${e.context})` : '';
    return `- "${e.source}" → "${e.target}"${ctx}`;
  });
  return `\n## Mandatory Terminology\nYou MUST use exactly these target translations for the following source terms. Do not paraphrase or substitute synonyms:\n${lines.join('\n')}\n`;
}

type StyleProfile = {
  formality: 'casual' | 'standard' | 'formal';
  audience: 'general' | 'technical' | 'executive';
  voice: 'prefer-active' | 'neutral' | 'prefer-passive';
  lengthBias: 'concise' | 'faithful' | 'expansive';
  customNotes?: string;
};
 
export function renderStyleGuide(profile: StyleProfile, targetLocale: string): string {
  const formalityNote = {
    casual: 'Use a conversational tone with contractions when natural.',
    standard: 'Use a neutral, professional tone.',
    formal: 'Use formal register; avoid contractions and colloquialisms.',
  }[profile.formality];
 
  const voiceNote = {
    'prefer-active': 'Prefer active voice unless passive is idiomatic.',
    neutral: 'Choose voice that sounds most natural to a native reader.',
    'prefer-passive': 'Use passive voice where it conveys impartiality.',
  }[profile.voice];
 
  // Locale-specific overrides catch model habits before they ship
  const localeSpecific = targetLocale.startsWith('ja')
    ? profile.formality === 'casual'
      ? 'For Japanese: only use です/ます when the source is conversational; otherwise use a neutral 敬体.'
      : 'For Japanese: always use 敬体 (です/ます). Never use 常体 (である).'
    : '';
 
  return [
    '## Style Guide',
    `- Formality: ${formalityNote}`,
    `- Audience: ${profile.audience}`,
    `- Voice: ${voiceNote}`,
    `- Length: ${profile.lengthBias === 'concise' ? 'Be concise. Drop filler.' : profile.lengthBias === 'expansive' ? 'You may expand for clarity.' : 'Match the source length closely.'}`,
    localeSpecific,
    profile.customNotes ? `- Custom: ${profile.customNotes}` : '',
  ].filter(Boolean).join('\n');
}

type FewShotExample = {
  source: string;
  target: string;
  note?: string;
};
 
export function selectFewShots(
  sourceText: string,
  pool: FewShotExample[],
  k: number = 3
): FewShotExample[] {
  const scored = pool.map((ex) => ({
    ex,
    score: lexicalOverlap(sourceText, ex.source),
  }));
  scored.sort((a, b) => b.score - a.score);
  return scored.slice(0, k).map((s) => s.ex);
}
 
function lexicalOverlap(a: string, b: string): number {
  const tokensA = new Set(a.toLowerCase().split(/\s+/));
  const tokensB = b.toLowerCase().split(/\s+/);
  let hit = 0;
  for (const t of tokensB) if (tokensA.has(t)) hit++;
  return hit / Math.max(1, tokensB.length);
}

import Anthropic from '@anthropic-ai/sdk';
 
type ModelTier = 'haiku' | 'sonnet' | 'opus';
 
const MODEL_IDS: Record<ModelTier, string> = {
  haiku: 'claude-haiku-4-5-20251001',
  sonnet: 'claude-sonnet-4-6',
  opus: 'claude-opus-4-6',
};
 
type TranslateRequest = {
  source: string;
  sourceLocale: string;
  targetLocale: string;
  glossary?: GlossaryEntry[];
  style?: StyleProfile;
  fewShots?: FewShotExample[];
  domain?: 'general' | 'legal' | 'medical' | 'finance' | 'gaming';
  tier?: ModelTier;
};
 
export async function translate(req: TranslateRequest): Promise<string> {
  const tier = req.tier ?? selectTier(req);
  const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
 
  const { protectedText, placeholders } = protectInlineMarkup(req.source);
  const glossary = req.glossary ? selectRelevantGlossary(protectedText, req.glossary) : [];
  const fewShots = req.fewShots ? selectFewShots(protectedText, req.fewShots) : [];
 
  const systemPrompt = [
    'You are a professional translator.',
    `Translate from ${req.sourceLocale} to ${req.targetLocale}.`,
    'Preserve all placeholders like __VAR_0__, __URL_1__, __CODE_2__ exactly as-is.',
    req.style ? renderStyleGuide(req.style, req.targetLocale) : '',
    buildGlossaryInstruction(glossary),
    fewShots.length > 0 ? renderFewShots(fewShots) : '',
    'Output ONLY the translated text. No commentary, no quotation marks around the result.',
  ].filter(Boolean).join('\n\n');
 
  const response = await client.messages.create({
    model: MODEL_IDS[tier],
    max_tokens: estimateMaxTokens(protectedText, req.targetLocale),
    system: systemPrompt,
    messages: [{ role: 'user', content: protectedText }],
  });
 
  const block = response.content[0];
  if (block.type !== 'text') throw new Error('Unexpected content type');
  return restoreInlineMarkup(block.text, placeholders);
}
 
function selectTier(req: TranslateRequest): ModelTier {
  if (req.domain === 'legal' || req.domain === 'medical') return 'opus';
  if (req.source.length < 200) return 'haiku';
  return 'sonnet';
}
 
function estimateMaxTokens(text: string, targetLocale: string): number {
  // JA→EN tends to shrink; EN→JA tends to grow
  const baseRatio = targetLocale.startsWith('ja') ? 1.6 : 1.2;
  return Math.min(8000, Math.ceil(text.length * baseRatio));
}
 
function renderFewShots(examples: FewShotExample[]): string {
  const lines = examples.map((ex, i) => `### Example ${i + 1}\nSource: ${ex.source}\nTarget: ${ex.target}${ex.note ? `\nNote: ${ex.note}` : ''}`);
  return `## Reference Translations\n${lines.join('\n\n')}`;
}

type RetryConfig = {
  maxAttempts: number;
  baseDelayMs: number;
  maxDelayMs: number;
};
 
const DEFAULT_RETRY: RetryConfig = { maxAttempts: 3, baseDelayMs: 800, maxDelayMs: 8000 };
 
export async function translateWithRetry(req: TranslateRequest, config: RetryConfig = DEFAULT_RETRY): Promise<string> {
  let lastError: unknown;
  for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
    try {
      return await translate(req);
    } catch (err) {
      lastError = err;
      if (err instanceof TranslationIntegrityError) {
        // Integrity errors benefit from temperature 0 and a stronger emphasis prompt
        await sleep(jitter(config.baseDelayMs * attempt, config.maxDelayMs));
        continue;
      }
      if (attempt < config.maxAttempts) {
        await sleep(jitter(config.baseDelayMs * 2 ** (attempt - 1), config.maxDelayMs));
      }
    }
  }
  throw lastError;
}
 
function sleep(ms: number) { return new Promise((r) => setTimeout(r, ms)); }
function jitter(ms: number, max: number): number { return Math.min(max, Math.floor(ms * (0.6 + Math.random() * 0.8))); }

type QualityReport = {
  passed: boolean;
  scores: {
    placeholderIntegrity: number;
    glossaryAdherence: number;
    lengthRatio: number;
    judgeScore?: number;
  };
  violations: string[];
};
 
export function runQualityGate(
  source: string,
  translated: string,
  glossary: GlossaryEntry[],
  targetLocale: string
): QualityReport {
  const violations: string[] = [];
 
  // 1) Placeholder integrity
  const placeholderRegex = /__(?:URL|VAR|CODE)_\d+__/g;
  const sourcePh = (source.match(placeholderRegex) || []).length;
  const targetPh = (translated.match(placeholderRegex) || []).length;
  const placeholderIntegrity = sourcePh === 0 ? 1 : Math.max(0, 1 - Math.abs(sourcePh - targetPh) / sourcePh);
  if (placeholderIntegrity < 1) violations.push(`Placeholder mismatch: src=${sourcePh}, tgt=${targetPh}`);
 
  // 2) Glossary adherence
  let glossaryHits = 0;
  let glossaryRequired = 0;
  for (const entry of glossary) {
    if (source.toLowerCase().includes(entry.source.toLowerCase())) {
      glossaryRequired++;
      if (translated.includes(entry.target)) glossaryHits++;
      else violations.push(`Glossary miss: "${entry.source}" expected "${entry.target}"`);
    }
  }
  const glossaryAdherence = glossaryRequired === 0 ? 1 : glossaryHits / glossaryRequired;
 
  // 3) Length ratio (empirical bands)
  const expectedRatio = targetLocale.startsWith('ja') ? 1.4 : 1.0;
  const actualRatio = translated.length / Math.max(1, source.length);
  const ratioDelta = Math.abs(actualRatio - expectedRatio) / expectedRatio;
  const lengthRatio = ratioDelta < 0.5 ? 1 - ratioDelta : 0;
  if (lengthRatio < 0.5) violations.push(`Length ratio anomaly: ${actualRatio.toFixed(2)} vs expected ${expectedRatio}`);
 
  const passed = placeholderIntegrity >= 1 && glossaryAdherence >= 0.95 && lengthRatio >= 0.5;
 
  return {
    passed,
    scores: { placeholderIntegrity, glossaryAdherence, lengthRatio },
    violations,
  };
}

import Anthropic from '@anthropic-ai/sdk';
 
type JudgeVerdict = 'A' | 'B' | 'tie';
 
export async function judgePairwise(
  source: string,
  candidateA: string,
  candidateB: string,
  targetLocale: string
): Promise<{ verdict: JudgeVerdict; reason: string }> {
  const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
  const response = await client.messages.create({
    model: 'claude-sonnet-4-6',
    max_tokens: 400,
    system: `You are an expert ${targetLocale} translation judge. Compare two translations and decide which is better. Output JSON: {"verdict": "A"|"B"|"tie", "reason": "..."}`,
    messages: [{
      role: 'user',
      content: `Source:\n${source}\n\nCandidate A:\n${candidateA}\n\nCandidate B:\n${candidateB}`,
    }],
  });
  const text = response.content[0].type === 'text' ? response.content[0].text : '';
  const match = text.match(/\{[\s\S]*\}/);
  if (!match) throw new Error('Judge produced no JSON');
  return JSON.parse(match[0]);
}

type TranslationMemoryEntry = {
  sourceHash: string;
  source: string;
  target: string;
  styleProfileId: string;
  glossaryHash: string;
  modelTier: ModelTier;
  qualityScores: QualityReport['scores'];
  approvedAt: number;
};
 
export async function diffAndTranslate(
  oldSegments: string[],
  newSegments: string[],
  memory: Map<string, TranslationMemoryEntry>,
  req: Omit<TranslateRequest, 'source'>
): Promise<{ segment: string; translation: string; reused: boolean }[]> {
  const results: { segment: string; translation: string; reused: boolean }[] = [];
  for (const segment of newSegments) {
    const cached = memory.get(hashSegment(segment, req));
    if (cached && segmentStillValid(cached, req)) {
      results.push({ segment, translation: cached.target, reused: true });
    } else {
      const translation = await translateWithRetry({ ...req, source: segment });
      results.push({ segment, translation, reused: false });
    }
  }
  return results;
}
 
function hashSegment(segment: string, req: Omit<TranslateRequest, 'source'>): string {
  // Simplified — in production use a proper crypto hash
  return `${segment}|${req.targetLocale}|${(req as any).styleProfileId ?? ''}`;
}
 
function segmentStillValid(entry: TranslationMemoryEntry, req: Omit<TranslateRequest, 'source'>): boolean {
  // Cache invalidation is real engineering — don't ignore it
  if (entry.glossaryHash !== currentGlossaryHash(req)) return false;
  return true;
}
 
function currentGlossaryHash(req: Omit<TranslateRequest, 'source'>): string {
  return JSON.stringify(req.glossary?.map((g) => `${g.source}=>${g.target}`) ?? []);
}