locale-sync-cli 1.0.0

package/lib/core/engines/pullEngine.js

@@ -0,0 +1,160 @@
+const { normalizeForAnchor } = require('../utils/stringNormalizer');
+const { checkPlaceholderConsistency } = require('../utils/placeholderChecker');
+
+/**
+ * 优先级链（按列颜色独立判定）：
+ * 项目(⬜/🟢非空) > Common(⬜/🟢非空) > 项目(🟡) > Common(🟡) > 主动清空(空+有色) > 保留本地
+ */
+async function generatePullPlan(projectRows, commonRows, localMap, config) {
+  const plan = [];
+  const normH         = h => h.toLowerCase().replace(/[-_]/g, '');
+  const getLocaleBase  = loc => loc.length <= 3 ? loc : loc.slice(0, 2);
+  const isEnLoc        = loc => getLocaleBase(loc) === 'en';
+  // 查找行对象中 en 系列列（en/enus/en-US）的英文值（兼容新旧表头格式）
+  const getEnValue = r => {
+    if (!r) return '';
+    for (const [k, v] of Object.entries(r)) {
+      if (k.startsWith('_')) continue;
+      if (typeof v === 'string' && v.trim() && isEnLoc(k)) return v;
+    }
+    return '';
+  };
+
+  // 构建 Common 索引（en 锚点 → 行）
+  const commonByEn = new Map();
+  for (const r of commonRows) {
+    const anchor = normalizeForAnchor(getEnValue(r));
+    if (anchor) commonByEn.set(anchor, r);
+  }
+
+  const processedAnchors = new Set();
+
+  // ── 第一轮：处理项目表行 ──────────────────────────────────────
+  for (const projRow of projectRows) {
+    // 防环路：忽略 < antiLoopWindow 秒内来自 Push 的行
+    if (projRow.lastsyncby === 'push' && projRow.lastsyncat) {
+      const diff = (Date.now() - new Date(projRow.lastsyncat).getTime()) / 1000;
+      if (diff < config.sync.antiLoopWindow) continue;
+    }
+    // 灰色行整行跳过
+    if (projRow._color === 'gray') continue;
+
+    const enAnchor = normalizeForAnchor(getEnValue(projRow));
+    if (!enAnchor) continue;
+    processedAnchors.add(enAnchor);
+
+    const commonRow = commonByEn.get(enAnchor);
+    const localKey  = projRow.key || null;
+
+    for (const [localeKey, localEntry] of Object.entries(localMap)) {
+      if (isEnLoc(localeKey)) continue;
+      if (!localKey || !(localKey in localEntry.values)) continue;
+
+      const localValue = localEntry.values[localKey];
+      const base       = getLocaleBase(localeKey);
+
+      // 兼容新格式列名（arsa←ar-SA）和旧格式（ar）
+      const projColor = projRow._colors?.[localeKey] ?? projRow._colors?.[base] ?? 'none';
+      const projVal   = projRow[localeKey] ?? projRow[base] ?? '';
+      const commColor = commonRow ? (commonRow._colors?.[localeKey] ?? commonRow._colors?.[base] ?? 'none') : null;
+      const commVal   = commonRow ? (commonRow[localeKey] ?? commonRow[base] ?? '') : null;
+
+      let finalValue;
+      let warnYellow = false;
+
+      if (projVal !== '') {
+        // 项目表有值 → 永远最高优先级（不论颜色）
+        finalValue = projVal;
+        warnYellow = projColor === 'yellow';
+      } else if (projVal === '' && projColor !== 'none') {
+        // 项目表主动清空（空+有色）
+        finalValue = '';
+      } else if (commonRow && commVal !== '') {
+        // Common 有值 → 次优先级
+        finalValue = commVal;
+        if (commColor === 'yellow') warnYellow = true;
+      } else if (commonRow && commVal === '' && commColor !== null && commColor !== 'none') {
+        // Common 主动清空
+        finalValue = '';
+      }
+      // else: 保留本地
+
+      if (finalValue !== undefined && finalValue !== localValue) {
+        plan.push({
+          filePath: localEntry.filePaths?.[localKey] || localEntry.filePath,
+          key: localEntry.keyMap?.[localKey] || localKey,
+          oldValue: localValue,
+          newValue: finalValue,
+          locale: localeKey,
+          warnings: [
+            ...checkPlaceholderConsistency(getEnValue(projRow), { [localeKey]: finalValue }),
+            ...(warnYellow ? [`[${localeKey}] 来源为黄色单元格（待人工确认）`] : [])
+          ]
+        });
+      }
+    }
+  }
+
+  // ── 第二轮：处理 Common 表中未被项目表覆盖的行 ───────────────
+  const enEntry = Object.entries(localMap).find(([k]) => isEnLoc(k))?.[1];
+  for (const commonRow of commonRows) {
+    const enAnchor = normalizeForAnchor(getEnValue(commonRow));
+    if (!enAnchor || processedAnchors.has(enAnchor)) continue;
+
+    if (commonRow.lastsyncby === 'push' && commonRow.lastsyncat) {
+      const diff = (Date.now() - new Date(commonRow.lastsyncat).getTime()) / 1000;
+      if (diff < config.sync.antiLoopWindow) continue;
+    }
+    if (commonRow._color === 'gray') continue;
+
+    for (const [localeKey, localEntry] of Object.entries(localMap)) {
+      if (isEnLoc(localeKey)) continue;
+
+      let localKey;
+      if (enEntry) {
+        localKey = Object.keys(enEntry.values).find(
+          k => normalizeForAnchor(enEntry.values[k]) === enAnchor
+        );
+      } else {
+        localKey = Object.keys(localEntry.values).find(
+          k => normalizeForAnchor(localEntry.values[k]) === enAnchor
+        );
+      }
+      if (!localKey || !(localKey in localEntry.values)) continue;
+
+      const localValue = localEntry.values[localKey];
+      const base       = getLocaleBase(localeKey);
+      const cellColor  = commonRow._colors?.[localeKey] ?? commonRow._colors?.[base] ?? 'none';
+      const cellVal    = commonRow[localeKey] ?? commonRow[base] ?? '';
+      let finalValue;
+      let warnYellow = false;
+
+      if (['none', 'green'].includes(cellColor) && cellVal !== '') {
+        finalValue = cellVal;
+      } else if (cellColor === 'yellow') {
+        finalValue = cellVal;
+        warnYellow = true;
+      } else if (cellVal === '' && cellColor !== 'none') {
+        finalValue = '';
+      }
+
+      if (finalValue !== undefined && finalValue !== localValue) {
+        plan.push({
+          filePath: localEntry.filePaths?.[localKey] || localEntry.filePath,
+          key: localKey,
+          oldValue: localValue,
+          newValue: finalValue,
+          locale: localeKey,
+          warnings: [
+            ...checkPlaceholderConsistency(getEnValue(commonRow), { [localeKey]: finalValue }),
+            ...(warnYellow ? [`[${localeKey}] 来源为黄色单元格（待人工确认）`] : [])
+          ]
+        });
+      }
+    }
+  }
+
+  return plan;
+}
+
+module.exports = { generatePullPlan };

package/lib/core/engines/pushEngine.js

@@ -0,0 +1,367 @@
+const path = require('path');
+const { normalizeForAnchor } = require('../utils/stringNormalizer');
+const { colorToRGB } = require('../../io/googleSheets');
+
+// 前置校验：拦截公式注入与非法控制字符
+function validateValue(val, key, locale) {
+  if (typeof val !== 'string') return;
+  if (val.startsWith('=')) {
+    throw new Error(`[Formula Injection] Key "${key}" [${locale}] 值以 "=" 开头，已拒绝写入`);
+  }
+  if (/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/.test(val)) {
+    throw new Error(`[Control Char] Key "${key}" [${locale}] 值包含非法控制字符，已拒绝写入`);
+  }
+}
+
+async function generatePushPlan(localItems, sheetData, config) {
+  const requests = [];
+  const {
+    projectHeaders = [],
+    projectSheetId = 0,
+    commonHeaders  = [],
+    commonSheetId  = 0
+  } = sheetData;
+
+  const normH         = h => h.toLowerCase().replace(/[-_]/g, '');
+  const getLocaleBase  = loc => loc.length <= 3 ? loc : loc.slice(0, 2);
+  const isEnCol        = hn => getLocaleBase(hn) === 'en'; // en / enus / en-US 归一化后均视为 en 列
+  const GREEN  = colorToRGB('green');
+  const YELLOW = colorToRGB('yellow');
+
+  // 构建新增行的单元格数组（appendCells 复用），bgColor 可传绿色或黄色
+  const buildRow = (hdrs, isProjectTable, rowItem, now, bgColor = GREEN) =>
+    hdrs.map(h => {
+      const hn = normH(h);
+      let val = '';
+      if (hn === 'key')             val = isProjectTable ? rowItem.key : '';
+      else if (hn === 'filepath')   val = isProjectTable ? path.relative(process.cwd(), rowItem.filePath) : '';
+      else if (isEnCol(hn))         val = rowItem.en;
+      else if (hn === 'lastsyncby') val = 'push';
+      else if (hn === 'lastsyncat') val = now;
+      else {
+        val = rowItem.translations[hn] || '';
+        validateValue(val, rowItem.key, hn);
+      }
+      const isTransCol = !['key', 'filepath', 'lastsyncby', 'lastsyncat'].includes(hn);
+      const cell = { userEnteredValue: { stringValue: (val == null ? '' : String(val)) } };
+      cell.userEnteredFormat = { wrapStrategy: 'WRAP', horizontalAlignment: 'CENTER', verticalAlignment: 'MIDDLE' };
+      if (isTransCol && val) cell.userEnteredFormat.backgroundColor = bgColor;
+      return cell;
+    });
+
+  // 构建冲突行：仅含冲突 locale（黄色） + en/key/filepath 元信息，其余 locale 留空
+  const buildConflictRow = (hdrs, rowItem, now, conflictMap) =>
+    hdrs.map(h => {
+      const hn = normH(h);
+      let val = '';
+      if (hn === 'key')             val = rowItem.key;
+      else if (hn === 'filepath')   val = path.relative(process.cwd(), rowItem.filePath);
+      else if (isEnCol(hn))         val = rowItem.en;
+      else if (hn === 'lastsyncby') val = 'push';
+      else if (hn === 'lastsyncat') val = now;
+      else if (conflictMap.has(hn)) val = conflictMap.get(hn);
+      // 其他 locale → 留空（已在 common 行填充）
+
+      const cell = { userEnteredValue: { stringValue: (val == null ? '' : String(val)) } };
+      cell.userEnteredFormat = { wrapStrategy: 'WRAP', horizontalAlignment: 'CENTER', verticalAlignment: 'MIDDLE' };
+      if (val) {
+        if (conflictMap.has(hn)) {
+          cell.userEnteredFormat.backgroundColor = YELLOW;   // 冲突 locale → 黄色
+        } else if (!['key', 'filepath', 'lastsyncby', 'lastsyncat'].includes(hn)) {
+          cell.userEnteredFormat.backgroundColor = GREEN;    // en 等内容列 → 绿色
+        }
+      }
+      return cell;
+    });
+
+  // locale 列按表头顺序排列，用于 en 为空时的稳定备用锚点
+  // locale 列按表头顺序排列（排除 en 系列和元数据列），用于无 en 时的稳定备用锚点
+  const localeColOrder = commonHeaders
+    .map(h => h.toLowerCase().replace(/[-_]/g, ''))
+    .filter(h => !['key', 'filepath', 'lastsyncby', 'lastsyncat'].includes(h) && getLocaleBase(h) !== 'en');
+
+  // 在 readSheet 行对象中查找 en 系列列（en / en-US / enus 等）的英文文本
+  const getEnValue = r => {
+    for (const [k, v] of Object.entries(r)) {
+      if (k.startsWith('_')) continue;
+      if (typeof v === 'string' && v.trim() && isEnCol(k)) return v;
+    }
+    return '';
+  };
+
+  // en 为空时：按表头 locale 列顺序找第一个非空翻译值作为锚点
+  const noEnAnchor = valMap => {
+    for (const loc of localeColOrder) {
+      const v = valMap[loc];
+      if (typeof v === 'string' && v.trim()) return `__noen__${normalizeForAnchor(v)}`;
+    }
+    return null;
+  };
+
+  // 构建索引
+  const commonIndex = new Map();
+  sheetData.common.forEach(r => {
+    const enVal = getEnValue(r);
+    if (enVal) {
+      const anchor = normalizeForAnchor(enVal);
+      if (!commonIndex.has(anchor)) commonIndex.set(anchor, []);
+      commonIndex.get(anchor).push(r);
+    } else {
+      // en 为空：按 locale 列顺序取第一个非空翻译值作锚点
+      const anchor = noEnAnchor(r);
+      if (anchor) {
+        if (!commonIndex.has(anchor)) commonIndex.set(anchor, []);
+        commonIndex.get(anchor).push(r);
+      }
+      // key|filepath 兜底（项目表写入的行）
+      if (r.key || r.filepath) {
+        const keyAnchor = `__key__${r.key || ''}|${r.filepath || ''}`;
+        if (!commonIndex.has(keyAnchor)) commonIndex.set(keyAnchor, []);
+        commonIndex.get(keyAnchor).push(r);
+      }
+    }
+  });
+  const projectIndex = new Map();
+  // 兼容旧格式（绝对路径）和新格式（相对路径），统一转为相对路径作为索引 key
+  const toRelPath = p => (!p ? '' : path.isAbsolute(p) ? path.relative(process.cwd(), p) : p);
+  sheetData.project.forEach(r => projectIndex.set(`${r.key}|${toRelPath(r.filepath)}`, r));
+
+  // 新增行缓冲区：最终合并成单个 appendCells，避免 Google API 多请求上限
+  const newCommonRows    = [];
+  const newProjectRows   = [];
+  // 第一次 push 批内冲突检测：enAnchor → { item, rowIndex }
+  const pendingCommonMap = new Map();
+
+  const now = new Date().toISOString();
+
+  for (const item of localItems) {
+    // en 为空时：用同一套 locale 列顺序逻辑求备用锚点
+    let enAnchor;
+    if (item.en && item.en.trim()) {
+      enAnchor = normalizeForAnchor(item.en);
+    } else {
+      const normTrans = {};
+      for (const [k, v] of Object.entries(item.translations)) normTrans[normH(k)] = v;
+      enAnchor = noEnAnchor(normTrans) ?? `__key__${item.key}|${path.relative(process.cwd(), item.filePath)}`;
+    }
+    const pk = `${item.key}|${path.relative(process.cwd(), item.filePath)}`;
+    const projRow = projectIndex.get(pk);
+    const commonRows = commonIndex.get(enAnchor) || [];
+    const commonRow = commonRows[0];
+
+    let rowIdx, sheetId, headers, isProject = true;
+
+    if (projRow) {
+      // 防环路：忽略 < antiLoopWindow 秒内来自 Pull 的行
+      if (projRow.lastsyncby === 'pull' && projRow.lastsyncat) {
+        const diff = (Date.now() - new Date(projRow.lastsyncat).getTime()) / 1000;
+        if (diff < config.sync.antiLoopWindow) continue;
+      }
+      rowIdx  = projRow._rowIndex;
+      sheetId = projRow._sheetId ?? 0;
+      headers = projRow._headers;
+    } else if (commonRow) {
+      if (commonRow.lastsyncby === 'pull' && commonRow.lastsyncat) {
+        const diff = (Date.now() - new Date(commonRow.lastsyncat).getTime()) / 1000;
+        if (diff < config.sync.antiLoopWindow) continue;
+      }
+      rowIdx  = commonRow._rowIndex;
+      sheetId = commonRow._sheetId ?? 0;
+      headers = commonRow._headers;
+      isProject = false;
+    } else {
+      // ── 新增行：common / project 都不存在 ──
+      const hasContent = (item.en && item.en.trim() !== '') ||
+        Object.values(item.translations).some(v => typeof v === 'string' && v.trim() !== '');
+      if (!hasContent) continue;
+
+      if (commonHeaders.length > 0) {
+        const pending = pendingCommonMap.get(enAnchor);
+
+        if (pending) {
+          // 同英文锚点已在待写队列：冲突检测 + 非冲突 locale 合并入已排队行
+          const conflictMap = new Map();
+          const fillUpdates = {};
+
+          for (const [locale, val] of Object.entries(item.translations)) {
+            if (isEnCol(normH(locale))) continue;
+            const localeNorm = normH(locale);
+            if (!val || !val.trim()) continue;
+            const pendingVal = (pending.item.translations[localeNorm] ?? '').trim();
+            if (pendingVal && pendingVal !== val) {
+              conflictMap.set(localeNorm, val);
+            } else if (!pendingVal) {
+              fillUpdates[localeNorm] = val;
+            }
+          }
+
+          // 将新 locale 值合并入已排队的 common 行
+          if (Object.keys(fillUpdates).length > 0) {
+            const mergedItem = { ...pending.item, translations: { ...pending.item.translations, ...fillUpdates } };
+            newCommonRows[pending.rowIndex] = { values: buildRow(commonHeaders, false, mergedItem, now) };
+            pending.item = mergedItem;
+          }
+
+          if (conflictMap.size > 0 && projectHeaders.length > 0) {
+            newProjectRows.push({ values: buildConflictRow(projectHeaders, item, now, conflictMap) });
+          }
+        } else {
+          // 首次出现：写入 common，并记录到待写索引
+          pendingCommonMap.set(enAnchor, { item, rowIndex: newCommonRows.length });
+          newCommonRows.push({ values: buildRow(commonHeaders, false, item, now) });
+        }
+      }
+      continue;
+    }
+
+    // ── 更新已有行 ──────────────────────────────────────────────
+    // 检查 common 行是否为重复标记（同一翻译内容已在其他行）
+    if (!isProject && commonRow && commonRow._isDuplicateMarked) {
+      // 重复行：生成警告信息，但继续处理（可选择跳过或合并）
+      console.warn(`[WARN] Common表中发现重复翻译: key="${item.key}" en="${getEnValue(commonRow)}"，该行可能需要人工合并`);
+    }
+
+    // 检查是否与 common 行完全相同（所有 locale 都匹配）→ 完全重复则直接跳过
+    if (!isProject && commonRow) {
+      let isFullyMatched = true;
+      for (const [locale, val] of Object.entries(item.translations)) {
+        if (isEnCol(normH(locale))) continue;
+        const localeNorm = normH(locale);
+        const itemVal = (val || '').trim();
+        const commonVal = (commonRow[localeNorm] || '').trim();
+        if (itemVal && itemVal !== commonVal) {
+          isFullyMatched = false;
+          break;
+        }
+      }
+      if (isFullyMatched && Object.values(item.translations).some(v => (v || '').trim())) {
+        // 所有翻译都相同，完全重复 → 跳过此项
+        continue;
+      }
+    }
+
+    const syncByIdx = headers.findIndex(h => normH(h) === 'lastsyncby');
+    const syncAtIdx = headers.findIndex(h => normH(h) === 'lastsyncat');
+    let rowHasUpdate = false;
+
+    if (!isProject) {
+      // ── Common 行：填充空格 + 冲突检测 ──
+      // fill    : common 为空，本地有值 → 更新 common（绿色）
+      // conflict: common 非空 且本地值不同（非空）→ 不改 common，在项目表追加冲突行
+      const conflictMap = new Map(); // localeNorm → local val
+
+      for (const [locale, val] of Object.entries(item.translations)) {
+        if (isEnCol(normH(locale))) continue;
+        const localeNorm = normH(locale);
+        const colIdx = headers.findIndex(h => normH(h) === localeNorm);
+        if (colIdx === -1) continue;
+        validateValue(val, item.key, locale);
+
+        const cellColor   = commonRow._colors?.[localeNorm] ?? 'none';
+        const existingVal = commonRow[localeNorm] ?? '';
+        // 译者手动编辑（无背景色 + 非空）→ 锁定，完全跳过
+        if (cellColor === 'none' && existingVal !== '') continue;
+
+        if (existingVal === '' && val && val.trim() !== '') {
+          // 空格填充：common 为空，本地有值
+          requests.push({
+            updateCells: {
+              range: { sheetId, startRowIndex: rowIdx - 1, endRowIndex: rowIdx, startColumnIndex: colIdx, endColumnIndex: colIdx + 1 },
+              rows: [{ values: [{
+                userEnteredValue: { stringValue: val },
+                userEnteredFormat: { backgroundColor: GREEN, wrapStrategy: 'WRAP' }
+              }] }],
+              fields: 'userEnteredValue,userEnteredFormat.backgroundColor,userEnteredFormat.wrapStrategy'
+            }
+          });
+          rowHasUpdate = true;
+        } else if (existingVal !== '' && val && val.trim() !== '' && val !== existingVal) {
+          // 冲突：common 已有不同值 → 记录，不改 common
+          conflictMap.set(localeNorm, val);
+        }
+        // match 或 local 为空 → 无需操作
+      }
+
+      // 冲突 → 项目表追加冲突行（仅含冲突 locale 黄色 + en 绿色，其余 locale 留空）
+      // 若该 key 的项目行已存在则不重复追加
+      if (conflictMap.size > 0 && projectHeaders.length > 0 && !projectIndex.has(pk)) {
+        newProjectRows.push({ values: buildConflictRow(projectHeaders, item, now, conflictMap) });
+      }
+    } else {
+      // ── Project 行：只更新绿色（push 写入）单元格 ──
+      // 黄色（冲突待审）、空（非冲突 locale 留空）、白/无色（译者编辑）均跳过
+      for (const [locale, val] of Object.entries(item.translations)) {
+        if (isEnCol(normH(locale))) continue;
+        const localeNorm = normH(locale);
+        const colIdx = headers.findIndex(h => normH(h) === localeNorm);
+        if (colIdx === -1) continue;
+        if (!val || !val.trim()) continue; // 本地值为空，跳过
+        validateValue(val, item.key, locale);
+
+        const cellColor   = projRow._colors?.[localeNorm] ?? 'none';
+        const existingVal = projRow[localeNorm] ?? '';
+        // 仅更新 push 写入的绿色单元格（值有变化时）
+        if (cellColor !== 'green') continue;
+        if (existingVal === val) continue; // 无变化跳过
+
+        requests.push({
+          updateCells: {
+            range: { sheetId, startRowIndex: rowIdx - 1, endRowIndex: rowIdx, startColumnIndex: colIdx, endColumnIndex: colIdx + 1 },
+            rows: [{ values: [{
+              userEnteredValue: { stringValue: val },
+              userEnteredFormat: { backgroundColor: GREEN, wrapStrategy: 'WRAP' }
+            }] }],
+            fields: 'userEnteredValue,userEnteredFormat.backgroundColor,userEnteredFormat.wrapStrategy'
+          }
+        });
+        rowHasUpdate = true;
+      }
+    }
+
+    // 元数据只写一次
+    if (rowHasUpdate) {
+      if (syncByIdx !== -1) {
+        requests.push({
+          updateCells: {
+            range: { sheetId, startRowIndex: rowIdx - 1, endRowIndex: rowIdx, startColumnIndex: syncByIdx, endColumnIndex: syncByIdx + 1 },
+            rows: [{ values: [{ userEnteredValue: { stringValue: 'push' } }] }],
+            fields: 'userEnteredValue'
+          }
+        });
+      }
+      if (syncAtIdx !== -1) {
+        requests.push({
+          updateCells: {
+            range: { sheetId, startRowIndex: rowIdx - 1, endRowIndex: rowIdx, startColumnIndex: syncAtIdx, endColumnIndex: syncAtIdx + 1 },
+            rows: [{ values: [{ userEnteredValue: { stringValue: now } }] }],
+            fields: 'userEnteredValue'
+          }
+        });
+      }
+    }
+  }
+
+  // ── 新增行：合并为单个 appendCells 请求（common / project 各一个）──
+  if (newCommonRows.length > 0) {
+    requests.push({
+      appendCells: {
+        sheetId: commonSheetId,
+        rows: newCommonRows,
+        fields: 'userEnteredValue,userEnteredFormat.backgroundColor,userEnteredFormat.wrapStrategy,userEnteredFormat.horizontalAlignment,userEnteredFormat.verticalAlignment'
+      }
+    });
+  }
+  if (newProjectRows.length > 0) {
+    requests.push({
+      appendCells: {
+        sheetId: projectSheetId,
+        rows: newProjectRows,
+        fields: 'userEnteredValue,userEnteredFormat.backgroundColor,userEnteredFormat.wrapStrategy,userEnteredFormat.horizontalAlignment,userEnteredFormat.verticalAlignment'
+      }
+    });
+  }
+
+  return requests;
+}
+
+module.exports = { generatePushPlan };

package/lib/core/utils/placeholderChecker.js

@@ -0,0 +1,26 @@
+const PLACEHOLDER_REGEX = /\{[^{}]+\}|\$\{[^{}]+\}|%[sd]|%\{[^{}]+\}|<[^\/]+\/>/g;
+
+function extractPlaceholders(str) {
+  if (!str) return new Set();
+  const matches = str.match(PLACEHOLDER_REGEX) || [];
+  return new Set(matches.map(p => p.trim()));
+}
+
+function checkPlaceholderConsistency(enText, translations) {
+  const enPlaceholders = extractPlaceholders(enText);
+  const warnings = [];
+
+  for (const [locale, text] of Object.entries(translations)) {
+    if (!text) continue;
+    const localePlaceholders = extractPlaceholders(text);
+    
+    const missing = [...enPlaceholders].filter(p => !localePlaceholders.has(p));
+    if (missing.length) warnings.push(`[${locale}] 缺失占位符: ${missing.join(', ')}`);
+    
+    const extra = [...localePlaceholders].filter(p => !enPlaceholders.has(p));
+    if (extra.length) warnings.push(`[${locale}] 多余占位符: ${extra.join(', ')}`);
+  }
+  return warnings;
+}
+
+module.exports = { extractPlaceholders, checkPlaceholderConsistency };

package/lib/core/utils/stringNormalizer.js

@@ -0,0 +1,22 @@
+function normalizeForAnchor(str) {
+  if (typeof str !== 'string') return '';
+  return str
+    .trim()
+    .replace(/[\u200B-\u200D\uFEFF\u00A0]/g, '') // 移除零宽字符与不间断空格
+    .replace(/\s+/g, ' ');                         // 连续空白合并为单空格（保留大小写）
+}
+
+/**
+ * 将归一化 locale 码还原为 BCP-47 显示格式
+ * enus → en-US  arsa → ar-SA  ptbr → pt-BR  arb → arb  en → en
+ */
+function formatLocaleHeader(code) {
+  const n = code.length;
+  if (n <= 3) return code;
+  if (n === 4) return `${code.slice(0, 2)}-${code.slice(2).toUpperCase()}`;
+  if (n === 5) return `${code.slice(0, 3)}-${code.slice(3).toUpperCase()}`;
+  if (n === 6) return `${code.slice(0, 3)}-${code.slice(3).toUpperCase()}`;
+  return code;
+}
+
+module.exports = { normalizeForAnchor, formatLocaleHeader };

package/lib/index.js

@@ -0,0 +1,8 @@
+module.exports = {
+  config: require('./config/manager'),
+  io: require('./io/googleSheets'),
+  engines: {
+    pull: require('./core/engines/pullEngine'),
+    push: require('./core/engines/pushEngine')
+  }
+};