Claude API で多言語翻訳 SaaS を本番運用する設計ガイド — 用語集・スタイル・ドメイン適応の実装

// プレースホルダー方式の前処理（Markdown / プレーンテキスト向け）
type ProtectedText = {
  protectedText: string;
  placeholders: Record<string, string>;
};
 
export function protectInlineMarkup(input: string): ProtectedText {
  const placeholders: Record<string, string> = {};
  let counter = 0;
 
  // Markdown リンク [text](url) の URL のみ保護
  let protectedText = input.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match, text, url) => {
    const key = `__URL_${counter++}__`;
    placeholders[key] = url;
    return `[${text}](${key})`;
  });
 
  // 変数プレースホルダー {name} を保護
  protectedText = protectedText.replace(/\{[a-zA-Z_][a-zA-Z0-9_]*\}/g, (match) => {
    const key = `__VAR_${counter++}__`;
    placeholders[key] = match;
    return key;
  });
 
  // インラインコード `...` を保護
  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 {}

const cases = [
  'Hello {user_name}, welcome.',                                    // A 単純変数
  'You have {count, plural, one {# item} other {# items}} left.',   // B ICU plural
  'Set the `{api_key}` value in .env.',                             // C コード内の変数
  '{gender, select, male {He} female {She} other {They}} replied.', // D ICU select
  'Run `npm install` first.',                                       // E 通常のコード
  'See [the docs]({docs_url}) for {plan_name}.',                    // F リンク + 変数
];
 
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}`;
  }
 
  // 「退避できたか」は、保護後のテキストに波括弧やバッククォートが生で残っていないかで見る
  const leaked = /[{`]/.test(protectedText.replace(/__(URL|VAR|CODE)_\d+__/g, ''));
 
  console.log(
    restored === src ? 'roundtrip OK' : 'roundtrip NG',
    leaked ? 'leaked' : 'guarded',
    src,
  );
}

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];
 
    // インラインコードは最優先で丸ごと退避する（中の変数を触らせない）
    if (ch === '`') {
      const end = input.indexOf('`', i + 1);
      if (end !== -1) {
        out += put('CODE', input.slice(i, end + 1));
        i = end + 1;
        continue;
      }
    }
 
    // 対応する括弧を数え、ICU 構文なら入れ子ごと退避する
    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;
      }
    }
 
    // [text](url) は url だけ退避し、text は翻訳対象として残す
    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 {
  // 消えたキーは全部まとめて報告する。1 件ずつ throw すると原因の全体像が見えない
  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;
}

const ICU_HEAD = /^\{\s*([A-Za-z_]\w*)\s*,\s*(plural|selectordinal|select)\s*,/;
 
// {count, plural, one {# item} other {# items}}
//   → 骨格: {count, plural, one {__ICU_0_ARM_0__} other {__ICU_0_ARM_1__}}
//   → 翻訳対象: "# 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 })),
  };
}

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

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

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];
 
  // 日本語ターゲットの場合は敬体/常体を明示
  const localeSpecific = targetLocale.startsWith('ja')
    ? profile.formality === 'casual'
      ? 'For Japanese: use です・ます調 only when the original is conversational; otherwise use a neutral 敬体.'
      : 'For Japanese: always use 敬体 (です・ます調). Do NOT 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[] {
  // 単純な BM25 もしくは埋め込みコサイン類似度でランキング（ここでは簡易版）
  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 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 }],
  });
 
  // 途中で切れた訳文を「成功」として返さない（詳しくは直後の節）
  if (response.stop_reason === 'max_tokens') {
    throw new TruncatedOutputError(`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 {
  // 日本語→英語は短く、英語→日本語は長くなる傾向
  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')}`;
}

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."

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) {
        // 整合性エラーは temperature を下げて再試行が有効
        // ここではモデル呼び出しに temperature を渡せる前提で省略
        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) プレースホルダー保存
  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) 用語集適用率
  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) 長さ比率（経験則の許容範囲）
  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 : '';
  // 緩めの JSON 抽出
  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 {
  // 本番では暗号学的ハッシュを使う
  return `${segment}|${req.targetLocale}|${(req as any).styleProfileId ?? ''}`;
}
 
function segmentStillValid(entry: TranslationMemoryEntry, req: Omit<TranslateRequest, 'source'>): boolean {
  // キャッシュ無効化はちゃんとした設計が必要
  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}`) ?? []);
}