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

Pre-Processing — Don't Lose Tags or Placeholders

The most common translation incident I see is broken tags or variable placeholders ({user_name}, <a href="...">). Because Claude reads meaning, it sometimes "translates" the position of a tag and silently rearranges it.

There are two solid defenses. One is to swap inline markup for opaque placeholders before sending. The other is to extract only the translatable text nodes from a parsed AST. I switch based on input format: HTML and XML are safest with AST extraction, while Markdown is fine with placeholder substitution.

// 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 {}

The crucial part is throwing on a missing placeholder during restoration. If you silently return a translation with broken links, you ship broken UI to customers. In my pipelines, an integrity failure routes to retry (covered later), and after three failures it goes to a human review queue.

Find the Inputs That Break Your Guard Before Release

The code above has served me for a long time, but shipping it as-is guarantees a class of failures. Translation incidents almost never happen in the prose — they happen at the seams between syntaxes.

I wanted evidence rather than a hunch, so I ran protectInlineMarkup / restoreInlineMarkup unchanged on Node.js 22 against six input shapes that actually flow through a production pipeline, checking the full round trip of protect then restore. Working as an indie developer, I would much rather surface this class of defect in a five-minute harness than in a customer's bug report.

const cases = [
  'Hello {user_name}, welcome.',                                    // A simple variable
  'You have {count, plural, one {# item} other {# items}} left.',   // B ICU plural
  'Set the `{api_key}` value in .env.',                             // C variable inside code
  '{gender, select, male {He} female {She} other {They}} replied.', // D ICU select
  'Run `npm install` first.',                                       // E ordinary code span
  'See [the docs]({docs_url}) for {plan_name}.',                    // F link plus variable
];
 
for (const src of cases) {
  const { protectedText, placeholders } = protectInlineMarkup(src);
 
  let restored: string;
  try {
    restored = restoreInlineMarkup(protectedText, placeholders);
  } catch (error) {
    restored = `THROW: ${(error as Error).message}`;
  }
 
  // "Guarded" means no raw braces or backticks survive in the protected text
  const leaked = /[{`]/.test(protectedText.replace(/__(URL|VAR|CODE)_\d+__/g, ''));
 
  console.log(
    restored === src ? 'roundtrip OK' : 'roundtrip NG',
    leaked ? 'leaked' : 'guarded',
    src,
  );
}

The result: 5 of 6 round-tripped, but only 3 of 6 were fully guarded.

Two root causes explain all of it.

The first is chaining regular expressions. Variables are captured before code spans, so in case C the already-substituted key gets wrapped a second time inside the code span. At restore time the key looks absent from the text, and a perfectly healthy segment is flagged as broken and pushed to the human review queue. A queue inflated by false positives is every bit as costly as shipping a broken translation.

The second is assuming braces never nest. ICU MessageFormat plurals and selects are nested braces by definition. Case B matches nothing and passes straight through; case D captures only the inner arms. And a plural that reaches the model unguarded breaks at runtime without anyone noticing the moment the model helpfully translates the one and other keywords.

The fix is not another regex. It is a single scanning pass that counts matching braces.

export function protectInlineMarkup(input: string): ProtectedText {
  const placeholders: Record<string, string> = {};
  let out = '';
  let i = 0;
  let counter = 0;
 
  const put = (kind: string, value: string) => {
    const key = `__${kind}_${counter++}__`;
    placeholders[key] = value;
    return key;
  };
 
  while (i < input.length) {
    const ch = input[i];
 
    // Code spans go first and whole, so nothing inside them is ever touched
    if (ch === '`') {
      const end = input.indexOf('`', i + 1);
      if (end !== -1) {
        out += put('CODE', input.slice(i, end + 1));
        i = end + 1;
        continue;
      }
    }
 
    // Count matching braces so ICU syntax is captured with its nesting intact
    if (ch === '{') {
      let depth = 0;
      let j = i;
      for (; j < input.length; j++) {
        if (input[j] === '{') depth++;
        else if (input[j] === '}' && --depth === 0) break;
      }
      if (depth === 0 && j < input.length) {
        out += put('VAR', input.slice(i, j + 1));
        i = j + 1;
        continue;
      }
    }
 
    // For [text](url), guard only the url and leave text translatable
    if (ch === '[') {
      const close = input.indexOf('](', i);
      if (close !== -1) {
        const paren = input.indexOf(')', close + 2);
        if (paren !== -1) {
          out += input.slice(i, close + 2) + put('URL', input.slice(close + 2, paren)) + ')';
          i = paren + 1;
          continue;
        }
      }
    }
 
    out += ch;
    i++;
  }
 
  return { protectedText: out, placeholders };
}
 
export function restoreInlineMarkup(translated: string, placeholders: Record<string, string>): string {
  // Report every missing key at once — throwing on the first one hides the shape of the failure
  const missing = Object.keys(placeholders).filter((key) => !translated.includes(key));
  if (missing.length > 0) {
    throw new TranslationIntegrityError(`Placeholder lost: ${missing.join(', ')}`);
  }
 
  let restored = translated;
  for (const [key, original] of Object.entries(placeholders)) {
    restored = restored.replaceAll(key, original);
  }
  return restored;
}

Running the same six inputs again gives 6 of 6 round-tripped and 6 of 6 fully guarded. Making the scan order explicit in code removes the false positive in C and the pass-throughs in B and D at the same time.

One honest caveat, though: this does not solve ICU. Because case B is captured whole, # item — text that genuinely needs translating — falls out of the translation set entirely. In practice I keep the skeleton and push each branch body through as a child segment.

const ICU_HEAD = /^\{\s*([A-Za-z_]\w*)\s*,\s*(plural|selectordinal|select)\s*,/;
 
// {count, plural, one {# item} other {# items}}
//   → skeleton: {count, plural, one {__ICU_0_ARM_0__} other {__ICU_0_ARM_1__}}
//   → translatable: "# item" / "# items"
export function expandIcu(raw: string, index: number) {
  const head = raw.match(ICU_HEAD);
  if (!head) return null;
 
  const body = raw.slice(head[0].length, raw.length - 1);
  const arms: { key: string; text: string }[] = [];
  let i = 0;
 
  while (i < body.length) {
    while (i < body.length && /\s/.test(body[i])) i++;
    let k = i;
    while (k < body.length && !/[\s{]/.test(body[k])) k++;
    const key = body.slice(i, k).trim();
 
    while (k < body.length && /\s/.test(body[k])) k++;
    if (body[k] !== '{') break;
 
    let depth = 0;
    let j = k;
    for (; j < body.length; j++) {
      if (body[j] === '{') depth++;
      else if (body[j] === '}' && --depth === 0) break;
    }
    arms.push({ key, text: body.slice(k + 1, j) });
    i = j + 1;
  }
 
  if (arms.length === 0) return null;
 
  const skeleton =
    `{${head[1]}, ${head[2]}, ` +
    arms.map((arm, j) => `${arm.key} {__ICU_${index}_ARM_${j}__}`).join(' ') +
    '}';
 
  return {
    skeleton,
    arms: arms.map((arm, j) => ({ slot: `__ICU_${index}_ARM_${j}__`, text: arm.text })),
  };
}

From there you only need to drop each translation back into its slot. The plural keywords and the variable name stay sealed inside the skeleton, so the model has no opening to rewrite them.

If your resources are dense with ICU, swapping this hand-rolled scan for a real ICU parser is a perfectly reasonable call. My own threshold is blunt: once ICU-bearing segments pass 10% of the corpus, bring in a parser; below that, the thirty lines above carry their weight. Before adding a dependency, measure that percentage against your actual data.

Markup protection is an unglamorous layer. Yet whether you can explain your translation quality to a customer usually comes down to how quietly well this layer is doing its job.

Inject and Enforce a Glossary

In my experience, terminology drift accounts for a large share of customer complaints in translation SaaS. A reviewer who sees "Customer" rendered once as "顧客" and once as "カスタマー" loses trust in the entire document.

Claude handles long context well, so dumping the full glossary into the prompt is technically possible — but it wastes tokens and dilutes the signal. Filtering the glossary down to terms that actually appear in the source before injection cuts prompt size substantially in my projects while improving hit rate.

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`;
}

Note the wording. Claude takes user intent seriously, so when the prompt says MUST, compliance is significantly higher than with "for reference." Pair this with a post-translation check that the target term appears in the output, and you'll catch most glossary violations automatically (we wire this up in the quality gate section).

Tighten Glossary Matching with Word Boundaries

The selectRelevantGlossary above uses includes, a plain substring check. When I wrote it, I thought of it as "just see whether the term shows up in the source." That lightness came back to bite later.

On Node.js 22 I ran a five-term glossary (plan / API / log / sign in / Pro) against four English strings of the kind you see in real product copy.

That is four false positives, plus one miss: in the first string, the double-spaced sign in slipped past the substring check. The matcher grabbed log inside catalog, plan inside planet and Pro inside Professional, yet lost the real sign in — a glossary doing the opposite of its job.

The damage spreads to two places. In the prompt, terms absent from the source get declared MUST, which adds needless constraints and tokens. In the quality gate, glossaryRequired gets inflated, so terms that rightly never appear in the translation pile up as Glossary miss. More passed: false, and a human review queue that swells for no good reason.

The fix is to reject matches wedged between alphanumerics and to tolerate whitespace variation.

function escapeRegExp(s: string): string {
  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}
 
export function selectRelevantGlossary(
  sourceText: string,
  glossary: GlossaryEntry[]
): GlossaryEntry[] {
  return glossary.filter((entry) => {
    // 複数語の用語は空白の揺れ（連続スペース・改行）を許容する
    const body = escapeRegExp(entry.source).replace(/\s+/g, '\\s+');
    // 英数字に挟まれている一致（catalog の中の log など）は除外する
    const re = new RegExp(`(?<![A-Za-z0-9])${body}(?![A-Za-z0-9])`, entry.caseSensitive ? '' : 'i');
    return re.test(sourceText);
  });
}

For sources without word breaks, such as Japanese or Chinese, this boundary check means nothing. There I keep the substring match and instead make sure longer terms are checked first.

The glossary layer is unglamorous, but it sits at the very front of translation consistency. Check matching accuracy before you judge translation accuracy — this round-trip test reminded me of that line. If you already have a glossary, I would suggest running about twenty real strings through it and simply counting the false positives.

Style Profiles That Actually Move Tone

Translating a contract in a friendly tone is bad; translating a Twitter post in legalese is also bad. Style needs to be selectable per project or even per audience.

I model style with four axes:

• Formality: casual / standard / formal
• Audience: general / technical / executive
• Voice: prefer-active / neutral / prefer-passive
• Length bias: concise / faithful / expansive

Inject this into the system prompt:

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');
}

I include the Japanese-specific note because of a recurring failure mode: when translating English casual writing to Japanese, Claude tends to mirror the source's register and slip into 常体 (である調), which reads as rude in Japanese business contexts. A one-line locale-specific instruction fixes the issue. Whenever your output "feels off," try adding 1–2 lines of locale-specific guidance — it's the cheapest fix in the toolkit.

Domain Adaptation — Strategic Few-Shot, Not RAG-First

Medicine, law, finance, gaming — domain shifts the correct translation dramatically. My priority order for teaching a generic model about a domain is:

1. Improve the domain glossary (above)
2. Embed 2–5 reference translation pairs as few-shot examples
3. Only if 1 and 2 still fall short, retrieve domain reference documents via RAG

Counter-intuitively, two well-chosen few-shot examples handle most cases. Beyond five examples, my measurements show diminishing returns relative to the prompt cost. The trick is picking representative pairs: the first should be a typical sentence, the second should contain the term you most often get wrong, and the third should hit your hardest edge case.

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);
}

Production deployments swap the lexical scorer for embedding similarity, but lexical overlap is more than enough to start. Few-shot selection has a real impact on quality, so I keep separate few-shot pools per domain rather than one giant pool.

The Claude API Layer — Model Selection and Streaming

Model choice directly drives both quality and unit cost. My defaults:

• Short copy / UI strings / notification emails → Claude Haiku (cost-first)
• General blog posts / marketing copy → Claude Sonnet (balanced; default)
• Legal / contracts / medical → Claude Opus (quality-first; assumes human review)

Don't hardcode the choice — derive it from tenant configuration and content 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 maxTokens = estimateMaxTokens(protectedText, req.targetLocale);
  const response = await client.messages.create({
    model: MODEL_IDS[tier],
    max_tokens: maxTokens,
    system: systemPrompt,
    messages: [{ role: 'user', content: protectedText }],
  });
 
  // Never return a cut-off translation as a success (see the next section)
  if (response.stop_reason === 'max_tokens') {
    throw new TruncatedOutputError(`output was cut off at max_tokens=${maxTokens}`);
  }
  const block = response.content[0];
  if (block.type !== 'text') throw new Error('Unexpected content type');
  return restoreInlineMarkup(block.text, placeholders);
}
 
export class TruncatedOutputError extends Error {}
 
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')}`;
}

Keep this core under ~200 lines. It's where evaluation, retry, and observability layers will plug in, so it should stay readable. The max_tokens estimator is a starting point — most teams maintain a per-locale coefficient table that gets refined from production data.

A cut-off translation arrives without an error

When the max_tokens estimate is too small, the API does not raise an error. It returns the unfinished text with stop_reason: "max_tokens". That is why the code above checks stop_reason. An implementation that skips the check lets a sentence like "Your order ships within 3 business days" leave as "Your order will" and travel all the way to the quality gate.

To check the behavior without an API key, I swapped the response for a mock and ran three variants in Node.js (output reproduced as-is):

naive   : "Thank you for your purchase. Your order will"
guarded : TruncatedError - output hit max_tokens=10
retry   : "Thank you for your purchase. Your order ships within 3 business days."

From the top: no stop_reason check, a check that throws, and a check that doubles the budget and retries once. Because the client is a mock, this does not measure at what token count a real request gets cut. It does confirm one thing: a single branch that treats truncated output as a failure removes one path by which translations break silently.

Keep the retry to one attempt. If the output still gets cut at the cap (8000 in the code above), split the input and translate the parts, or route it to the human review queue. Logging where the cut happened also gives you the data to correct the per-locale coefficients.

Retries and Partial Translation Recovery

In long-form translation, network drops, timeouts, and truncated outputs are not edge cases — they happen daily. Plain exponential backoff is fine for transport errors. The trick is giving integrity errors (lost placeholders, glossary misses) their own handling rather than treating every failure the same way.

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))); }

I learned to separate integrity errors the hard way. Treating them like transport errors meant my retries kept hitting the same prompt-shape bug, burning tokens forever. Once integrity errors got their own branch (lower temperature, stronger phrasing), unnecessary retries dropped noticeably.

Quality Gates — Triage What Humans See

Sending every translation to a human reviewer is not financially viable. Automate the triage so humans only see the borderline cases. I rely on four gates:

• Placeholder integrity (already covered)
• Glossary adherence (target term appears in output)
• Length-ratio sanity check
• LLM-as-judge for relative quality (optional)

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,
  };
}

Tune the thresholds against real data. In my deployments, a glossaryAdherence >= 0.95 floor combined with the other signals routes 10–20% of jobs to human review — small enough to staff, large enough to catch silent regressions.

LLM-as-Judge for Regression Tests

When you change the prompt or extend the glossary, you can't tell by intuition whether quality went up or down. Pairwise judging with Claude makes regression testing tractable, even in CI.

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]);
}

Our team runs this judge over 30–50 sampled pairs on every PR that touches prompts. If win rate drops below 50% versus the baseline, the PR is auto-rejected. Total monthly cost stays in the tens of dollars. The discipline of replacing "feels better" with "wins more pairwise comparisons" is worth far more than the API spend.

Common Pitfalls

These are the mistakes I keep seeing repeated, including by myself.

1. Treating the Glossary as a Suggestion

"Here's a glossary, please refer to it" gets you suggestion-level compliance. Mark the glossary as MUST and pair it with a CI check that retries violations. That's when terminology consistency stops being a customer complaint.

2. Placeholder Names That Collide

Naming your placeholders __VAR_1__ looks fine until a source document happens to contain that string verbatim. I switched to Unicode section-mark wrappers like __§§VAR0001§§__ and have not seen a collision since.

3. Naive Length-Ratio Checks

EN→JA grows; JA→EN shrinks. A single global threshold flags healthy translations as "bad." Maintain coefficients per (source-locale, target-locale) pair.

4. Forgetting Style Profile in the Cache Key

Different style profiles produce different translations of the same source. Cache key must be hash(source + target_locale + style_profile_id + glossary_hash + model). Hashing source alone leaks one tenant's translations to another — a real privacy incident, not a hypothetical.

5. Stuffing Too Many Few-Shots

Five examples plateau. Twenty examples bloat the prompt for marginal quality. I cap at three retrieved examples; carefully picked beats numerous nearly every time.

Cost Control — Caching and Tiered Models

Translation cost is dominated by API calls. My priority order:

1. Exact-match cache — same input, same config, same output → no API call (KV or Redis)
2. Segment-level cache — hash by sentence; only re-translate changed segments
3. Prompt caching — Claude API's prompt caching reuses the system prompt with glossary and few-shots
4. Model tiering — Haiku for short or low-stakes, Sonnet for body content, Opus for regulated work

Prompt caching is especially powerful for translation workloads, because long shared headers (glossary, few-shots) get sent over and over. How much it saves depends on how large the shared part is and how many calls land inside the cache lifetime, so compare your own billing data before and after. The minimum cacheable size also differs by model, so check the official documentation. For broader cost patterns, see Cost Optimization Patterns for Claude API in Production.

Observability — Run Translation Jobs Against SLOs

The metrics that matter for translation are not quite the same as those for a chat assistant. At minimum I track:

• Job pass rate (auto-gate pass + human review pass)
• Glossary adherence mean and distribution
• Segment re-translation rate (the inverse of cache hit rate)
• Translation latency p50 / p95 / p99
• Per-language-pair unit cost and token usage

Dashboard them in Grafana or Datadog and define SLOs like "auto-gate pass rate ≥ 99%" and "glossary adherence ≥ 98%." This shares philosophy with Production Observability for Claude Code with OpenTelemetry — pairing traces with business metrics is what makes regressions actually findable.

Designing the Human Review Queue

Once the auto-gate flags a segment, a human reviewer needs to act on it within a reasonable SLA. This sounds obvious, but most translation SaaS implementations underinvest in the queue itself, which creates two problems: reviewers waste time triaging, and customers wait longer than expected.

I treat the review queue as its own product surface, not a debug tool. The queue should expose, per item, the violations the auto-gate found, the suspected severity, and the surrounding source context (not just the failing segment). When reviewers see only one sentence, they often resolve it incorrectly because they cannot judge tone or terminology without context.

A practical layout that has worked well for me:

• Top of the card: source segment with the previous and next segments dimmed for context
• Middle: candidate translation with violation annotations inline
• Bottom: glossary entries that should have applied, with a one-click "force this term" action

I added the one-click enforcement action to spare reviewers from hunting for the glossary entry and editing by hand. You can measure its effect as the median handling time per item, so capture that number before you ship it. At thousands of segments per day, even a small per-item difference adds up. Reviewers can also "promote" a corrected translation back into the few-shot pool, which closes the loop between human feedback and model behavior over time.

Versioning Translations and Re-Translation Strategy

Source content is rarely static. Customers update marketing copy, legal teams revise contracts, product teams ship new release notes. The naive approach — retranslate the entire document — wastes money and risks regressions.

A robust translation SaaS treats every translation as versioned, segment by segment. When a new source document arrives, you compute a segment-level diff against the previous version and only retranslate changed segments. The unchanged segments inherit their existing translations and quality scores.

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}`) ?? []);
}

The subtle but important detail is segmentStillValid. If the glossary changed, an old translation that previously passed the gate may now violate the new terminology, so it needs to be regenerated. Forgetting this check is how teams end up with documents where 80% of segments use the new term and 20% silently use the old one.

When to Reach for Fine-Tuning

People often ask whether they should fine-tune to gain domain accuracy. My honest answer for most teams is: not yet. Glossary plus few-shot plus a tight quality gate gets you 80–90% of the way for a fraction of the operational complexity, and you keep the option to swap in newer base models the moment they ship.

Fine-tuning makes sense when you have stable, high-volume traffic in a single narrow domain where the prompt-engineering ceiling has been reached and you need to drop tokens per request to control cost. Until you have hundreds of thousands of high-quality reviewed pairs in that single domain, the maintenance cost of fine-tuning rarely pays off. Re-evaluate this decision once a year — base model improvements often erase the gap your fine-tune used to provide.

Wrapping Up — Your Next Concrete Step

We have walked through the major design pieces of a production translation SaaS. The single most useful thing you can do today is decompose your project's quality requirements onto the five axes above.

Out of accuracy, terminology consistency, style consistency, fluency, and locale adaptation — which one is hurting you most right now? That answer dictates which section of this guide you should implement first. For most teams, terminology and style are where the highest ROI lives.

A translation SaaS will not work if you treat it as "just call the LLM." But once you decompose the problem and address each axis with the right control point, you can aim for quality close to a dedicated MT engine, and in domains where your glossary and reference translations are strong you may well surpass it. That claim only holds once your own evaluation (round-trip tests and LLM-as-Judge) confirms it. I hope the code and patterns above give you a useful starting line.

The glossary and quality-gate designs in this article carry over directly to any workflow where an LLM's output has to be inspected before it reaches customers. Start by swapping those six round-trip cases for real strings from your own resource files and running them.