locale-sync-cli 1.0.0

package/lib/io/googleSheets.js

@@ -0,0 +1,220 @@
+const { google } = require('googleapis');
+const pRetry = require('p-retry');
+const fs = require('fs');
+const path = require('path');
+
+const BATCH_LIMIT = 400;
+
+function columnIndexToLetter(index) {
+  let col = '';
+  let n = index + 1;
+  while (n > 0) {
+    const r = (n - 1) % 26;
+    col = String.fromCharCode(65 + r) + col;
+    n = Math.floor((n - 1) / 26);
+  }
+  return col;
+}
+
+async function getClient(config) {
+  const scopes = ['https://www.googleapis.com/auth/spreadsheets'];
+  // 优先读取机器级环境变量（base64 编码的 service-account JSON）
+  const b64 = process.env.LOCALE_SYNC_CREDENTIALS;
+  if (b64) {
+    let credentials;
+    try {
+      credentials = JSON.parse(Buffer.from(b64, 'base64').toString('utf8'));
+    } catch {
+      throw new Error('LOCALE_SYNC_CREDENTIALS 格式无效，请重新运行 locale-sync set-credentials');
+    }
+    const auth = new google.auth.GoogleAuth({ credentials, scopes });
+    return google.sheets({ version: 'v4', auth });
+  }
+  // 向后兼容：config 传字符串（keyFile 路径）或对象带 keyFile 字段
+  // 路径相对于运行命令的项目根目录（process.cwd()）解析
+  const rawKeyFile = typeof config === 'string' ? config : config?.keyFile;
+  const keyFile = rawKeyFile
+    ? (path.isAbsolute(rawKeyFile) ? rawKeyFile : path.join(process.cwd(), rawKeyFile))
+    : path.join(process.cwd(), 'service-account.json');
+  if (!fs.existsSync(keyFile)) {
+    throw new Error(
+      `找不到 Google 凭证：请设置环境变量 LOCALE_SYNC_CREDENTIALS，\n` +
+      `或将 service-account.json 放在项目根目录（${process.cwd()}），\n` +
+      `或运行 locale-sync init 进行配置。`
+    );
+  }
+  const auth = new google.auth.GoogleAuth({ keyFile, scopes });
+  return google.sheets({ version: 'v4', auth });
+}
+
+async function ensureMetadataColumns(sheets, spreadsheetId, sheetName, baseHeaders = null) {
+  const meta = await sheets.spreadsheets.get({ spreadsheetId, fields: 'sheets(properties(title))' });
+  const exists = meta.data.sheets.some(s => s.properties.title === sheetName);
+  if (!exists) {
+    await sheets.spreadsheets.batchUpdate({
+      spreadsheetId,
+      requestBody: { requests: [{ addSheet: { properties: { title: sheetName } } }] }
+    });
+  }
+
+  const headersRes = await sheets.spreadsheets.values.get({ spreadsheetId, range: `${sheetName}!1:1` });
+  const headers = headersRes.data.values?.[0] || [];
+
+  // 空 sheet 且传入了基础列定义时，自动初始化完整 header 行（含元数据列）
+  if (headers.length === 0) {
+    if (!baseHeaders || baseHeaders.length === 0) return;
+    const fullHeaders = [...baseHeaders, '_lastSyncBy', '_lastSyncAt'];
+    await sheets.spreadsheets.values.update({
+      spreadsheetId,
+      range: `${sheetName}!A1`,
+      valueInputOption: 'RAW',
+      requestBody: { values: [fullHeaders] }
+    });
+    return;
+  }
+
+  const normalizedHeaders = headers.map(h => h.toLowerCase().replace(/[-_]/g, ''));
+  const missing = [
+    { col: '_lastSyncBy', norm: 'lastsyncby' },
+    { col: '_lastSyncAt', norm: 'lastsyncat' }
+  ].filter(({ norm }) => !normalizedHeaders.includes(norm)).map(({ col }) => col);
+
+  if (missing.length) {
+    const startCol = columnIndexToLetter(headers.length);
+    await sheets.spreadsheets.values.update({
+      spreadsheetId,
+      range: `${sheetName}!${startCol}1`,
+      valueInputOption: 'RAW',
+      requestBody: { values: [missing] }
+    });
+  }
+}
+
+async function readSheet(sheets, spreadsheetId, sheetName) {
+  const range = `${sheetName}!A:ZZ`;
+  const [valuesRes, formatRes] = await Promise.all([
+    sheets.spreadsheets.values.get({ spreadsheetId, range, valueRenderOption: 'UNFORMATTED_VALUE' }),
+    sheets.spreadsheets.get({ spreadsheetId, ranges: [range], fields: 'sheets(properties(title,sheetId),data(rowData(values(userEnteredFormat.backgroundColor))))' })
+  ]);
+
+  const rows = valuesRes.data.values || [];
+  const matchedSheet = formatRes.data.sheets?.find(s => s.properties?.title === sheetName);
+  const actualSheetId = matchedSheet?.properties?.sheetId ?? 0;
+  const headers = rows[0] || [];
+  const headerMap = headers.map((h, i) => ({ key: h.toLowerCase().replace(/[-_]/g, ''), index: i }));
+  const rowData = matchedSheet?.data?.[0]?.rowData || [];
+
+  // 即使没有数据行，也把 headers 和 sheetId 附到返回数组上，供 push 新增行时使用
+  const result = rows.slice(1).map((row, rIdx) => {
+    const entry = { _headers: headers, _sheetId: actualSheetId };
+    headerMap.forEach(({ key, index }) => {
+      entry[key] = row[index] || '';
+    });
+    const rowCells = rowData[rIdx + 1]?.values || [];
+    // 按列独立读取颜色，存入 _colors map（key 为归一化列名）
+    const colors = {};
+    headerMap.forEach(({ key, index }) => {
+      const fmt = rowCells[index]?.userEnteredFormat?.backgroundColor;
+      colors[key] = fmt ? rgbToColorName(fmt) : 'none';
+    });
+    entry._colors = colors;
+    entry._color = colors[headerMap[0]?.key] || 'none'; // 行级颜色（向后兼容）
+    entry._rowIndex = rIdx + 2;
+    return entry;
+  });
+  result.headers = headers;
+  result.sheetId = actualSheetId;
+  return result;
+}
+
+function rgbToColorName(rgb) {
+  if (!rgb) return 'none';
+  if (rgb.red > 0.6 && rgb.green > 0.9 && rgb.blue > 0.6) return 'green';
+  if (rgb.red > 0.9 && rgb.green > 0.9 && rgb.blue > 0.6) return 'yellow';
+  if (rgb.red > 0.9 && rgb.green < 0.8 && rgb.blue < 0.8) return 'red';
+  if (rgb.red > 0.8 && rgb.green > 0.8 && rgb.blue > 0.8) return 'gray';
+  return 'none';
+}
+
+function colorToRGB(name) {
+  const map = {
+    green: { red: 0.7, green: 1, blue: 0.7 },
+    yellow: { red: 1, green: 1, blue: 0.7 },
+    red: { red: 1, green: 0.7, blue: 0.7 },
+    gray: { red: 0.9, green: 0.9, blue: 0.9 }
+  };
+  return map[name] || { red: 1, green: 1, blue: 1 };
+}
+
+/**
+ * 返回两类格式化请求：
+ *  1. 冻结首行
+ *  2. 首行高度 = 普通行 2 倍（42 px）
+ *  3. 首行：青色背景 + 粗体 + 居中
+ *  4. 数据区（row 1+）：水平/垂直居中 + 自动换行
+ */
+function buildSheetFormatRequests(sheetId) {
+  const CYAN = { red: 0.0, green: 0.8, blue: 0.8 };
+  return [
+    // 1. 冻结首行
+    {
+      updateSheetProperties: {
+        properties: { sheetId, gridProperties: { frozenRowCount: 1 } },
+        fields: 'gridProperties.frozenRowCount'
+      }
+    },
+    // 2. 首行高度 42 px（普通行约 21 px 的 2 倍）
+    {
+      updateDimensionProperties: {
+        range: { sheetId, dimension: 'ROWS', startIndex: 0, endIndex: 1 },
+        properties: { pixelSize: 42 },
+        fields: 'pixelSize'
+      }
+    },
+    // 3. 首行：青色背景 + 粗体 + 水平/垂直居中 + 换行
+    {
+      repeatCell: {
+        range: { sheetId, startRowIndex: 0, endRowIndex: 1 },
+        cell: {
+          userEnteredFormat: {
+            backgroundColor: CYAN,
+            textFormat: { bold: true },
+            horizontalAlignment: 'CENTER',
+            verticalAlignment: 'MIDDLE',
+            wrapStrategy: 'WRAP'
+          }
+        },
+        fields: 'userEnteredFormat(backgroundColor,textFormat.bold,horizontalAlignment,verticalAlignment,wrapStrategy)'
+      }
+    },
+    // 4. 数据区（row 1 起）：水平/垂直居中 + 换行
+    {
+      repeatCell: {
+        range: { sheetId, startRowIndex: 1 },
+        cell: {
+          userEnteredFormat: {
+            horizontalAlignment: 'CENTER',
+            verticalAlignment: 'MIDDLE',
+            wrapStrategy: 'WRAP'
+          }
+        },
+        fields: 'userEnteredFormat(horizontalAlignment,verticalAlignment,wrapStrategy)'
+      }
+    }
+  ];
+}
+
+async function batchWrite(sheets, spreadsheetId, requests) {
+  if (requests.length === 0) return;
+  const chunks = [];
+  for (let i = 0; i < requests.length; i += BATCH_LIMIT) chunks.push(requests.slice(i, i + BATCH_LIMIT));
+
+  for (const chunk of chunks) {
+    await pRetry(
+      async () => sheets.spreadsheets.batchUpdate({ spreadsheetId, requestBody: { requests: chunk } }),
+      { retries: 3, onFailedAttempt: () => {} }
+    );
+  }
+}
+
+module.exports = { getClient, ensureMetadataColumns, readSheet, batchWrite, colorToRGB, rgbToColorName, BATCH_LIMIT, buildSheetFormatRequests };

package/lib/io/localFs/astUpdater.js

@@ -0,0 +1,198 @@
+const fs = require('fs').promises;
+const path = require('path');
+const recast = require('recast');
+const babelParser = require('recast/parsers/babel');
+const { default: traverse } = require('@babel/traverse');
+const t = require('@babel/types');
+
+function buildKeyPath(nodePath) {
+  const segments = [];
+  let curr = nodePath;
+  while (curr) {
+    const node = curr.node;
+    const parentPath = curr.parentPath;
+    if (t.isObjectProperty(node) || t.isObjectMethod(node)) {
+      const k = node.key.name != null ? node.key.name : node.key.value;
+      if (k != null) segments.unshift(String(k));
+    }
+    // 当前节点在数组中：插入其索引
+    if (parentPath && t.isArrayExpression(parentPath.node)) {
+      const idx = parentPath.node.elements.indexOf(node);
+      if (idx >= 0) segments.unshift(String(idx));
+    }
+    if (!parentPath || t.isExportDefaultDeclaration(node) || t.isAssignmentExpression(node) || t.isFile(node)) break;
+    curr = parentPath;
+  }
+  return segments.join('.');
+}
+
+/**
+ * 将 TemplateLiteral AST 节点序列化为带 ${...} 占位符的字符串
+ * 例: `list3${process.env.common}action start!` → "list3${process.env.common}action start!"
+ */
+function serializeTemplateLiteral(node) {
+  let val = '';
+  for (let i = 0; i < node.quasis.length; i++) {
+    val += node.quasis[i].value.cooked || '';
+    if (i < node.expressions.length) {
+      val += '${' + recast.print(node.expressions[i]).code + '}';
+    }
+  }
+  return val;
+}
+
+/**
+ * 将字符串值回填到 TemplateLiteral AST 节点的 quasis
+ * 按原始 expression 源码作为分隔符拆分，逐段更新 quasis
+ */
+function applyToTemplateLiteral(tlNode, newValue) {
+  if (tlNode.expressions.length === 0) {
+    if (tlNode.quasis[0]) {
+      tlNode.quasis[0].value.raw = newValue;
+      tlNode.quasis[0].value.cooked = newValue;
+    }
+    return;
+  }
+  const exprSources = tlNode.expressions.map(e => recast.print(e).code);
+  let remaining = newValue;
+  const parts = [];
+  for (const exprSrc of exprSources) {
+    const placeholder = '${' + exprSrc + '}';
+    const idx = remaining.indexOf(placeholder);
+    if (idx === -1) {
+      // 占位符缺失（用户删除了表达式）：全部写入第一个 quasi，其余置空
+      if (tlNode.quasis[0]) {
+        tlNode.quasis[0].value.raw = newValue;
+        tlNode.quasis[0].value.cooked = newValue;
+      }
+      for (let i = 1; i < tlNode.quasis.length; i++) {
+        tlNode.quasis[i].value.raw = '';
+        tlNode.quasis[i].value.cooked = '';
+      }
+      return;
+    }
+    parts.push(remaining.slice(0, idx));
+    remaining = remaining.slice(idx + placeholder.length);
+  }
+  parts.push(remaining);
+  for (let i = 0; i < parts.length; i++) {
+    if (tlNode.quasis[i]) {
+      tlNode.quasis[i].value.raw = parts[i];
+      tlNode.quasis[i].value.cooked = parts[i];
+    }
+  }
+}
+
+// 按 dot-path 设置嵌套对象的值
+function setNestedValue(obj, keyPath, value) {
+  const keys = keyPath.split('.');
+  let cur = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (cur[keys[i]] == null || typeof cur[keys[i]] !== 'object') return false;
+    cur = cur[keys[i]];
+  }
+  const last = keys[keys.length - 1];
+  if (!(last in cur)) return false;
+  cur[last] = value;
+  return true;
+}
+
+async function applyJsonFileUpdates(filePath, updates, dryRun, results) {
+  const CommentJSON = require('comment-json');
+  const content = await fs.readFile(filePath, 'utf8');
+  const data = CommentJSON.parse(content);
+  let modified = false;
+  for (const u of updates) {
+    if (setNestedValue(data, u.key, u.newValue)) modified = true;
+  }
+  if (modified && !dryRun) {
+    await fs.writeFile(filePath, CommentJSON.stringify(data, null, 2), 'utf8');
+  }
+  if (modified) results.updated++;
+}
+
+async function applyYamlFileUpdates(filePath, updates, dryRun, results) {
+  const yaml = require('js-yaml');
+  const content = await fs.readFile(filePath, 'utf8');
+  const data = yaml.load(content);
+  let modified = false;
+  for (const u of updates) {
+    if (setNestedValue(data, u.key, u.newValue)) modified = true;
+  }
+  if (modified && !dryRun) {
+    await fs.writeFile(filePath, yaml.dump(data, { lineWidth: -1, noRefs: true }), 'utf8');
+  }
+  if (modified) results.updated++;
+}
+
+async function applyJsAstFileUpdates(filePath, updates, dryRun, results) {
+  const content = await fs.readFile(filePath, 'utf8');
+  const ast = recast.parse(content, { parser: babelParser });
+  let modified = false;
+
+  traverse(ast, {
+    ObjectProperty(nodePath) {
+      if (!t.isStringLiteral(nodePath.node.value) && !t.isTemplateLiteral(nodePath.node.value)) return;
+      const keyPath = buildKeyPath(nodePath);
+      const update = updates.find(u => u.key === keyPath);
+      if (!update) return;
+      const newVal = update.newValue;
+      if (t.isStringLiteral(nodePath.node.value)) {
+        nodePath.node.value.value = newVal;
+      } else if (t.isTemplateLiteral(nodePath.node.value)) {
+        applyToTemplateLiteral(nodePath.node.value, newVal);
+      }
+      modified = true;
+    },
+    // 数组元素（StringLiteral）
+    StringLiteral(nodePath) {
+      if (!t.isArrayExpression(nodePath.parentPath?.node)) return;
+      const keyPath = buildKeyPath(nodePath);
+      const update = updates.find(u => u.key === keyPath);
+      if (!update) return;
+      nodePath.node.value = update.newValue;
+      modified = true;
+    },
+    // 数组元素（TemplateLiteral，原样按 ${...} 分段回填）
+    TemplateLiteral(nodePath) {
+      if (!t.isArrayExpression(nodePath.parentPath?.node)) return;
+      const keyPath = buildKeyPath(nodePath);
+      const update = updates.find(u => u.key === keyPath);
+      if (!update) return;
+      applyToTemplateLiteral(nodePath.node, update.newValue);
+      modified = true;
+    }
+  });
+
+  if (modified && !dryRun) {
+    const output = recast.print(ast, { quote: 'single', trailingComma: true, tabWidth: 2 }).code;
+    await fs.writeFile(filePath, output, 'utf8');
+  }
+  if (modified) results.updated++;
+}
+
+async function applyAstUpdates(plan, dryRun) {
+  const results = { updated: 0, warnings: [] };
+  const fileGroups = plan.reduce((acc, u) => {
+    (acc[u.filePath] = acc[u.filePath] || []).push(u);
+    return acc;
+  }, {});
+
+  for (const [filePath, updates] of Object.entries(fileGroups)) {
+    const ext = path.extname(filePath).toLowerCase();
+    try {
+      if (ext === '.json') {
+        await applyJsonFileUpdates(filePath, updates, dryRun, results);
+      } else if (ext === '.yaml' || ext === '.yml') {
+        await applyYamlFileUpdates(filePath, updates, dryRun, results);
+      } else {
+        await applyJsAstFileUpdates(filePath, updates, dryRun, results);
+      }
+    } catch (err) {
+      results.warnings.push(`[UPDATE_ERROR] ${filePath}: ${err.message}`);
+    }
+  }
+  return results;
+}
+
+module.exports = { applyAstUpdates, buildKeyPath, serializeTemplateLiteral };

package/lib/io/localFs/scanner.js

@@ -0,0 +1,242 @@
+const fastGlob = require('fast-glob');
+const path = require('path');
+const fs = require('fs').promises;
+const { parse } = require('recast');
+const babelParser = require('recast/parsers/babel');
+const { default: traverse } = require('@babel/traverse');
+const t = require('@babel/types');
+const { buildKeyPath, serializeTemplateLiteral } = require('./astUpdater');
+const { normalizeForAnchor } = require('../../core/utils/stringNormalizer');
+
+// 匹配 locale 代码：en, zh, enUS, arAE, en-US, zh_CN 等
+const LOCALE_RE = /^[a-z]{2,3}([A-Z]{2,3}|[-_][a-zA-Z]{2,3})?$/;
+
+async function scanLocales(localesDirs, ignore = []) {
+  const map = {};
+  const dirs = Array.isArray(localesDirs) ? localesDirs : [localesDirs];
+
+  // 将用户配置的忽略规则规范化为 fast-glob 兼容的 glob 模式
+  // - 无点无斜线 → 文件夹名：node_modules → **/node_modules/**
+  // - 有点无斜线 → 文件名或扩展：*.d.ts / index.js → **/*.d.ts
+  // - 含斜线 → 项目根目录相对路径，转为相对于 locales 目录的路径后再套用上述规则
+  const toGlob = (t) => {
+    if (t.startsWith('*')) return [`**/${t}`];
+    if (t.includes('.')) return [`**/${t}`];
+    return [`**/${t}/**`, `**/${t}`];
+  };
+  const resolveIgnore = (resolvedDir) => (Array.isArray(ignore) ? ignore : []).flatMap(p => {
+    if (!p || typeof p !== 'string') return [];
+    const t = p.trim();
+    if (!t) return [];
+    if (t.includes('/')) {
+      const abs = path.resolve(t);
+      const rel = path.relative(resolvedDir, abs);
+      return rel.startsWith('..') ? [t] : toGlob(rel);
+    }
+    return toGlob(t);
+  });
+
+  for (const dir of dirs) {
+    // 将配置路径解析为绝对路径，以便正确计算相对路径
+    const resolvedDir = path.isAbsolute(dir) ? dir : path.resolve(dir);
+    let files;
+    try {
+      files = await fastGlob(['**/*.{js,json,yaml,yml}'], { cwd: resolvedDir, absolute: true, ignore: resolveIgnore(resolvedDir) });
+    } catch (e) {
+      console.warn(`[SCAN WARN] Cannot scan dir: ${dir}`, e.message);
+      continue;
+    }
+
+    for (const file of files) {
+      // locale 检测策略（优先级）：
+      // 1. 文件名（原始，未规范化）是合法 locale 代码（ar-SA.js → 'arsa'，en-US.js → 'enus'）
+      // 2. 任意目录层级（由浅到深）名称是合法 locale 代码（en-US/common.js 或 oom/en-US/common.js → 'enus'）
+      // 3. 都不是 → 使用规范化后的文件名（多 locale 文件由 multi-locale 检测覆盖）
+      const relPath = path.relative(resolvedDir, file);
+      const relParts = relPath.split(path.sep);
+      const rawFileBase = path.basename(file, path.extname(file));
+      const fileBase = rawFileBase.toLowerCase().replace(/[-_]/g, '');
+      const dirParts = relParts.slice(0, -1); // 所有目录层级，不含文件名
+      const rawLocaleDir = dirParts.find(p => LOCALE_RE.test(p)) ?? null;
+      const localeDirNorm = rawLocaleDir ? rawLocaleDir.toLowerCase().replace(/[-_]/g, '') : null;
+      const locale = LOCALE_RE.test(rawFileBase)
+        ? fileBase
+        : (rawLocaleDir ? localeDirNorm : fileBase);
+
+      const ext = path.extname(file).toLowerCase();
+      const entry = { filePath: file, keyMap: {}, values: {} };
+      let multiLocaleHandled = false;
+
+      if (ext === '.json') {
+        try {
+          const CommentJSON = require('comment-json');
+          const content = await fs.readFile(file, 'utf8');
+          const data = CommentJSON.parse(content);
+          if (isMultiLocaleObject(data)) {
+            mergeMultiLocale(data, file, map);
+            multiLocaleHandled = true;
+          } else {
+            flattenObj(data, '', entry);
+          }
+        } catch (e) { console.error(`[SCAN JSON ERROR] ${file}:`, e.message); }
+      } else if (ext === '.yaml' || ext === '.yml') {
+        try {
+          const yaml = require('js-yaml');
+          const content = await fs.readFile(file, 'utf8');
+          const data = yaml.load(content);
+          if (data && typeof data === 'object') {
+            if (isMultiLocaleObject(data)) {
+              mergeMultiLocale(data, file, map);
+              multiLocaleHandled = true;
+            } else {
+              flattenObj(data, '', entry);
+            }
+          }
+        } catch (e) { console.error(`[SCAN YAML ERROR] ${file}:`, e.message); }
+      } else {
+        try {
+          const content = await fs.readFile(file, 'utf8');
+          const ast = parse(content, { parser: babelParser });
+          traverse(ast, {
+            ObjectProperty(path) {
+              if (t.isStringLiteral(path.node.value) || t.isTemplateLiteral(path.node.value)) {
+                const kp = buildKeyPath(path);
+                if (!kp) return;
+                let val = '';
+                if (t.isStringLiteral(path.node.value)) val = path.node.value.value;
+                else val = serializeTemplateLiteral(path.node.value);
+                entry.keyMap[kp] = kp;
+                entry.values[kp] = val;
+              }
+            },
+            // 数组元素：字符串字面量
+            StringLiteral(path) {
+              if (!t.isArrayExpression(path.parentPath?.node)) return;
+              const kp = buildKeyPath(path);
+              if (!kp) return;
+              entry.keyMap[kp] = kp;
+              entry.values[kp] = path.node.value;
+            },
+            // 数组元素：模板字面量（原样序列化含 ${...} 占位符）
+            TemplateLiteral(path) {
+              if (!t.isArrayExpression(path.parentPath?.node)) return;
+              const kp = buildKeyPath(path);
+              if (!kp) return;
+              entry.keyMap[kp] = kp;
+              entry.values[kp] = serializeTemplateLiteral(path.node);
+            }
+          });
+          // JS 文件：检测多 locale 合体格式（顶层 key 均为 locale 代码）
+          const topKeys = [...new Set(Object.keys(entry.values).map(k => k.split('.')[0]))];
+          if (topKeys.length > 0 && topKeys.every(k => LOCALE_RE.test(k))) {
+            mergeMultiLocaleFlat(entry, topKeys, file, map);
+            multiLocaleHandled = true;
+          }
+        } catch (e) { console.error(`[SCAN AST ERROR] ${file}:`, e.message); }
+      }
+
+      if (!multiLocaleHandled) {
+        // 为每个 key 记录所在文件（多文件 locale 回填时精确定位）
+        entry.filePaths = {};
+        for (const key of Object.keys(entry.values)) {
+          entry.filePaths[key] = file;
+        }
+        if (map[locale]) {
+          Object.assign(map[locale].keyMap, entry.keyMap);
+          Object.assign(map[locale].values, entry.values);
+          Object.assign(map[locale].filePaths, entry.filePaths);
+        } else {
+          map[locale] = entry;
+        }
+      }
+    }
+  }
+  return map;
+}
+
+function flattenObj(obj, prefix, target) {
+  const entries = Array.isArray(obj)
+    ? obj.map((v, i) => [String(i), v])
+    : Object.entries(obj);
+  for (const [k, v] of entries) {
+    const newKey = prefix ? `${prefix}.${k}` : k;
+    if (v !== null && typeof v === 'object') {
+      flattenObj(v, newKey, target);
+    } else {
+      target.keyMap[newKey] = newKey;
+      target.values[newKey] = String(v ?? '');
+    }
+  }
+}
+
+/** 判断 JSON/YAML 对象是否为"单文件多 locale"格式（顶层 key 均为 locale 代码） */
+function isMultiLocaleObject(obj) {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return false;
+  const keys = Object.keys(obj);
+  return keys.length > 0 && keys.every(k => LOCALE_RE.test(k));
+}
+
+/** 将 JSON/YAML 多 locale 对象拆分后合并到 map */
+function mergeMultiLocale(data, file, map) {
+  for (const [localeKey, content] of Object.entries(data)) {
+    if (!content || typeof content !== 'object') continue;
+    const locale = localeKey.toLowerCase().replace(/[-_]/g, '');
+    const subEntry = { filePath: file, keyMap: {}, values: {}, filePaths: {} };
+    flattenObjMulti(content, '', localeKey, subEntry, file);
+    if (map[locale]) {
+      Object.assign(map[locale].keyMap, subEntry.keyMap);
+      Object.assign(map[locale].values, subEntry.values);
+      Object.assign(map[locale].filePaths, subEntry.filePaths);
+    } else {
+      map[locale] = subEntry;
+    }
+  }
+}
+
+/**
+ * flattenObj 变体：keyMap 存储带 locale 前缀的完整写回路径
+ * 例: enUS.name → values['name'] = 'wang', keyMap['name'] = 'enUS.name'
+ */
+function flattenObjMulti(obj, prefix, localeKey, target, file) {
+  const entries = Array.isArray(obj)
+    ? obj.map((v, i) => [String(i), v])
+    : Object.entries(obj);
+  for (const [k, v] of entries) {
+    const logicalKey = prefix ? `${prefix}.${k}` : k;
+    if (v !== null && typeof v === 'object') {
+      flattenObjMulti(v, logicalKey, localeKey, target, file);
+    } else {
+      target.keyMap[logicalKey] = `${localeKey}.${logicalKey}`; // 写回路径含 locale 前缀
+      target.values[logicalKey] = String(v ?? '');
+      target.filePaths[logicalKey] = file;
+    }
+  }
+}
+
+/** 将多 locale JS AST 结果（含 locale 前缀的 key）按 locale 拆分合并 */
+function mergeMultiLocaleFlat(entry, topKeys, file, map) {
+  for (const lk of topKeys) {
+    const prefix = lk + '.';
+    const subEntry = { filePath: file, keyMap: {}, values: {}, filePaths: {} };
+    for (const [k, v] of Object.entries(entry.values)) {
+      if (k.startsWith(prefix)) {
+        const logicalKey = k.slice(prefix.length);
+        subEntry.keyMap[logicalKey] = k;  // 写回时用完整 key（含 locale 前缀）
+        subEntry.values[logicalKey] = v;
+        subEntry.filePaths[logicalKey] = file;
+      }
+    }
+    const locale = lk.toLowerCase().replace(/[-_]/g, '');
+    if (Object.keys(subEntry.values).length > 0) {
+      if (map[locale]) {
+        Object.assign(map[locale].keyMap, subEntry.keyMap);
+        Object.assign(map[locale].values, subEntry.values);
+        Object.assign(map[locale].filePaths, subEntry.filePaths);
+      } else {
+        map[locale] = subEntry;
+      }
+    }
+  }
+}
+
+module.exports = { scanLocales };