voxflow 1.14.0 → 1.15.1

package/lib/commands/translate.js

@@ -0,0 +1,593 @@
+/**
+ * VoxFlow CLI — Translate command
+ *
+ * Translate SRT subtitles, plain text, or text files using the backend
+ * /api/llm/chat endpoint with batched prompts.
+ *
+ * Three input modes:
+ *   - SRT mode  (--srt <file>): Parse SRT, batch-translate captions, output translated SRT
+ *   - Text mode (--text "..."): Translate a single text string, print to stdout
+ *   - File mode (--input <file>): Read .txt/.md file, translate, write output file
+ *
+ * Cost: 1 quota per batch (10 captions). Using /api/llm/chat instead of
+ * /api/llm/translate saves 80-98% quota for SRT translation.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { API_BASE, TRANSLATE_DEFAULTS } = require('../core/config');
+const { chatCompletion, detectLanguage } = require('../core/llm-client');
+const { parseSrt, formatSrt } = require('../core/srt');
+
+// ─── Language mapping ────────────────────────────────────────────────────────
+
+const LANG_MAP = {
+  zh: 'Chinese (Simplified)',
+  en: 'English',
+  ja: 'Japanese',
+  ko: 'Korean',
+  fr: 'French',
+  de: 'German',
+  es: 'Spanish',
+  pt: 'Portuguese',
+  ru: 'Russian',
+  ar: 'Arabic',
+  th: 'Thai',
+  vi: 'Vietnamese',
+  it: 'Italian',
+  id: 'Indonesian',
+  ms: 'Malay',
+  yue: 'Cantonese',
+};
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+/**
+ * Split captions into batches of the given size.
+ * @param {Array} captions
+ * @param {number} batchSize
+ * @returns {Array<Array>}
+ */
+function batchCaptions(captions, batchSize = 10) {
+  const batches = [];
+  for (let i = 0; i < captions.length; i += batchSize) {
+    batches.push(captions.slice(i, i + batchSize));
+  }
+  return batches;
+}
+
+/**
+ * Build the system + user prompt for a batch of captions.
+ * @param {Array} captions - Caption objects with .text and optional .speakerId
+ * @param {string} fromLang - Full language name (e.g. "Chinese (Simplified)")
+ * @param {string} toLang   - Full language name (e.g. "English")
+ * @returns {{ system: string, user: string }}
+ */
+function buildTranslationPrompt(captions, fromLang, toLang) {
+  const system = [
+    `You are a professional subtitle translator. Translate each numbered line from ${fromLang} to ${toLang}.`,
+    '',
+    'Rules:',
+    '- Return ONLY the translated lines, one per number',
+    '- Keep the exact same numbering (1., 2., 3., ...)',
+    '- Preserve [Speaker: xxx] tags unchanged — do NOT translate speaker names',
+    '- Keep translations concise and natural for subtitles',
+    '- Do not add explanations, notes, or extra text',
+  ].join('\n');
+
+  const user = captions
+    .map((cap, i) => {
+      const prefix = cap.speakerId ? `[Speaker: ${cap.speakerId}] ` : '';
+      return `${i + 1}. ${prefix}${cap.text}`;
+    })
+    .join('\n');
+
+  return { system, user };
+}
+
+/**
+ * Parse the LLM response back into translated texts.
+ * Strategy: try numbered regex match first, then fall back to positional.
+ *
+ * @param {string} content - LLM response text
+ * @param {Array} originalCaptions - Original caption objects (for fallback)
+ * @returns {Array} Translated caption objects
+ */
+function parseTranslationResponse(content, originalCaptions) {
+  const lines = content.trim().split('\n').filter(l => l.trim());
+  const translated = [];
+
+  for (let i = 0; i < originalCaptions.length; i++) {
+    const pattern = new RegExp(`^${i + 1}\\.\\s*(.+)$`);
+    const match = lines.find(l => pattern.test(l.trim()));
+
+    if (match) {
+      const text = match.trim().replace(pattern, '$1').trim();
+      // Strip speaker tag from translated text (we preserve original speakerId)
+      let cleanText = text;
+      const speakerMatch = text.match(/^\[Speaker:\s*[^\]]+\]\s*/i);
+      if (speakerMatch) {
+        cleanText = text.slice(speakerMatch[0].length);
+      }
+      translated.push({
+        ...originalCaptions[i],
+        text: cleanText || originalCaptions[i].text,
+      });
+    } else {
+      // Fallback: try positional match
+      if (i < lines.length) {
+        const fallbackText = lines[i].replace(/^\d+\.\s*/, '').trim();
+        let cleanText = fallbackText;
+        const speakerMatch = fallbackText.match(/^\[Speaker:\s*[^\]]+\]\s*/i);
+        if (speakerMatch) {
+          cleanText = fallbackText.slice(speakerMatch[0].length);
+        }
+        translated.push({
+          ...originalCaptions[i],
+          text: cleanText || originalCaptions[i].text,
+        });
+      } else {
+        // Could not find translation — keep original
+        translated.push({ ...originalCaptions[i] });
+      }
+    }
+  }
+
+  return translated;
+}
+
+/**
+ * Adjust subtitle timing for translated text length differences.
+ * Only adjusts when the length ratio differs by more than THRESHOLD.
+ *
+ * @param {Array} sourceCaptions     - Original captions (for reference length)
+ * @param {Array} translatedCaptions - Translated captions
+ * @returns {Array} Captions with adjusted endMs
+ */
+function realignTimings(sourceCaptions, translatedCaptions) {
+  const THRESHOLD = 0.3;  // Only adjust if >30% length difference
+  const MIN_GAP_MS = 100;
+
+  const result = translatedCaptions.map((cap, i) => {
+    const source = sourceCaptions[i];
+    if (!source) return cap;
+
+    const sourceLen = source.text.length;
+    const targetLen = cap.text.length;
+    if (sourceLen === 0) return cap;
+
+    const ratio = targetLen / sourceLen;
+    if (ratio < (1 + THRESHOLD) && ratio > (1 - THRESHOLD)) {
+      return cap; // Similar length, no adjustment needed
+    }
+
+    const originalDuration = source.endMs - source.startMs;
+    let newDuration = Math.round(originalDuration * ratio);
+
+    // Clamp: don't exceed next caption's start
+    const nextStart = i < sourceCaptions.length - 1
+      ? sourceCaptions[i + 1].startMs
+      : Infinity;
+    const maxDuration = nextStart - cap.startMs - MIN_GAP_MS;
+    if (newDuration > maxDuration && maxDuration > 0) {
+      newDuration = maxDuration;
+    }
+
+    // Floor: at least 500ms
+    newDuration = Math.max(newDuration, 500);
+
+    return {
+      ...cap,
+      endMs: cap.startMs + newDuration,
+    };
+  });
+
+  return result;
+}
+
+// ─── Main command ────────────────────────────────────────────────────────────
+
+/**
+ * Translate command entry point (with SIGINT guard).
+ *
+ * @param {object} opts
+ * @param {string} opts.token     - JWT auth token
+ * @param {string} [opts.api]     - Backend base URL
+ * @param {string} [opts.srt]     - SRT file path
+ * @param {string} [opts.text]    - Inline text to translate
+ * @param {string} [opts.input]   - Text file path (.txt, .md)
+ * @param {string} [opts.from]    - Source language code (or 'auto')
+ * @param {string} opts.to        - Target language code (required)
+ * @param {string} [opts.output]  - Output file path
+ * @param {boolean}[opts.realign] - Adjust subtitle timing
+ * @param {number} [opts.batchSize] - Captions per LLM call (default: 10)
+ */
+async function translate(opts) {
+  const sigintHandler = () => {
+    console.log('\n\nTranslation cancelled.');
+    process.exit(130);
+  };
+  process.on('SIGINT', sigintHandler);
+
+  try {
+    return await _translate(opts);
+  } finally {
+    process.removeListener('SIGINT', sigintHandler);
+  }
+}
+
+async function _translate(opts) {
+  const {
+    token,
+    api = API_BASE,
+    srt,
+    text,
+    input,
+    from,
+    to,
+    output: userOutput,
+    realign = false,
+    batchSize = TRANSLATE_DEFAULTS.batchSize,
+  } = opts;
+
+  // Determine mode
+  if (srt) return _translateSrt({ token, api, srt, from, to, output: userOutput, realign, batchSize });
+  if (text) return _translateText({ token, api, text, from, to });
+  if (input) return _translateFile({ token, api, input, from, to, output: userOutput });
+
+  throw new Error('No input specified. Use --srt, --text, or --input');
+}
+
+// ─── SRT Translation ────────────────────────────────────────────────────────
+
+async function _translateSrt({ token, api, srt: srtPath, from, to, output: userOutput, realign, batchSize }) {
+  console.log('\n=== VoxFlow Translate (SRT) ===');
+
+  // Read and parse SRT
+  const resolved = path.resolve(srtPath);
+  const content = fs.readFileSync(resolved, 'utf8');
+  const captions = parseSrt(content);
+
+  if (captions.length === 0) {
+    throw new Error(`SRT file is empty or invalid: ${resolved}`);
+  }
+
+  console.log(`Input:    ${path.basename(resolved)}`);
+  console.log(`Captions: ${captions.length}`);
+
+  // Detect source language if not specified
+  const fromCode = from || await autoDetectLanguage(api, captions);
+  const fromLang = LANG_MAP[fromCode] || fromCode;
+  const toLang = LANG_MAP[to] || to;
+
+  console.log(`From:     ${fromLang} (${fromCode})`);
+  console.log(`To:       ${toLang} (${to})`);
+  console.log(`Realign:  ${realign ? 'yes' : 'no'}`);
+
+  // Batch and translate
+  const batches = batchCaptions(captions, batchSize);
+  console.log(`Batches:  ${batches.length} (batch size: ${batchSize})`);
+  console.log('');
+
+  let allTranslated = [];
+  let totalQuota = 0;
+
+  for (let bi = 0; bi < batches.length; bi++) {
+    const batch = batches[bi];
+    process.stdout.write(`  [${bi + 1}/${batches.length}] Translating ${batch.length} captions...`);
+
+    const { system, user } = buildTranslationPrompt(batch, fromLang, toLang);
+    const result = await chatCompletion({
+      apiBase: api,
+      token,
+      messages: [
+        { role: 'system', content: system },
+        { role: 'user', content: user },
+      ],
+      temperature: TRANSLATE_DEFAULTS.temperature,
+      maxTokens: TRANSLATE_DEFAULTS.maxTokens,
+    });
+
+    const translated = parseTranslationResponse(result.content, batch);
+    allTranslated = allTranslated.concat(translated);
+    totalQuota++;
+
+    if (result.quota) {
+      console.log(` OK (remaining: ${result.quota.remaining})`);
+    } else {
+      console.log(' OK');
+    }
+  }
+
+  // Optional re-alignment
+  if (realign) {
+    console.log('  Re-aligning subtitle timing...');
+    allTranslated = realignTimings(captions, allTranslated);
+  }
+
+  // Renumber captions
+  allTranslated = allTranslated.map((cap, i) => ({ ...cap, id: i + 1 }));
+
+  // Format output
+  const outputContent = formatSrt(allTranslated);
+
+  // Determine output path
+  let outputPath;
+  if (userOutput) {
+    outputPath = path.resolve(userOutput);
+  } else {
+    const base = path.basename(resolved, path.extname(resolved));
+    const dir = path.dirname(resolved);
+    // Pre-build filename — see scripts/check-no-asset-rewrite.js
+    const fname = base + '-' + to + '.srt';
+    outputPath = path.resolve(dir, fname);
+  }
+
+  fs.writeFileSync(outputPath, outputContent, 'utf8');
+
+  // Summary
+  console.log(`\n=== Done ===`);
+  console.log(`Output:   ${outputPath}`);
+  console.log(`Captions: ${allTranslated.length}`);
+  console.log(`Quota:    ${totalQuota} used`);
+
+  // Preview
+  if (allTranslated.length > 0) {
+    console.log(`\n--- Preview ---`);
+    const preview = allTranslated.slice(0, 3);
+    for (const cap of preview) {
+      const speaker = cap.speakerId ? `[${cap.speakerId}] ` : '';
+      const textSnippet = cap.text.length > 60
+        ? cap.text.slice(0, 57) + '...'
+        : cap.text;
+      console.log(`  ${cap.id}. ${speaker}${textSnippet}`);
+    }
+    if (allTranslated.length > 3) {
+      console.log(`  ... (${allTranslated.length - 3} more)`);
+    }
+  }
+
+  return {
+    outputPath,
+    captionCount: allTranslated.length,
+    quotaUsed: totalQuota,
+    from: fromCode,
+    to,
+  };
+}
+
+// ─── Text Translation ────────────────────────────────────────────────────────
+
+async function _translateText({ token, api, text, from, to }) {
+  console.log('\n=== VoxFlow Translate (Text) ===');
+
+  const fromCode = from || await autoDetectLanguage(api, [{ text }]);
+  const fromLang = LANG_MAP[fromCode] || fromCode;
+  const toLang = LANG_MAP[to] || to;
+
+  console.log(`From: ${fromLang} → To: ${toLang}`);
+
+  const result = await chatCompletion({
+    apiBase: api,
+    token,
+    messages: [
+      {
+        role: 'system',
+        content: `You are a professional translator. Translate the following text from ${fromLang} to ${toLang}. Return ONLY the translation, no explanations.`,
+      },
+      { role: 'user', content: text },
+    ],
+    temperature: TRANSLATE_DEFAULTS.temperature,
+    maxTokens: TRANSLATE_DEFAULTS.maxTokens,
+  });
+
+  const translated = result.content.trim();
+  console.log(`\n${translated}`);
+
+  const remaining = result.quota ? result.quota.remaining : '?';
+  console.log(`\n(Quota: 1 used, ${remaining} remaining)`);
+
+  return { text: translated, quotaUsed: 1, from: fromCode, to };
+}
+
+// ─── File Translation ────────────────────────────────────────────────────────
+
+async function _translateFile({ token, api, input, from, to, output: userOutput }) {
+  console.log('\n=== VoxFlow Translate (File) ===');
+
+  const resolved = path.resolve(input);
+  const content = fs.readFileSync(resolved, 'utf8');
+
+  if (content.trim().length === 0) {
+    throw new Error(`Input file is empty: ${resolved}`);
+  }
+
+  console.log(`Input:  ${path.basename(resolved)}`);
+  console.log(`Length: ${content.length} chars`);
+
+  const fromCode = from || await autoDetectLanguage(api, [{ text: content }]);
+  const fromLang = LANG_MAP[fromCode] || fromCode;
+  const toLang = LANG_MAP[to] || to;
+
+  console.log(`From:   ${fromLang} → To: ${toLang}`);
+
+  const result = await chatCompletion({
+    apiBase: api,
+    token,
+    messages: [
+      {
+        role: 'system',
+        content: `You are a professional translator. Translate the following document from ${fromLang} to ${toLang}. Preserve the original formatting (paragraphs, line breaks, markdown). Return ONLY the translation.`,
+      },
+      { role: 'user', content },
+    ],
+    temperature: TRANSLATE_DEFAULTS.temperature,
+    maxTokens: Math.max(TRANSLATE_DEFAULTS.maxTokens, 4000), // files may need more tokens
+  });
+
+  const translated = result.content.trim();
+
+  // Determine output path
+  let outputPath;
+  if (userOutput) {
+    outputPath = path.resolve(userOutput);
+  } else {
+    const ext = path.extname(resolved);
+    const base = path.basename(resolved, ext);
+    const dir = path.dirname(resolved);
+    // Pre-build filename — see scripts/check-no-asset-rewrite.js
+    const fname = base + '-' + to + ext;
+    outputPath = path.resolve(dir, fname);
+  }
+
+  fs.writeFileSync(outputPath, translated + '\n', 'utf8');
+
+  const remaining = result.quota ? result.quota.remaining : '?';
+  console.log(`\n=== Done ===`);
+  console.log(`Output: ${outputPath}`);
+  console.log(`Quota:  1 used, ${remaining} remaining`);
+
+  return { outputPath, quotaUsed: 1, from: fromCode, to };
+}
+
+// ─── Auto-detect language ────────────────────────────────────────────────────
+
+async function autoDetectLanguage(api, captions) {
+  // Take first few captions (or text) for detection
+  const sample = captions.slice(0, 3).map(c => c.text).join(' ');
+  const detected = await detectLanguage({ apiBase: api, text: sample });
+  return detected || 'auto';
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+// ─── CLI Handler ────────────────────────────────────────────────────────────
+
+async function handle(args) {
+  const { parseFlag, parseIntFlag, parseBoolFlag, runWithRetry } = require('../core/args');
+  const { getToken, getTokenInfo } = require('../core/auth');
+  const { API_BASE } = require('../core/config');
+
+  const api = parseFlag(args, '--api') || API_BASE;
+  const explicitToken = parseFlag(args, '--token');
+
+  // Parse and validate before auth
+  const srt = parseFlag(args, '--srt');
+  const text = parseFlag(args, '--text');
+  const input = parseFlag(args, '--input');
+  const from = parseFlag(args, '--from');
+  const to = parseFlag(args, '--to');
+  const output = parseFlag(args, '--output', '-o');
+  const realign = parseBoolFlag(args, '--realign');
+  const batchSize = parseIntFlag(args, '--batch-size');
+
+  // Validate --to is required
+  if (!to && !parseBoolFlag(args, '--help')) {
+    console.error('Error: --to <lang> is required. Example: voxflow translate --srt file.srt --to en');
+    process.exit(1);
+  }
+
+  // Validate language codes
+  const validLangs = ['zh', 'en', 'ja', 'ko', 'fr', 'de', 'es', 'pt', 'ru', 'ar', 'th', 'vi', 'it', 'id', 'ms', 'yue'];
+  if (to && !validLangs.includes(to)) {
+    console.error(`Error: --to must be one of: ${validLangs.join(', ')} (got: "${to}")`);
+    process.exit(1);
+  }
+  if (from && !validLangs.includes(from) && from !== 'auto') {
+    console.error(`Error: --from must be one of: auto, ${validLangs.join(', ')} (got: "${from}")`);
+    process.exit(1);
+  }
+
+  // Validate input source
+  const sources = [srt, text, input].filter(Boolean).length;
+  if (sources === 0 && !parseBoolFlag(args, '--help')) {
+    console.error('Error: Provide one of: --srt <file>, --text <text>, --input <file>');
+    process.exit(1);
+  }
+  if (sources > 1) {
+    console.error('Error: Specify only one input: --srt, --text, or --input');
+    process.exit(1);
+  }
+
+  // Validate file existence
+  if (srt) {
+    const fs = require('fs');
+    const path = require('path');
+    const resolved = path.resolve(srt);
+    if (!fs.existsSync(resolved)) {
+      console.error(`Error: SRT file not found: ${resolved}`);
+      process.exit(1);
+    }
+  }
+  if (input) {
+    const fs = require('fs');
+    const path = require('path');
+    const resolved = path.resolve(input);
+    if (!fs.existsSync(resolved)) {
+      console.error(`Error: Input file not found: ${resolved}`);
+      process.exit(1);
+    }
+  }
+
+  // Validate batch size
+  if (batchSize !== undefined) {
+    if (isNaN(batchSize) || batchSize < 1 || batchSize > 20) {
+      console.error(`Error: --batch-size must be between 1 and 20 (got: "${parseFlag(args, '--batch-size')}")`);
+      process.exit(1);
+    }
+  }
+
+  // Authenticate after all validation
+  let token;
+  if (explicitToken) {
+    token = explicitToken;
+  } else {
+    token = await getToken({ api });
+    const info = getTokenInfo();
+    if (info) {
+      console.log(`\x1b[32mLogged in as ${info.email}\x1b[0m`);
+    }
+  }
+
+  const opts = {
+    token, api, srt, text, input, from, to, output, realign, batchSize,
+  };
+
+  await runWithRetry(translate, opts, api, explicitToken);
+}
+
+const meta = {
+  translate: {
+    usage: '[opts]',
+    description: 'Translate SRT subtitles, text, or files',
+    options: [
+      `--srt <file>         SRT subtitle file to translate`,
+      `--text <text>        Inline text to translate`,
+      `--input <file>       Text file (.txt, .md) to translate`,
+      `--from <lang>        Source language code (default: auto-detect)`,
+      `--to <lang>          Target language code (required)`,
+      `--output <path>      Output file path (default: <input>-<lang>.<ext>)`,
+      `--realign            Adjust subtitle timing for target language length`,
+      `--batch-size <n>     Captions per LLM call, 1-20 (default: ${TRANSLATE_DEFAULTS.batchSize})`,
+    ],
+    examples: [
+      'voxflow translate --srt subtitles.srt --to en',
+      'voxflow translate --text "你好世界" --to en',
+      'voxflow translate --input article.txt --to en --output article-en.txt',
+    ],
+  },
+};
+
+module.exports = {
+  translate,
+  handle,
+  meta,
+  LANG_MAP,
+  // Expose internals for testing
+  _test: {
+    buildTranslationPrompt,
+    parseTranslationResponse,
+    realignTimings,
+    batchCaptions,
+  },
+};