@ansstory/hias 1.0.4 → 1.0.6

package/lib/core/translate.js

@@ -0,0 +1,1049 @@
+// 翻译命令处理 - 实现文件/文件夹翻译功能，支持百度翻译、腾讯翻译
+
+const fs = require('fs')
+const fsp = fs.promises
+const path = require('path')
+const os = require('os')
+const inquirer = require('inquirer')
+const chalk = require('chalk')
+const ora = require('ora')
+const { minimatch } = require('minimatch')
+const { baiduTranslate } = require('../utils/baidu-translate')
+const { tencentTranslate } = require('../utils/tencent-translate')
+const writeFile = require('../utils/write-file')
+const i18n = require('../i18n')
+const extractors = require('../extractors')
+const translationCache = require('../utils/translation-cache')
+const {
+  normalizeExistingCalls,
+  stripExistingI18nCalls,
+  extractChineseWithPositions,
+  applyReplacements,
+  applyJsonTranslation,
+  mergeAndWriteLocaleFiles,
+} = extractors
+
+/**
+ * 读取配置：优先项目级 .hias/setting.json，其次全局 ~/.hias-cli/config.json，最后使用默认值
+ */
+function resolveSetting(baseDir) {
+  const defaults = {
+    locales: ['zh-CN', 'en-US'],
+    outDir: '.hias/lang',
+    fallbackToKey: true,
+    provider: 'tencent',
+    appId: '',
+    secretKey: '',
+    replaceOriginalFile: false,
+    i18nCallTemplate: '$t',
+    extensions: [],
+  }
+
+  let settings = null
+
+  // 1. 项目级配置
+  const projectPath = path.join(baseDir, '.hias', 'setting.json')
+  if (fs.existsSync(projectPath)) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(projectPath, 'utf-8'))
+      settings = { ...defaults, ...(raw.translationSetting || raw) }
+    } catch (e) {
+      const t = i18n.getT()
+      console.warn(chalk.yellow(t('messages.translateSettingParseError')))
+    }
+  }
+
+  // 2. 全局配置（仅在未找到项目配置时使用）
+  if (!settings) {
+    const globalPath = path.join(os.homedir(), '.hias-cli', 'config.json')
+    if (fs.existsSync(globalPath)) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(globalPath, 'utf-8'))
+        if (raw.translationSetting) {
+          settings = { ...defaults, ...raw.translationSetting }
+        }
+      } catch (e) {
+        // 静默忽略全局配置解析错误
+      }
+    }
+  }
+
+  // 3. 最终兜底使用默认值
+  if (!settings) {
+    settings = { ...defaults }
+  }
+
+  // 校验并修复配置项
+  validateAndFixSettings(settings, defaults)
+
+  // 校验翻译 API 配置
+  const t = i18n.getT()
+  if (settings.provider === 'baidu' && (!settings.appId || !settings.secretKey)) {
+    console.warn(chalk.yellow(t('messages.translateMissingBaiduConfig')))
+  } else if (settings.provider === 'tencent' && (!settings.appId || !settings.secretKey)) {
+    console.warn(chalk.yellow(t('messages.translateMissingTencentConfig')))
+  }
+
+  return settings
+}
+
+function validateAndFixSettings(settings, defaults) {
+  const t = i18n.getT()
+  const warns = []
+
+  if (!Array.isArray(settings.locales) || settings.locales.length < 2) {
+    warns.push('locales: must be an array with at least 2 items (source + target), reset to default')
+    settings.locales = defaults.locales
+  }
+  if (!['baidu', 'tencent'].includes(settings.provider)) {
+    warns.push(`provider: "${settings.provider}" is invalid, must be "baidu" or "tencent", reset to "${defaults.provider}"`)
+    settings.provider = defaults.provider
+  }
+  if (typeof settings.appId !== 'string') {
+    warns.push('appId: must be a string, reset to empty')
+    settings.appId = ''
+  }
+  if (typeof settings.secretKey !== 'string') {
+    warns.push('secretKey: must be a string, reset to empty')
+    settings.secretKey = ''
+  }
+  if (typeof settings.outDir !== 'string') {
+    warns.push('outDir: must be a string, reset to default')
+    settings.outDir = defaults.outDir
+  }
+  if (typeof settings.replaceOriginalFile !== 'boolean') {
+    warns.push('replaceOriginalFile: must be a boolean, reset to default')
+    settings.replaceOriginalFile = defaults.replaceOriginalFile
+  }
+  if (typeof settings.fallbackToKey !== 'boolean') {
+    warns.push('fallbackToKey: must be a boolean, reset to default')
+    settings.fallbackToKey = defaults.fallbackToKey
+  }
+  if (typeof settings.i18nCallTemplate !== 'string') {
+    warns.push('i18nCallTemplate: must be a string, reset to default')
+    settings.i18nCallTemplate = defaults.i18nCallTemplate
+  }
+  if (!Array.isArray(settings.extensions)) {
+    settings.extensions = defaults.extensions
+  }
+
+  for (const w of warns) {
+    console.warn(chalk.yellow('Config warning: ' + w))
+  }
+}
+
+/**
+ * 将英文字本转换为合法的 key 名称：小写、空格/特殊字符转为下划线
+ */
+function sanitizeKey(text, maxLen = 40) {
+  let key = text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_|_$/g, '')
+  if (key.length > maxLen) {
+    key = key.substring(0, maxLen).replace(/_+$/, '')
+  }
+  return key || 'key'
+}
+
+/**
+ * 根据英文本列表生成去重后的 key，key 基于英文本内容
+ */
+function generateKeysFromTranslations(translations) {
+  const keys = []
+  const usedKeys = new Map()
+  for (const text of translations) {
+    let key = sanitizeKey(text)
+    if (usedKeys.has(key)) {
+      const count = usedKeys.get(key) + 1
+      usedKeys.set(key, count)
+      key = `${key}_${count}`
+    } else {
+      usedKeys.set(key, 0)
+    }
+    keys.push(key)
+  }
+  return keys
+}
+
+/**
+ * 将语言代码（如 zh-CN）转为 API 用的简码（如 zh）
+ * 百度 API 简码与标准不一致，需要映射
+ */
+function shortLang(locale) {
+  if (!locale) return 'zh'
+  const code = locale.split('-')[0].split('_')[0].toLowerCase()
+  // 百度翻译 API 特殊映射：jp→jp, kor→ko, fra→fr, spa→es, etc.
+  const BAIDU_LANG_MAP = {
+    ja: 'jp',
+    kor: 'ko',
+    fra: 'fr',
+    spa: 'es',
+    ru: 'ru',
+    ara: 'ar',
+    th: 'th',
+  }
+  return BAIDU_LANG_MAP[code] || code
+}
+
+/**
+ * 从中文文本生成简短的 fallback key，取首段前 20 个字符
+ */
+function generateFallbackKey(text) {
+  const firstLine = text.split(/\r?\n/)[0].trim()
+  const short = firstLine.replace(/[,，。！？、；：""''《》（）\s]+/g, '_').replace(/^_|_$/g, '')
+  return short.substring(0, 40) || 'key'
+}
+
+/**
+ * 交互式确认提示
+ */
+function promptConfirm(message) {
+  return inquirer.prompt([{ type: 'confirm', name: 'ok', message, default: false }]).then((a) => a.ok)
+}
+
+/**
+ * 将文本数组按字节长度分批
+ * @param {string[]} texts
+ * @param {number} maxBytes - 每批最大字节数（含 \n 分隔符）
+ * @returns {string[][]}
+ */
+function splitByByteLength(texts, maxBytes) {
+  const batches = []
+  let currentBatch = []
+  let currentBytes = 0
+  for (const text of texts) {
+    const textBytes = Buffer.byteLength(text, 'utf-8')
+    const sepBytes = currentBatch.length > 0 ? 1 : 0 // \n 分隔符
+    if (currentBytes + sepBytes + textBytes > maxBytes) {
+      if (currentBatch.length > 0) {
+        batches.push(currentBatch)
+      }
+      // 单个文本超长时仍单独成批，API 会自行处理截断或报错
+      currentBatch = [text]
+      currentBytes = textBytes
+    } else {
+      currentBatch.push(text)
+      currentBytes += sepBytes + textBytes
+    }
+  }
+  if (currentBatch.length > 0) {
+    batches.push(currentBatch)
+  }
+  return batches
+}
+
+async function translateBatch(texts, appId, secretKey, provider = 'baidu', from = 'zh', to = 'en') {
+  if (texts.length === 0) return []
+
+  if (provider === 'tencent') {
+    return await tencentTranslate(texts, appId, secretKey, from, to)
+  }
+
+  // 百度翻译 API 支持用换行符分隔多个文本，一次请求翻译
+  // 单次请求长度限制约 6000 字节，按 5000 字节分批留余量
+  const BATCH_MAX_BYTES = 5000
+  const batches = splitByByteLength(texts, BATCH_MAX_BYTES)
+  const allResults = []
+
+  for (const batch of batches) {
+    const combined = batch.join('\n')
+    let translated
+    try {
+      translated = await baiduTranslate(combined, appId, secretKey, from, to)
+    } catch {
+      translated = null
+    }
+
+    if (translated && translated.length === batch.length) {
+      allResults.push(...translated)
+    } else {
+      // 逐文本翻译，失败则回退到原文
+      for (const text of batch) {
+        try {
+          const [result] = await baiduTranslate(text, appId, secretKey, from, to)
+          allResults.push(result || text)
+        } catch {
+          allResults.push(text)
+        }
+      }
+    }
+  }
+
+  return allResults
+}
+
+/**
+ * 解析 name 参数：优先使用 --name/--n，否则从路径推断
+ */
+function resolveName(options, fallbackPath) {
+  let name = options.name || options.n
+  if (!name) {
+    name = path.basename(fallbackPath)
+  }
+  return name
+}
+
+/**
+ * 生成 locale maps (textToKey + 各语言的 map)
+ */
+function generateLocaleMaps(name, uniqueTexts, translatedTexts, translationPerformed, targetLocale) {
+  const map = { [name]: {} }
+  const textToKey = new Map()
+
+  if (translationPerformed) {
+    const subKeys = generateKeysFromTranslations(translatedTexts)
+    uniqueTexts.forEach((text, index) => {
+      const subKey = subKeys[index]
+      if (!textToKey.has(text)) textToKey.set(text, `${name}.${subKey}`)
+      map[name][subKey] = translatedTexts[index]
+    })
+  } else {
+    const keyCount = new Map()
+    const usedFallbackKeys = new Set()
+    uniqueTexts.forEach((text) => {
+      let subKey = generateFallbackKey(text)
+      if (usedFallbackKeys.has(subKey)) {
+        const count = (keyCount.get(subKey) || 0) + 1
+        keyCount.set(subKey, count)
+        subKey = `${subKey}_${count}`
+      }
+      usedFallbackKeys.add(subKey)
+      if (!textToKey.has(text)) textToKey.set(text, `${name}.${subKey}`)
+      map[name][subKey] = text
+    })
+  }
+
+  return { map, textToKey }
+}
+
+/**
+ * 调用翻译 API（带缓存），失败时回退到原文
+ * 逐文本处理：每段文本各自尝试翻译，失败仅影响自身
+ */
+async function translateOrFallback(uniqueTexts, settings, fromLang, toLang) {
+  const baseDir = process.cwd()
+  const t = i18n.getT()
+
+  // 先查缓存，筛选出未缓存文本
+  const results = new Array(uniqueTexts.length)
+  const uncachedIndices = []
+  const uncachedTexts = []
+
+  for (let i = 0; i < uniqueTexts.length; i++) {
+    const cached = translationCache.getCachedTranslation(uniqueTexts[i], fromLang, toLang, baseDir)
+    if (cached !== null) {
+      results[i] = cached
+    } else {
+      uncachedIndices.push(i)
+      uncachedTexts.push(uniqueTexts[i])
+    }
+  }
+
+  if (uncachedTexts.length === 0) {
+    return { translatedTexts: results, translationPerformed: true }
+  }
+
+  // 调用翻译 API
+  if (settings.appId && settings.secretKey && (settings.provider === 'baidu' || settings.provider === 'tencent')) {
+    try {
+      const apiResults = await translateBatch(uncachedTexts, settings.appId, settings.secretKey, settings.provider, shortLang(fromLang), shortLang(toLang))
+      // 回填结果，翻译失败处保留原文
+      for (let j = 0; j < uncachedTexts.length; j++) {
+        const translated = apiResults[j] || uncachedTexts[j]
+        results[uncachedIndices[j]] = translated
+        translationCache.setCachedTranslation(uncachedTexts[j], fromLang, toLang, translated, baseDir)
+      }
+      // 保存缓存
+      translationCache.saveCache(baseDir)
+      return { translatedTexts: results, translationPerformed: true }
+    } catch (err) {
+      console.log(chalk.red.bold(t('messages.translateTranslateFailed', { error: err.message })))
+    }
+  }
+
+  if (settings.appId && settings.secretKey) {
+    console.log(chalk.yellow('  \u26A0 ' + t('messages.translateApiFallback')))
+  } else {
+    console.log(chalk.yellow('  \u26A0 ' + t('messages.translateApiNotConfigured')))
+  }
+
+  // 回退：未缓存的用原文填充
+  for (let i = 0; i < uncachedTexts.length; i++) {
+    results[uncachedIndices[i]] = uncachedTexts[i]
+  }
+  return { translatedTexts: results, translationPerformed: false }
+}
+
+/**
+ * 输出翻译后的文件
+ */
+function writeTranslatedFile(filePath, translatedContent, outDir, settings) {
+  if (settings.replaceOriginalFile) {
+    fs.writeFileSync(filePath, translatedContent, 'utf-8')
+  } else {
+    const fullPath = path.join(outDir, path.basename(filePath))
+    const dir = path.dirname(fullPath)
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true })
+    }
+    fs.writeFileSync(fullPath, translatedContent, 'utf-8')
+  }
+}
+
+/**
+ * 展示预览差异
+ */
+function showDryRunDiff(origContent, previewContent, extractions, settings, filePath, outDir, t) {
+  const origLines = origContent.split(/\r?\n/)
+  const newLines = previewContent.split(/\r?\n/)
+  let changedCount = 0
+  const maxLines = Math.max(origLines.length, newLines.length)
+  for (let i = 0; i < maxLines; i++) {
+    const origLine = i < origLines.length ? origLines[i] : undefined
+    const newLine = i < newLines.length ? newLines[i] : undefined
+    if (origLine !== newLine) {
+      changedCount++
+      if (origLine !== undefined) {
+        console.log(`  ${chalk.red('~')} L${i + 1}: ${chalk.gray(origLine.trim().substring(0, 80))}`)
+      }
+      if (newLine !== undefined) {
+        console.log(`  ${chalk.green('+')}       ${chalk.white(newLine.trim().substring(0, 80))}`)
+      }
+    }
+  }
+  if (changedCount === 0) {
+    console.log(`  ${chalk.gray(t('messages.translateNoChanges'))}`)
+  }
+  for (const item of extractions) {
+    console.log(`  ${chalk.gray(item.text)} \u2192 ${chalk.green(item.key)}`)
+  }
+  if (settings.replaceOriginalFile) {
+    console.log(chalk.yellow(t('messages.translateDryRunReplace', { file: filePath })))
+  } else {
+    console.log(chalk.yellow(t('messages.translateDryRunOutput', { dir: path.join(settings.outDir, name) })))
+  }
+}
+
+/**
+ * 处理单个文件的翻译
+ */
+async function handleTranslateFileAction(filePath, options) {
+  const t = i18n.getT()
+  const settings = resolveSetting(process.cwd())
+  const cwd = process.cwd()
+  const fullPath = path.resolve(cwd, filePath)
+
+  if (!fs.existsSync(fullPath)) {
+    console.log(chalk.red.bold(t('messages.translateFileNotFound', { file: filePath })))
+    return
+  }
+
+  const fileExt = path.extname(fullPath).toLowerCase()
+  if (!extractors.getSupportedExtensions(settings).includes(fileExt)) {
+    console.log(chalk.red.bold(t('messages.translateUnsupportedType', { type: fileExt })))
+    return
+  }
+
+  // 未提供 name 时使用父级目录名
+  let name = resolveName(options, path.dirname(fullPath))
+
+  let content = fs.readFileSync(fullPath, 'utf-8')
+  const fileType = fileExt.slice(1)
+
+  // 将已有的国际化调用命名空间更新为当前 name
+  content = normalizeExistingCalls(content, name, settings.i18nCallTemplate)
+
+  // 移除已有的 $t() 调用，防止二次包裹
+  const extractionContent = stripExistingI18nCalls(content, settings.i18nCallTemplate)
+
+  // 提取中文文本
+  const extractions = extractChineseWithPositions(extractionContent, fileType)
+
+  if (extractions.length === 0) {
+    console.log(chalk.yellow.bold(t('messages.translateNoChineseFound', { file: filePath })))
+    return
+  }
+
+  // 提取预览模式：仅展示提取结果不翻译
+  if (options.showExtractions) {
+    console.log(chalk.cyan(t('messages.translateDryRunHeader', { file: filePath })))
+    for (const item of extractions) {
+      console.log(`  ${chalk.gray(item.text)}  (${item.context || fileType}, pos ${item.start}-${item.end})`)
+    }
+    return
+  }
+
+  // 提取所有中文文本用于翻译（去重）
+  const uniqueTexts = [...new Set(extractions.map((item) => item.text))]
+
+  const fromLang = settings.locales[0] || 'zh-CN'
+  const toLangs = settings.locales.length > 1 ? settings.locales.slice(1) : ['en-US']
+
+  // 翻译到各目标语言，生成 locale maps
+  const localeMaps = {}
+  let textToKey = null
+
+  for (const toLang of toLangs) {
+    const { translatedTexts, translationPerformed } = await translateOrFallback(uniqueTexts, settings, fromLang, toLang)
+    const result = generateLocaleMaps(name, uniqueTexts, translatedTexts, translationPerformed)
+    if (!textToKey) textToKey = result.textToKey
+    // source map 仅第一次写入
+    if (!localeMaps[fromLang]) localeMaps[fromLang] = {}
+    if (!localeMaps[fromLang][name]) localeMaps[fromLang][name] = {}
+    Object.assign(localeMaps[fromLang][name], result.map[name])
+    localeMaps[toLang] = result.map
+  }
+
+  extractions.forEach((item) => {
+    item.key = textToKey.get(item.text)
+  })
+
+  // 确定输出目录
+  const outDir = path.resolve(cwd, settings.outDir, name)
+
+  // 预览模式
+  if (options.dryRun) {
+    console.log(chalk.cyan(t('messages.translateDryRunHeader', { file: filePath })))
+    const primaryTarget = toLangs[0]
+    const previewContent =
+      fileType === 'json'
+        ? applyJsonTranslation(content, extractions, localeMaps[primaryTarget] || localeMaps[fromLang], name)
+        : applyReplacements(content, extractions, name, fileType, settings.i18nCallTemplate)
+    showDryRunDiff(content, previewContent, extractions, settings, filePath, outDir, t)
+    const confirmed = await promptConfirm(chalk.cyan('Apply changes? (y/N) '))
+    if (!confirmed) {
+      console.log(chalk.gray(t('messages.translateDryRunCancelled')))
+      return
+    }
+  }
+
+  // 写入语言文件（合并已有，移除不再引用的 key）
+  await mergeAndWriteLocaleFiles(outDir, fromLang, toLangs, name, localeMaps, [content], settings.i18nCallTemplate)
+
+  // 生成翻译后的文件内容并输出
+  const primaryTarget = toLangs[0]
+  const translatedContent =
+    fileType === 'json'
+      ? applyJsonTranslation(content, extractions, localeMaps[primaryTarget] || localeMaps[fromLang], name)
+      : applyReplacements(content, extractions, name, fileType, settings.i18nCallTemplate)
+
+  await saveBackupSync(name, settings.replaceOriginalFile ? [fullPath] : [], cwd, settings.replaceOriginalFile)
+  writeTranslatedFile(fullPath, translatedContent, outDir, settings)
+
+  if (settings.replaceOriginalFile) {
+    console.log(chalk.green.bold(t('messages.translateOriginalReplaced', { file: filePath })))
+  }
+  console.log(chalk.green.bold(t('messages.translateOutputSuccess', { dir: path.join(settings.outDir, name) })))
+}
+
+/**
+ * 处理文件夹的递归翻译
+ */
+async function handleTranslateFolderAction(folderPath, options) {
+  const t = i18n.getT()
+  const settings = resolveSetting(process.cwd())
+  const cwd = process.cwd()
+  const fullFolderPath = path.resolve(cwd, folderPath)
+
+  if (!fs.existsSync(fullFolderPath)) {
+    console.log(chalk.red.bold(t('messages.translateFolderNotFound', { folder: folderPath })))
+    return
+  }
+
+  // 未提供 name 时使用文件夹名
+  let name = resolveName(options, fullFolderPath)
+
+  // 递归查找所有支持的文件
+  const files = []
+  function walkDir(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        walkDir(fullPath)
+      } else if (entry.isFile()) {
+        const fileExt = path.extname(entry.name).toLowerCase()
+        if (extractors.getSupportedExtensions(settings).includes(fileExt)) {
+          files.push(fullPath)
+        }
+      }
+    }
+  }
+  walkDir(fullFolderPath)
+
+  // 应用 --exclude 过滤（支持 glob 模式，如 **/*.test.js 或 node_modules/**）
+  const excludePatterns = []
+  const raw = options.exclude
+  if (Array.isArray(raw)) {
+    excludePatterns.push(...raw)
+  } else if (typeof raw === 'string') {
+    for (const p of raw.split(',')) {
+      const t = p.trim()
+      if (t) excludePatterns.push(t)
+    }
+  }
+  const filteredFiles = excludePatterns.length > 0
+    ? files.filter((fp) => {
+        const rel = path.relative(fullFolderPath, fp).replace(/\\/g, '/')
+        return !excludePatterns.some((pattern) => minimatch(rel, pattern, { dot: true, matchBase: false }))
+      })
+    : files
+
+  if (filteredFiles.length === 0) {
+    console.log(chalk.yellow.bold(t('messages.translateNoSupportedFiles')))
+    return
+  }
+
+  if (excludePatterns.length > 0 && filteredFiles.length < files.length) {
+    console.log(chalk.gray(t('messages.translateExcludedCount', { count: files.length - filteredFiles.length })))
+  }
+
+  console.log(chalk.cyan(t('messages.translateFoundFiles', { count: filteredFiles.length })))
+
+  // 处理每个文件，收集所有中文文本
+  const allExtractions = []
+  const fileEntries = []
+  const isVerbose = options.verbose
+  let progress
+  if (!isVerbose) {
+    progress = ora(t('messages.translateProgress', { current: 0, total: filteredFiles.length, file: '' })).start()
+  }
+
+  for (const [idx, file] of filteredFiles.entries()) {
+    const relFile = path.relative(fullFolderPath, file)
+    if (isVerbose) {
+      console.log(chalk.gray(t('messages.translateVerboseProgress', { current: idx + 1, total: filteredFiles.length, file: relFile })))
+    } else {
+      progress.text = t('messages.translateProgress', { current: idx + 1, total: filteredFiles.length, file: relFile })
+    }
+
+    // 大文件警告
+    const stat = fs.statSync(file)
+    if (stat.size > 10 * 1024 * 1024) {
+      const warnMsg = t('messages.translateLargeFile', { file: relFile, size: Math.round(stat.size / 1024 / 1024) })
+      if (isVerbose) {
+        console.log(chalk.yellow(warnMsg))
+      } else {
+        progress.warn(warnMsg)
+      }
+    }
+
+    let content = fs.readFileSync(file, 'utf-8')
+    const ext = path.extname(file).slice(1)
+
+    // 将已有的国际化调用命名空间更新为当前 name
+    content = normalizeExistingCalls(content, name, settings.i18nCallTemplate)
+    const extractionContent = stripExistingI18nCalls(content, settings.i18nCallTemplate)
+    const extractions = extractChineseWithPositions(extractionContent, ext)
+
+    const relativeDir = path.relative(fullFolderPath, path.dirname(file))
+    const outputFile = relativeDir ? path.join(relativeDir, path.basename(file)) : path.basename(file)
+
+    const entryIdx = fileEntries.length
+    fileEntries.push({
+      file,
+      content,
+      ext,
+      extractions,
+      outputFile,
+    })
+
+    extractions.forEach((e) => {
+      allExtractions.push({ ...e, fileIdx: entryIdx })
+    })
+  }
+
+  if (!isVerbose && progress) {
+    progress.succeed(t('messages.translateFilesLoaded', { count: filteredFiles.length }))
+  }
+
+  // 去重：相同的中文文本只翻译一次
+  const seen = new Map()
+  const uniqueTexts = []
+
+  for (const item of allExtractions) {
+    if (!seen.has(item.text)) {
+      seen.set(item.text, uniqueTexts.length)
+      uniqueTexts.push(item.text)
+    }
+  }
+
+  if (uniqueTexts.length === 0) {
+    console.log(chalk.yellow.bold(t('messages.translateNoChineseFound', { file: folderPath })))
+    return
+  }
+
+  // 提取预览模式：仅展示提取结果不翻译
+  if (options.showExtractions) {
+    console.log(chalk.cyan(t('messages.translateDryRunFolderHeader', { folder: folderPath })))
+    for (const item of allExtractions) {
+      const relFile = path.relative(fullFolderPath, fileEntries[item.fileIdx].file)
+      console.log(`  ${chalk.gray(relFile)}: "${chalk.white(item.text)}" (pos ${item.start}-${item.end})`)
+    }
+    return
+  }
+
+  // 翻译到各目标语言，生成 locale maps
+  const fromLang = settings.locales[0] || 'zh-CN'
+  const toLangs = settings.locales.length > 1 ? settings.locales.slice(1) : ['en-US']
+
+  const localeMaps = {}
+  let textToKey = null
+  let anyTranslated = false
+
+  for (const toLang of toLangs) {
+    const { translatedTexts, translationPerformed } = await translateOrFallback(uniqueTexts, settings, fromLang, toLang)
+    const result = generateLocaleMaps(name, uniqueTexts, translatedTexts, translationPerformed)
+    if (!textToKey) textToKey = result.textToKey
+    if (!localeMaps[fromLang]) localeMaps[fromLang] = {}
+    if (!localeMaps[fromLang][name]) localeMaps[fromLang][name] = {}
+    Object.assign(localeMaps[fromLang][name], result.map[name])
+    localeMaps[toLang] = result.map
+    if (translationPerformed) anyTranslated = true
+  }
+
+  if (anyTranslated) {
+    console.log(chalk.green.bold(t('messages.translateTranslateSuccess')))
+  }
+
+  // 预览模式：仅打印不做实际写入
+  if (options.dryRun) {
+    console.log(chalk.cyan(t('messages.translateDryRunFolderHeader', { folder: folderPath })))
+    for (const entry of fileEntries) {
+      const relPath = path.relative(fullFolderPath, entry.file)
+      console.log(`  ${chalk.white(relPath)}`)
+      const keyedExtractions = entry.extractions.map((item) => {
+        const key = textToKey.get(item.text)
+        return key ? { ...item, key } : item
+      })
+      const previewContent =
+        entry.ext === 'json'
+          ? applyJsonTranslation(entry.content, keyedExtractions, localeMaps[toLangs[0]] || localeMaps[fromLang], name)
+          : applyReplacements(entry.content, keyedExtractions, name, entry.ext, settings.i18nCallTemplate)
+      const origLines = entry.content.split(/\r?\n/)
+      const newLines = previewContent.split(/\r?\n/)
+      let changedCount = 0
+      for (let i = 0; i < origLines.length; i++) {
+        if (origLines[i] !== newLines[i]) {
+          changedCount++
+          console.log(`    ${chalk.red('~')} L${i + 1}: ${chalk.gray(origLines[i].trim().substring(0, 80))}`)
+          console.log(`    ${chalk.green('+')}       ${chalk.white(newLines[i].trim().substring(0, 80))}`)
+        }
+      }
+      if (changedCount === 0) console.log(`    ${chalk.gray(t('messages.translateNoChanges'))}`)
+    }
+    const confirmed = await promptConfirm(chalk.cyan('Apply changes? (y/N) '))
+    if (!confirmed) {
+      console.log(chalk.gray(t('messages.translateDryRunCancelled')))
+      return
+    }
+  }
+
+  // 输出目录
+  const outDir = path.resolve(cwd, settings.outDir, name)
+
+  // 写入语言文件（合并已有，移除不再引用的 key）
+  const allContents = fileEntries.map((e) => e.content)
+  await mergeAndWriteLocaleFiles(outDir, fromLang, toLangs, name, localeMaps, allContents, settings.i18nCallTemplate)
+
+  // 备份所有原文件用于回滚
+  if (fileEntries.length > 0) {
+    await saveBackupSync(name, settings.replaceOriginalFile ? fileEntries.map((e) => e.file) : [], cwd, settings.replaceOriginalFile)
+  }
+
+  // 写入每个翻译后的文件
+  for (const [idx, entry] of fileEntries.entries()) {
+    const relPath = path.relative(fullFolderPath, entry.file)
+    console.log(chalk.gray(t('messages.translateProgress', { current: idx + 1, total: fileEntries.length, file: relPath })))
+    const keyedExtractions = entry.extractions.map((item) => {
+      const key = textToKey.get(item.text)
+      return { ...item, key }
+    })
+
+    let translatedContent
+    if (entry.ext === 'json') {
+      translatedContent = applyJsonTranslation(entry.content, keyedExtractions, localeMaps[toLangs[0]] || localeMaps[fromLang], name)
+    } else {
+      translatedContent = applyReplacements(entry.content, keyedExtractions, name, entry.ext, settings.i18nCallTemplate)
+    }
+
+    if (settings.replaceOriginalFile) {
+      // replaceOriginalFile 时仅替换原文件，不拷贝到 outDir
+      fs.writeFileSync(entry.file, translatedContent, 'utf-8')
+    } else {
+      // 否则输出到 outDir
+      await writeFile(path.join(outDir, entry.outputFile), translatedContent)
+    }
+  }
+
+  if (settings.replaceOriginalFile) {
+    console.log(chalk.green.bold(t('messages.translateOriginalReplacedFolder', { folder: folderPath })))
+  }
+
+  console.log(chalk.green.bold(t('messages.translateFolderOutputSuccess', { dir: path.join(settings.outDir, name) })))
+}
+
+/**
+ * 在项目中生成 .hias/setting.json 配置文件
+ */
+async function handleSettingAction() {
+  const t = i18n.getT()
+  const cwd = process.cwd()
+  const projectPath = path.join(cwd, '.hias', 'setting.json')
+
+  if (fs.existsSync(projectPath)) {
+    console.log(chalk.yellow.bold(t('messages.translateSettingExists', { file: projectPath })))
+    return
+  }
+
+  const content = {
+    translationSetting: {
+      locales: ['zh-CN', 'en-US'],
+      outDir: '.hias/lang',
+      fallbackToKey: true,
+      replaceOriginalFile: false,
+      provider: 'tencent',
+      i18nCallTemplate: '$t',
+      appId: '',
+      secretKey: '',
+    },
+  }
+
+  await writeFile(projectPath, JSON.stringify(content, null, 2))
+  console.log(chalk.green.bold(t('messages.translateSettingCreated', { file: path.join('.hias', 'setting.json') })))
+}
+
+/**
+ * 生成全局 ~/.hias-cli/config.json 配置文件
+ */
+async function handleGlobalSettingAction() {
+  const t = i18n.getT()
+  const globalPath = path.join(os.homedir(), '.hias-cli', 'config.json')
+  let config = {}
+
+  if (fs.existsSync(globalPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(globalPath, 'utf-8'))
+    } catch (e) {
+      // 忽略
+    }
+  }
+
+  // 保留已有配置（如 language），只更新 translationSetting
+  config.translationSetting = {
+    locales: ['zh-CN', 'en-US'],
+    outDir: '.hias/lang',
+    fallbackToKey: true,
+    replaceOriginalFile: false,
+    provider: 'tencent',
+    i18nCallTemplate: '$t',
+    appId: '',
+    secretKey: '',
+  }
+
+  const configDir = path.dirname(globalPath)
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true })
+  }
+  fs.writeFileSync(globalPath, JSON.stringify(config, null, 2), 'utf-8')
+  console.log(chalk.green.bold(t('messages.translateSettingCreated', { file: globalPath })))
+}
+
+// === 回滚功能：备份与恢复 ===
+
+const BACKUP_ROOT = '.hias/.langbackup'
+
+/**
+ * 备份原文件内容到 .hias/.langbackup/<timestamp>_<name>/manifest.json，保留所有历史
+ */
+async function saveBackupSync(name, filePaths, cwd, replaceOriginalFile) {
+  const now = new Date()
+  const ts = `${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, '0')}${String(now.getDate()).padStart(2, '0')}_${String(now.getHours()).padStart(2, '0')}${String(now.getMinutes()).padStart(2, '0')}${String(now.getSeconds()).padStart(2, '0')}`
+  const backupDir = path.join(cwd, BACKUP_ROOT, `${ts}_${name}`)
+  await fsp.mkdir(backupDir, { recursive: true })
+
+  const files = {}
+  if (replaceOriginalFile) {
+    for (const fp of filePaths) {
+      const relativePath = path.relative(cwd, fp).replace(/\\/g, '/')
+      files[relativePath] = await fsp.readFile(fp, 'utf-8')
+    }
+  }
+
+  const manifest = {
+    name,
+    timestamp: now.toISOString(),
+    replaceOriginalFile,
+    files,
+    outputDir: path.join('.hias', 'lang', name).replace(/\\/g, '/'),
+  }
+
+  await fsp.writeFile(path.join(backupDir, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf-8')
+}
+
+/**
+ * 单步回滚：恢复最近一次备份，保留其他历史备份
+ */
+async function handleRollbackAction(options = {}) {
+  const t = i18n.getT()
+  const cwd = process.cwd()
+  const backupRoot = path.join(cwd, BACKUP_ROOT)
+
+  if (!fs.existsSync(backupRoot)) {
+    console.log(chalk.red.bold(t('messages.translateRollbackNoBackup')))
+    return
+  }
+
+  const entries = fs
+    .readdirSync(backupRoot, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort()
+    .reverse()
+
+  if (entries.length === 0) {
+    console.log(chalk.red.bold(t('messages.translateRollbackNoBackup')))
+    return
+  }
+
+  // --list 模式：仅列出备份
+  if (options.list) {
+    console.log(chalk.cyan(t('messages.translateRollbackListHeader')))
+    for (const entry of entries) {
+      const mp = path.join(backupRoot, entry, 'manifest.json')
+      if (fs.existsSync(mp)) {
+        try {
+          const m = JSON.parse(fs.readFileSync(mp, 'utf-8'))
+          console.log(`  ${chalk.white(entry)}  ${chalk.gray(m.name)}  ${m.replaceOriginalFile ? chalk.yellow('replace') : chalk.gray('copy')}`)
+        } catch {
+          console.log(`  ${chalk.white(entry)}  ${chalk.red(t('messages.translateRollbackParseError'))}`)
+        }
+      }
+    }
+    return
+  }
+
+  // --keep 模式：清理旧备份
+  if (options.keep !== undefined) {
+    const keepCount = parseInt(options.keep, 10)
+    if (isNaN(keepCount) || keepCount < 0) {
+      console.log(chalk.red('--keep must be a non-negative number'))
+      return
+    }
+    const sortedAsc = [...entries].sort()
+    if (sortedAsc.length <= keepCount) {
+      console.log(chalk.gray(t('messages.translateRollbackKeepNone')))
+      return
+    }
+    const toRemove = sortedAsc.slice(0, sortedAsc.length - keepCount)
+    for (const dir of toRemove) {
+      const fullDir = path.join(backupRoot, dir)
+      fs.rmSync(fullDir, { recursive: true, force: true })
+      console.log(chalk.gray('Removed backup: ' + dir))
+    }
+    if (fs.readdirSync(backupRoot).length === 0) {
+      fs.rmSync(backupRoot, { recursive: true, force: true })
+    }
+    console.log(chalk.green.bold(t('messages.translateRollbackKeepDone', { keep: keepCount })))
+    return
+  }
+
+  // --name 模式：回滚指定备份
+  let target = entries[0]
+  if (options.name) {
+    const found = entries.find((e) => e === options.name)
+    if (found) {
+      target = found
+    } else {
+      console.log(chalk.red.bold(t('messages.translateRollbackNotFound', { name: options.name })))
+      return
+    }
+  }
+
+  const latestDir = path.join(backupRoot, target)
+  const manifestPath = path.join(latestDir, 'manifest.json')
+
+  if (!fs.existsSync(manifestPath)) {
+    console.log(chalk.red.bold(t('messages.translateRollbackParseError')))
+    return
+  }
+
+  let manifest
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'))
+  } catch (e) {
+    console.log(chalk.red.bold(t('messages.translateRollbackParseError')))
+    return
+  }
+
+  // 恢复原文件
+  if (manifest.replaceOriginalFile && manifest.files) {
+    for (const [relativePath, originalContent] of Object.entries(manifest.files)) {
+      const originalFile = path.resolve(cwd, relativePath)
+      fs.writeFileSync(originalFile, originalContent, 'utf-8')
+      console.log(chalk.gray(t('messages.translateRollbackRestored', { file: relativePath })))
+    }
+  }
+
+  // 删除该次备份对应的输出目录
+  const outputDir = path.resolve(cwd, manifest.outputDir)
+  if (fs.existsSync(outputDir)) {
+    fs.rmSync(outputDir, { recursive: true, force: true })
+  }
+
+  // 只删除本次备份目录
+  fs.rmSync(latestDir, { recursive: true, force: true })
+
+  // 备份根目录为空时一并删除
+  if (fs.readdirSync(backupRoot).length === 0) {
+    fs.rmSync(backupRoot, { recursive: true, force: true })
+  }
+
+  console.log(chalk.green.bold(t('messages.translateRollbackSuccess')))
+}
+
+/**
+ * 将 .hias 目录添加到 .gitignore
+ */
+function handleGitignoreAction() {
+  const t = i18n.getT()
+  const cwd = process.cwd()
+  const gitignorePath = path.join(cwd, '.gitignore')
+
+  const entry = '.hias'
+
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, 'utf-8')
+    const lines = content.split(/\r?\n/).map((l) => l.trim())
+    if (lines.includes(entry) || lines.some((l) => l === '/' + entry)) {
+      console.log(chalk.green(t('messages.translateGitignoreExists')))
+      return
+    }
+    fs.writeFileSync(gitignorePath, content.replace(/\r?\n$/, '') + '\n' + entry + '\n', 'utf-8')
+    console.log(chalk.green(t('messages.translateGitignoreCreated')))
+  } else {
+    fs.writeFileSync(gitignorePath, entry + '\n', 'utf-8')
+    console.log(chalk.green(t('messages.translateGitignoreCreateFile')))
+  }
+}
+
+module.exports = {
+  handleTranslateFileAction,
+  handleTranslateFolderAction,
+  handleSettingAction,
+  handleGlobalSettingAction,
+  handleRollbackAction,
+  handleGitignoreAction,
+  // 导出的内部函数，用于单元测试
+  resolveSetting,
+  sanitizeKey,
+  generateKeysFromTranslations,
+  shortLang,
+  generateFallbackKey,
+  splitByByteLength,
+  translateBatch,
+  saveBackupSync,
+  // 从 extractors 模块重新导出所有提取相关函数
+  ...extractors,
+}