@el-j/google-sheet-translations 2.2.0-beta.1 → 2.2.0-beta.2

package/README.md

@@ -1,5 +1,11 @@
 # Google Sheet Translations
 
+[![CI](https://github.com/el-j/google-sheet-translations/actions/workflows/ci.yml/badge.svg)](https://github.com/el-j/google-sheet-translations/actions/workflows/ci.yml)
+[![Release](https://github.com/el-j/google-sheet-translations/actions/workflows/release.yml/badge.svg)](https://github.com/el-j/google-sheet-translations/actions/workflows/release.yml)
+[![Docs](https://github.com/el-j/google-sheet-translations/actions/workflows/docs.yml/badge.svg)](https://github.com/el-j/google-sheet-translations/actions/workflows/docs.yml)
+[![npm version](https://img.shields.io/npm/v/@el-j/google-sheet-translations.svg)](https://www.npmjs.com/package/@el-j/google-sheet-translations)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
 A Node.js package for managing translations stored in Google Sheets.
 
 ## Features

package/dist/esm/index.js

@@ -1466,6 +1466,14 @@ var DEFAULT_IMAGE_MIME_TYPES = [
 ];
 var FOLDER_MIME2 = "application/vnd.google-apps.folder";
 var DRIVE_FILES_URL2 = "https://www.googleapis.com/drive/v3/files";
+function normalizeExtension(name) {
+  const dot = name.lastIndexOf(".");
+  if (dot === -1) return name;
+  const base = name.slice(0, dot);
+  let ext = name.slice(dot + 1).toLowerCase();
+  if (ext === "jpeg") ext = "jpg";
+  return `${base}.${ext}`;
+}
 async function getAccessToken2(credentials) {
   const clientEmail = credentials?.GOOGLE_CLIENT_EMAIL ?? process.env.GOOGLE_CLIENT_EMAIL;
   const privateKey = credentials?.GOOGLE_PRIVATE_KEY ?? process.env.GOOGLE_PRIVATE_KEY;
@@ -1491,7 +1499,7 @@ async function listFilesInFolder2(folderId, token, mimeTypeFilter) {
     const query = `'${folderId}' in parents${mimeClause} and trashed = false`;
     const params = new URLSearchParams({
       q: query,
-      fields: "nextPageToken,files(id,name,mimeType,parents)",
+      fields: "nextPageToken,files(id,name,mimeType,modifiedTime,parents)",
       pageSize: "1000"
     });
     if (pageToken) params.set("pageToken", pageToken);
@@ -1508,7 +1516,7 @@ async function listFilesInFolder2(folderId, token, mimeTypeFilter) {
   } while (pageToken);
   return results;
 }
-async function collectFiles(folderId, folderRelPath, outputPath, token, allowedMimeTypes, recursive, folderPattern) {
+async function collectFiles(folderId, folderRelPath, outputPath, token, allowedMimeTypes, recursive, folderPattern, normalizeExts = true) {
   console.log(`[driveImageSync] Scanning folder: ${folderId} (path: "${folderRelPath}")`);
   const allItems = await listFilesInFolder2(folderId, token);
   const entries = [];
@@ -1524,12 +1532,20 @@ async function collectFiles(folderId, folderRelPath, outputPath, token, allowedM
         token,
         allowedMimeTypes,
         recursive,
-        folderPattern
+        folderPattern,
+        normalizeExts
       );
       entries.push(...subEntries);
     } else if (allowedMimeTypes.includes(item.mimeType)) {
-      const localPath = folderRelPath ? join(outputPath, folderRelPath, item.name) : join(outputPath, item.name);
-      entries.push({ id: item.id, name: item.name, localPath, mimeType: item.mimeType });
+      const localName = normalizeExts ? normalizeExtension(item.name) : item.name;
+      const localPath = folderRelPath ? join(outputPath, folderRelPath, localName) : join(outputPath, localName);
+      entries.push({
+        id: item.id,
+        name: item.name,
+        localPath,
+        mimeType: item.mimeType,
+        driveModifiedTime: item.modifiedTime
+      });
     }
   }
   return entries;
@@ -1575,7 +1591,9 @@ async function syncDriveImages(options) {
     folderPattern,
     credentials,
     cleanSync = false,
-    concurrency = 3
+    concurrency = 3,
+    incrementalSync = true,
+    normalizeExtensions = true
   } = options;
   const token = await getAccessToken2(credentials);
   mkdirSync(outputPath, { recursive: true });
@@ -1586,16 +1604,33 @@ async function syncDriveImages(options) {
     token,
     mimeTypes,
     recursive,
-    folderPattern
+    folderPattern,
+    normalizeExtensions
   );
   const downloaded = [];
   const skipped = [];
   const errors = [];
   const tasks = entries.map((entry) => async () => {
-    if (existsSync(entry.localPath)) {
-      console.log(`[driveImageSync] Skipping (exists): ${entry.localPath}`);
-      skipped.push(entry.localPath);
-      return;
+    const localExists = existsSync(entry.localPath);
+    if (localExists) {
+      if (incrementalSync && entry.driveModifiedTime) {
+        try {
+          const localMtimeMs = statSync(entry.localPath).mtimeMs;
+          const driveMtimeMs = new Date(entry.driveModifiedTime).getTime();
+          if (driveMtimeMs <= localMtimeMs) {
+            console.log(`[driveImageSync] Skipping (up to date): ${entry.localPath}`);
+            skipped.push(entry.localPath);
+            return;
+          }
+          console.log(`[driveImageSync] Re-downloading (changed in Drive): ${entry.localPath}`);
+        } catch {
+          console.log(`[driveImageSync] Downloading (could not stat local): ${entry.localPath}`);
+        }
+      } else {
+        console.log(`[driveImageSync] Skipping (exists): ${entry.localPath}`);
+        skipped.push(entry.localPath);
+        return;
+      }
     }
     console.log(`[driveImageSync] Downloading: ${entry.localPath}`);
     try {
@@ -1626,7 +1661,134 @@ async function syncDriveImages(options) {
   return { downloaded, skipped, deleted, errors };
 }
 
+// src/utils/localImageUtils.ts
+import { promises as fsp } from "node:fs";
+import { join as join2, extname } from "node:path";
+async function walkDirectory(dir, options) {
+  const { extensions } = options ?? {};
+  const lowerExts = extensions?.map((e) => e.toLowerCase());
+  async function go(current) {
+    const entries = await fsp.readdir(current, { withFileTypes: true, encoding: "utf8" });
+    const results = [];
+    for (const entry of entries) {
+      const full = join2(current, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...await go(full));
+      } else if (entry.isFile()) {
+        if (!lowerExts || lowerExts.includes(extname(entry.name).toLowerCase())) {
+          results.push(full);
+        }
+      }
+    }
+    return results;
+  }
+  return go(dir);
+}
+var DEFAULT_IMAGE_EXTENSIONS = [
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".webp",
+  ".avif",
+  ".gif",
+  ".svg",
+  ".tiff",
+  ".bmp",
+  ".ico"
+];
+async function validateImageDirectory(options) {
+  const {
+    rootDir,
+    imageExtensions = DEFAULT_IMAGE_EXTENSIONS,
+    allowRootFiles = false,
+    expectedSubfolders = []
+  } = options;
+  const errors = [];
+  const warnings = [];
+  const rootFiles = [];
+  const subfolders = [];
+  const lowerExts = imageExtensions.map((e) => e.toLowerCase());
+  let entries;
+  try {
+    entries = await fsp.readdir(rootDir, { withFileTypes: true, encoding: "utf8" });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      valid: false,
+      errors: [`Could not read directory "${rootDir}": ${msg}`],
+      warnings,
+      rootFiles,
+      subfolders
+    };
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      subfolders.push(entry.name);
+    } else if (entry.isFile()) {
+      if (lowerExts.includes(extname(entry.name).toLowerCase())) {
+        rootFiles.push(entry.name);
+      }
+    }
+  }
+  if (!allowRootFiles && rootFiles.length > 0) {
+    errors.push(
+      `Image files found directly in "${rootDir}" \u2014 the folder structure may have been flattened during sync. Files: ${rootFiles.slice(0, 5).join(", ")}${rootFiles.length > 5 ? ` \u2026 (+${rootFiles.length - 5} more)` : ""}`
+    );
+  }
+  if (!allowRootFiles && subfolders.length === 0) {
+    errors.push(
+      `No sub-directories found in "${rootDir}". Expected a nested folder structure (e.g. projects/, performances/).`
+    );
+  }
+  const missing = expectedSubfolders.filter((name) => !subfolders.includes(name));
+  if (missing.length > 0) {
+    warnings.push(
+      `Some expected sub-folders are absent from "${rootDir}": ${missing.join(", ")}`
+    );
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    rootFiles,
+    subfolders
+  };
+}
+
+// src/utils/getDriveTranslations.ts
+import path6 from "node:path";
+
+// src/utils/driveProjectIndex.ts
+import fs6 from "node:fs";
+import path5 from "node:path";
+function buildManifest(options) {
+  const locales = Object.keys(options.translations).sort();
+  return {
+    version: "1",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    projectName: options.projectName,
+    domain: options.domain,
+    locales,
+    defaultLocale: options.defaultLocale,
+    spreadsheets: options.spreadsheets,
+    outputDirectory: options.outputDirectory,
+    flatten: options.flatten,
+    projectMetadata: options.projectMetadata
+  };
+}
+function writeManifest(manifest, manifestPath) {
+  const dir = path5.dirname(manifestPath);
+  if (!fs6.existsSync(dir)) {
+    fs6.mkdirSync(dir, { recursive: true });
+  }
+  fs6.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
+  console.log(`[driveProjectIndex] Wrote project manifest \u2192 ${manifestPath}`);
+}
+
 // src/utils/getDriveTranslations.ts
+function sanitizeFolderName(name) {
+  return name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "") || "sheet";
+}
 async function manageDriveTranslations(options) {
   const {
     driveFolderId,
@@ -1637,15 +1799,25 @@ async function manageDriveTranslations(options) {
     imageOutputPath,
     imageSyncOptions,
     translationOptions = {},
-    docTitles
+    docTitles,
+    flatten = true,
+    createManifest,
+    manifestPath,
+    projectName,
+    domain,
+    defaultLocale,
+    projectMetadata
   } = options;
   if (syncImages && !imageOutputPath) {
     throw new Error(
       "[manageDriveTranslations] imageOutputPath is required when syncImages is true"
     );
   }
+  const shouldCreateManifest = createManifest ?? driveFolderId !== void 0;
   const discoveredIds = [];
   const discoveredNames = /* @__PURE__ */ new Map();
+  const discoveredFolderPaths = /* @__PURE__ */ new Map();
+  const discoveredModifiedTimes = /* @__PURE__ */ new Map();
   if (driveFolderId && scanForSpreadsheets) {
     const scanOptions = { folderId: driveFolderId };
     const discovered = await scanDriveFolderForSpreadsheets(scanOptions);
@@ -1655,6 +1827,8 @@ async function manageDriveTranslations(options) {
     for (const file of discovered) {
       discoveredIds.push(file.id);
       discoveredNames.set(file.id, file.name);
+      discoveredFolderPaths.set(file.id, file.folderPath);
+      if (file.modifiedTime) discoveredModifiedTimes.set(file.id, file.modifiedTime);
     }
   }
   const allIds = [.../* @__PURE__ */ new Set([...discoveredIds, ...explicitIds])];
@@ -1663,10 +1837,50 @@ async function manageDriveTranslations(options) {
     if (!name) return true;
     return spreadsheetNameFilter.test(name);
   }) : allIds;
-  const translations = await getMultipleSpreadSheetsData(docTitles, {
-    ...translationOptions,
-    spreadsheetIds: filteredIds.length > 0 ? filteredIds : void 0
-  });
+  let translations;
+  const spreadsheetEntries = [];
+  const baseOutputDir = translationOptions.translationsOutputDir ?? "translations";
+  if (!flatten) {
+    const { mergeStrategy = "later-wins", ...baseOptions } = translationOptions;
+    const perResults = [];
+    for (const id of filteredIds) {
+      const name = discoveredNames.get(id) ?? id;
+      const subDir = sanitizeFolderName(name);
+      const subOutputDir = path6.join(baseOutputDir, subDir);
+      console.log(
+        `[manageDriveTranslations] (flatten: false) Fetching "${name}" \u2192 ${subOutputDir}`
+      );
+      const result = await getSpreadSheetData(docTitles, {
+        ...baseOptions,
+        spreadsheetId: id,
+        translationsOutputDir: subOutputDir
+      });
+      perResults.push(result);
+      spreadsheetEntries.push({
+        id,
+        name,
+        folderPath: discoveredFolderPaths.get(id) ?? "",
+        sheets: docTitles ?? [],
+        modifiedTime: discoveredModifiedTimes.get(id),
+        outputSubDirectory: subDir
+      });
+    }
+    translations = mergeMultipleTranslationData(perResults, mergeStrategy);
+  } else {
+    translations = await getMultipleSpreadSheetsData(docTitles, {
+      ...translationOptions,
+      spreadsheetIds: filteredIds.length > 0 ? filteredIds : void 0
+    });
+    for (const id of filteredIds) {
+      spreadsheetEntries.push({
+        id,
+        name: discoveredNames.get(id) ?? id,
+        folderPath: discoveredFolderPaths.get(id) ?? "",
+        sheets: docTitles ?? [],
+        modifiedTime: discoveredModifiedTimes.get(id)
+      });
+    }
+  }
   let imageSync;
   if (syncImages && driveFolderId && imageOutputPath) {
     imageSync = await syncDriveImages({
@@ -1675,13 +1889,30 @@ async function manageDriveTranslations(options) {
       outputPath: imageOutputPath
     });
   }
-  return { translations, spreadsheetIds: filteredIds, imageSync };
+  let manifest;
+  if (shouldCreateManifest) {
+    const resolvedManifestPath = manifestPath ?? path6.join(baseOutputDir, "i18n-manifest.json");
+    manifest = buildManifest({
+      translations,
+      spreadsheets: spreadsheetEntries,
+      outputDirectory: baseOutputDir,
+      flatten,
+      projectName,
+      domain,
+      defaultLocale,
+      projectMetadata
+    });
+    writeManifest(manifest, resolvedManifestPath);
+  }
+  return { translations, spreadsheetIds: filteredIds, imageSync, manifest };
 }
 
 // src/index.ts
 var index_default = getSpreadSheetData;
 export {
+  DEFAULT_IMAGE_EXTENSIONS,
   DEFAULT_WAIT_SECONDS,
+  buildManifest,
   convertFromDataJsonFormat,
   convertToDataJsonFormat,
   createAuthClient,
@@ -1703,6 +1934,7 @@ export {
   manageDriveTranslations,
   mergeMultipleTranslationData,
   mergeSheets,
+  normalizeExtension,
   normalizeLocaleCode,
   processRawRows,
   readPublicSheet,
@@ -1712,9 +1944,12 @@ export {
   updateSpreadsheetWithLocalChanges,
   validateCredentials,
   validateEnv,
+  validateImageDirectory,
   wait,
+  walkDirectory,
   withRetry,
   writeLanguageDataFile,
   writeLocalesFile,
+  writeManifest,
   writeTranslationFiles
 };

package/dist/index.d.ts

@@ -30,10 +30,14 @@ export type { MultiSpreadsheetOptions } from './getMultipleSpreadSheetsData';
 export { mergeMultipleTranslationData } from './utils/multiSpreadsheetMerger';
 export { scanDriveFolderForSpreadsheets } from './utils/driveFolderScanner';
 export type { DriveSpreadsheetFile, ScanDriveFolderOptions } from './utils/driveFolderScanner';
-export { syncDriveImages } from './utils/driveImageSync';
+export { syncDriveImages, normalizeExtension } from './utils/driveImageSync';
 export type { DriveImageSyncOptions, DriveImageSyncResult } from './utils/driveImageSync';
+export { walkDirectory, validateImageDirectory, DEFAULT_IMAGE_EXTENSIONS } from './utils/localImageUtils';
+export type { WalkDirectoryOptions, ImageDirectoryValidationOptions, ImageDirectoryValidationResult, } from './utils/localImageUtils';
 export { manageDriveTranslations } from './utils/getDriveTranslations';
 export type { GoogleDriveManagerOptions, GoogleDriveManagerResult } from './utils/getDriveTranslations';
+export { buildManifest, writeManifest } from './utils/driveProjectIndex';
+export type { DriveProjectManifest, SpreadsheetManifestEntry, BuildManifestOptions } from './utils/driveProjectIndex';
 import { getSpreadSheetData } from './getSpreadSheetData';
 export default getSpreadSheetData;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAGhF,YAAY,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,+CAA+C,CAAC;AACxF,OAAO,EAAE,yBAAyB,EAAE,MAAM,iDAAiD,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AAC1E,OAAO,EAAE,iCAAiC,EAAE,MAAM,4BAA4B,CAAC;AAG/E,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAGzE,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,0BAA0B,EAC1B,4BAA4B,EAC5B,yBAAyB,GAC1B,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,YAAY,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAGpE,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACtG,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAGnF,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAGpG,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,aAAa,GACd,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAC5E,YAAY,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAC7E,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAG9E,OAAO,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAC5E,YAAY,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAG/F,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAG1F,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,YAAY,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAGxG,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,eAAe,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAGhF,YAAY,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,+CAA+C,CAAC;AACxF,OAAO,EAAE,yBAAyB,EAAE,MAAM,iDAAiD,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AAC1E,OAAO,EAAE,iCAAiC,EAAE,MAAM,4BAA4B,CAAC;AAG/E,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAGzE,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,0BAA0B,EAC1B,4BAA4B,EAC5B,yBAAyB,GAC1B,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,YAAY,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAGpE,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACtG,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAGnF,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAGpG,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,aAAa,GACd,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAC5E,YAAY,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAC7E,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAG9E,OAAO,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAC5E,YAAY,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAG/F,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC7E,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAC1G,YAAY,EACV,oBAAoB,EACpB,+BAA+B,EAC/B,8BAA8B,GAC/B,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,YAAY,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAGxG,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AACzE,YAAY,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAGtH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,eAAe,kBAAkB,CAAC"}

package/dist/index.js

@@ -30,7 +30,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DEFAULT_IMAGE_EXTENSIONS: () => DEFAULT_IMAGE_EXTENSIONS,
   DEFAULT_WAIT_SECONDS: () => DEFAULT_WAIT_SECONDS,
+  buildManifest: () => buildManifest,
   convertFromDataJsonFormat: () => convertFromDataJsonFormat,
   convertToDataJsonFormat: () => convertToDataJsonFormat,
   createAuthClient: () => createAuthClient,
@@ -52,6 +54,7 @@ __export(index_exports, {
   manageDriveTranslations: () => manageDriveTranslations,
   mergeMultipleTranslationData: () => mergeMultipleTranslationData,
   mergeSheets: () => mergeSheets,
+  normalizeExtension: () => normalizeExtension,
   normalizeLocaleCode: () => normalizeLocaleCode,
   processRawRows: () => processRawRows,
   readPublicSheet: () => readPublicSheet,
@@ -61,10 +64,13 @@ __export(index_exports, {
   updateSpreadsheetWithLocalChanges: () => updateSpreadsheetWithLocalChanges,
   validateCredentials: () => validateCredentials,
   validateEnv: () => validateEnv,
+  validateImageDirectory: () => validateImageDirectory,
   wait: () => wait,
+  walkDirectory: () => walkDirectory,
   withRetry: () => withRetry,
   writeLanguageDataFile: () => writeLanguageDataFile,
   writeLocalesFile: () => writeLocalesFile,
+  writeManifest: () => writeManifest,
   writeTranslationFiles: () => writeTranslationFiles
 });
 module.exports = __toCommonJS(index_exports);
@@ -1537,6 +1543,14 @@ var DEFAULT_IMAGE_MIME_TYPES = [
 ];
 var FOLDER_MIME2 = "application/vnd.google-apps.folder";
 var DRIVE_FILES_URL2 = "https://www.googleapis.com/drive/v3/files";
+function normalizeExtension(name) {
+  const dot = name.lastIndexOf(".");
+  if (dot === -1) return name;
+  const base = name.slice(0, dot);
+  let ext = name.slice(dot + 1).toLowerCase();
+  if (ext === "jpeg") ext = "jpg";
+  return `${base}.${ext}`;
+}
 async function getAccessToken2(credentials) {
   const clientEmail = credentials?.GOOGLE_CLIENT_EMAIL ?? process.env.GOOGLE_CLIENT_EMAIL;
   const privateKey = credentials?.GOOGLE_PRIVATE_KEY ?? process.env.GOOGLE_PRIVATE_KEY;
@@ -1562,7 +1576,7 @@ async function listFilesInFolder2(folderId, token, mimeTypeFilter) {
     const query = `'${folderId}' in parents${mimeClause} and trashed = false`;
     const params = new URLSearchParams({
       q: query,
-      fields: "nextPageToken,files(id,name,mimeType,parents)",
+      fields: "nextPageToken,files(id,name,mimeType,modifiedTime,parents)",
       pageSize: "1000"
     });
     if (pageToken) params.set("pageToken", pageToken);
@@ -1579,7 +1593,7 @@ async function listFilesInFolder2(folderId, token, mimeTypeFilter) {
   } while (pageToken);
   return results;
 }
-async function collectFiles(folderId, folderRelPath, outputPath, token, allowedMimeTypes, recursive, folderPattern) {
+async function collectFiles(folderId, folderRelPath, outputPath, token, allowedMimeTypes, recursive, folderPattern, normalizeExts = true) {
   console.log(`[driveImageSync] Scanning folder: ${folderId} (path: "${folderRelPath}")`);
   const allItems = await listFilesInFolder2(folderId, token);
   const entries = [];
@@ -1595,12 +1609,20 @@ async function collectFiles(folderId, folderRelPath, outputPath, token, allowedM
         token,
         allowedMimeTypes,
         recursive,
-        folderPattern
+        folderPattern,
+        normalizeExts
       );
       entries.push(...subEntries);
     } else if (allowedMimeTypes.includes(item.mimeType)) {
-      const localPath = folderRelPath ? (0, import_node_path5.join)(outputPath, folderRelPath, item.name) : (0, import_node_path5.join)(outputPath, item.name);
-      entries.push({ id: item.id, name: item.name, localPath, mimeType: item.mimeType });
+      const localName = normalizeExts ? normalizeExtension(item.name) : item.name;
+      const localPath = folderRelPath ? (0, import_node_path5.join)(outputPath, folderRelPath, localName) : (0, import_node_path5.join)(outputPath, localName);
+      entries.push({
+        id: item.id,
+        name: item.name,
+        localPath,
+        mimeType: item.mimeType,
+        driveModifiedTime: item.modifiedTime
+      });
     }
   }
   return entries;
@@ -1646,7 +1668,9 @@ async function syncDriveImages(options) {
     folderPattern,
     credentials,
     cleanSync = false,
-    concurrency = 3
+    concurrency = 3,
+    incrementalSync = true,
+    normalizeExtensions = true
   } = options;
   const token = await getAccessToken2(credentials);
   (0, import_node_fs6.mkdirSync)(outputPath, { recursive: true });
@@ -1657,16 +1681,33 @@ async function syncDriveImages(options) {
     token,
     mimeTypes,
     recursive,
-    folderPattern
+    folderPattern,
+    normalizeExtensions
   );
   const downloaded = [];
   const skipped = [];
   const errors = [];
   const tasks = entries.map((entry) => async () => {
-    if ((0, import_node_fs6.existsSync)(entry.localPath)) {
-      console.log(`[driveImageSync] Skipping (exists): ${entry.localPath}`);
-      skipped.push(entry.localPath);
-      return;
+    const localExists = (0, import_node_fs6.existsSync)(entry.localPath);
+    if (localExists) {
+      if (incrementalSync && entry.driveModifiedTime) {
+        try {
+          const localMtimeMs = (0, import_node_fs6.statSync)(entry.localPath).mtimeMs;
+          const driveMtimeMs = new Date(entry.driveModifiedTime).getTime();
+          if (driveMtimeMs <= localMtimeMs) {
+            console.log(`[driveImageSync] Skipping (up to date): ${entry.localPath}`);
+            skipped.push(entry.localPath);
+            return;
+          }
+          console.log(`[driveImageSync] Re-downloading (changed in Drive): ${entry.localPath}`);
+        } catch {
+          console.log(`[driveImageSync] Downloading (could not stat local): ${entry.localPath}`);
+        }
+      } else {
+        console.log(`[driveImageSync] Skipping (exists): ${entry.localPath}`);
+        skipped.push(entry.localPath);
+        return;
+      }
     }
     console.log(`[driveImageSync] Downloading: ${entry.localPath}`);
     try {
@@ -1697,7 +1738,134 @@ async function syncDriveImages(options) {
   return { downloaded, skipped, deleted, errors };
 }
 
+// src/utils/localImageUtils.ts
+var import_node_fs7 = require("node:fs");
+var import_node_path6 = require("node:path");
+async function walkDirectory(dir, options) {
+  const { extensions } = options ?? {};
+  const lowerExts = extensions?.map((e) => e.toLowerCase());
+  async function go(current) {
+    const entries = await import_node_fs7.promises.readdir(current, { withFileTypes: true, encoding: "utf8" });
+    const results = [];
+    for (const entry of entries) {
+      const full = (0, import_node_path6.join)(current, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...await go(full));
+      } else if (entry.isFile()) {
+        if (!lowerExts || lowerExts.includes((0, import_node_path6.extname)(entry.name).toLowerCase())) {
+          results.push(full);
+        }
+      }
+    }
+    return results;
+  }
+  return go(dir);
+}
+var DEFAULT_IMAGE_EXTENSIONS = [
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".webp",
+  ".avif",
+  ".gif",
+  ".svg",
+  ".tiff",
+  ".bmp",
+  ".ico"
+];
+async function validateImageDirectory(options) {
+  const {
+    rootDir,
+    imageExtensions = DEFAULT_IMAGE_EXTENSIONS,
+    allowRootFiles = false,
+    expectedSubfolders = []
+  } = options;
+  const errors = [];
+  const warnings = [];
+  const rootFiles = [];
+  const subfolders = [];
+  const lowerExts = imageExtensions.map((e) => e.toLowerCase());
+  let entries;
+  try {
+    entries = await import_node_fs7.promises.readdir(rootDir, { withFileTypes: true, encoding: "utf8" });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      valid: false,
+      errors: [`Could not read directory "${rootDir}": ${msg}`],
+      warnings,
+      rootFiles,
+      subfolders
+    };
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      subfolders.push(entry.name);
+    } else if (entry.isFile()) {
+      if (lowerExts.includes((0, import_node_path6.extname)(entry.name).toLowerCase())) {
+        rootFiles.push(entry.name);
+      }
+    }
+  }
+  if (!allowRootFiles && rootFiles.length > 0) {
+    errors.push(
+      `Image files found directly in "${rootDir}" \u2014 the folder structure may have been flattened during sync. Files: ${rootFiles.slice(0, 5).join(", ")}${rootFiles.length > 5 ? ` \u2026 (+${rootFiles.length - 5} more)` : ""}`
+    );
+  }
+  if (!allowRootFiles && subfolders.length === 0) {
+    errors.push(
+      `No sub-directories found in "${rootDir}". Expected a nested folder structure (e.g. projects/, performances/).`
+    );
+  }
+  const missing = expectedSubfolders.filter((name) => !subfolders.includes(name));
+  if (missing.length > 0) {
+    warnings.push(
+      `Some expected sub-folders are absent from "${rootDir}": ${missing.join(", ")}`
+    );
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    rootFiles,
+    subfolders
+  };
+}
+
+// src/utils/getDriveTranslations.ts
+var import_node_path8 = __toESM(require("node:path"));
+
+// src/utils/driveProjectIndex.ts
+var import_node_fs8 = __toESM(require("node:fs"));
+var import_node_path7 = __toESM(require("node:path"));
+function buildManifest(options) {
+  const locales = Object.keys(options.translations).sort();
+  return {
+    version: "1",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    projectName: options.projectName,
+    domain: options.domain,
+    locales,
+    defaultLocale: options.defaultLocale,
+    spreadsheets: options.spreadsheets,
+    outputDirectory: options.outputDirectory,
+    flatten: options.flatten,
+    projectMetadata: options.projectMetadata
+  };
+}
+function writeManifest(manifest, manifestPath) {
+  const dir = import_node_path7.default.dirname(manifestPath);
+  if (!import_node_fs8.default.existsSync(dir)) {
+    import_node_fs8.default.mkdirSync(dir, { recursive: true });
+  }
+  import_node_fs8.default.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
+  console.log(`[driveProjectIndex] Wrote project manifest \u2192 ${manifestPath}`);
+}
+
 // src/utils/getDriveTranslations.ts
+function sanitizeFolderName(name) {
+  return name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "") || "sheet";
+}
 async function manageDriveTranslations(options) {
   const {
     driveFolderId,
@@ -1708,15 +1876,25 @@ async function manageDriveTranslations(options) {
     imageOutputPath,
     imageSyncOptions,
     translationOptions = {},
-    docTitles
+    docTitles,
+    flatten = true,
+    createManifest,
+    manifestPath,
+    projectName,
+    domain,
+    defaultLocale,
+    projectMetadata
   } = options;
   if (syncImages && !imageOutputPath) {
     throw new Error(
       "[manageDriveTranslations] imageOutputPath is required when syncImages is true"
     );
   }
+  const shouldCreateManifest = createManifest ?? driveFolderId !== void 0;
   const discoveredIds = [];
   const discoveredNames = /* @__PURE__ */ new Map();
+  const discoveredFolderPaths = /* @__PURE__ */ new Map();
+  const discoveredModifiedTimes = /* @__PURE__ */ new Map();
   if (driveFolderId && scanForSpreadsheets) {
     const scanOptions = { folderId: driveFolderId };
     const discovered = await scanDriveFolderForSpreadsheets(scanOptions);
@@ -1726,6 +1904,8 @@ async function manageDriveTranslations(options) {
     for (const file of discovered) {
       discoveredIds.push(file.id);
       discoveredNames.set(file.id, file.name);
+      discoveredFolderPaths.set(file.id, file.folderPath);
+      if (file.modifiedTime) discoveredModifiedTimes.set(file.id, file.modifiedTime);
     }
   }
   const allIds = [.../* @__PURE__ */ new Set([...discoveredIds, ...explicitIds])];
@@ -1734,10 +1914,50 @@ async function manageDriveTranslations(options) {
     if (!name) return true;
     return spreadsheetNameFilter.test(name);
   }) : allIds;
-  const translations = await getMultipleSpreadSheetsData(docTitles, {
-    ...translationOptions,
-    spreadsheetIds: filteredIds.length > 0 ? filteredIds : void 0
-  });
+  let translations;
+  const spreadsheetEntries = [];
+  const baseOutputDir = translationOptions.translationsOutputDir ?? "translations";
+  if (!flatten) {
+    const { mergeStrategy = "later-wins", ...baseOptions } = translationOptions;
+    const perResults = [];
+    for (const id of filteredIds) {
+      const name = discoveredNames.get(id) ?? id;
+      const subDir = sanitizeFolderName(name);
+      const subOutputDir = import_node_path8.default.join(baseOutputDir, subDir);
+      console.log(
+        `[manageDriveTranslations] (flatten: false) Fetching "${name}" \u2192 ${subOutputDir}`
+      );
+      const result = await getSpreadSheetData(docTitles, {
+        ...baseOptions,
+        spreadsheetId: id,
+        translationsOutputDir: subOutputDir
+      });
+      perResults.push(result);
+      spreadsheetEntries.push({
+        id,
+        name,
+        folderPath: discoveredFolderPaths.get(id) ?? "",
+        sheets: docTitles ?? [],
+        modifiedTime: discoveredModifiedTimes.get(id),
+        outputSubDirectory: subDir
+      });
+    }
+    translations = mergeMultipleTranslationData(perResults, mergeStrategy);
+  } else {
+    translations = await getMultipleSpreadSheetsData(docTitles, {
+      ...translationOptions,
+      spreadsheetIds: filteredIds.length > 0 ? filteredIds : void 0
+    });
+    for (const id of filteredIds) {
+      spreadsheetEntries.push({
+        id,
+        name: discoveredNames.get(id) ?? id,
+        folderPath: discoveredFolderPaths.get(id) ?? "",
+        sheets: docTitles ?? [],
+        modifiedTime: discoveredModifiedTimes.get(id)
+      });
+    }
+  }
   let imageSync;
   if (syncImages && driveFolderId && imageOutputPath) {
     imageSync = await syncDriveImages({
@@ -1746,14 +1966,31 @@ async function manageDriveTranslations(options) {
       outputPath: imageOutputPath
     });
   }
-  return { translations, spreadsheetIds: filteredIds, imageSync };
+  let manifest;
+  if (shouldCreateManifest) {
+    const resolvedManifestPath = manifestPath ?? import_node_path8.default.join(baseOutputDir, "i18n-manifest.json");
+    manifest = buildManifest({
+      translations,
+      spreadsheets: spreadsheetEntries,
+      outputDirectory: baseOutputDir,
+      flatten,
+      projectName,
+      domain,
+      defaultLocale,
+      projectMetadata
+    });
+    writeManifest(manifest, resolvedManifestPath);
+  }
+  return { translations, spreadsheetIds: filteredIds, imageSync, manifest };
 }
 
 // src/index.ts
 var index_default = getSpreadSheetData;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_IMAGE_EXTENSIONS,
   DEFAULT_WAIT_SECONDS,
+  buildManifest,
   convertFromDataJsonFormat,
   convertToDataJsonFormat,
   createAuthClient,
@@ -1774,6 +2011,7 @@ var index_default = getSpreadSheetData;
   manageDriveTranslations,
   mergeMultipleTranslationData,
   mergeSheets,
+  normalizeExtension,
   normalizeLocaleCode,
   processRawRows,
   readPublicSheet,
@@ -1783,9 +2021,12 @@ var index_default = getSpreadSheetData;
   updateSpreadsheetWithLocalChanges,
   validateCredentials,
   validateEnv,
+  validateImageDirectory,
   wait,
+  walkDirectory,
   withRetry,
   writeLanguageDataFile,
   writeLocalesFile,
+  writeManifest,
   writeTranslationFiles
 });

package/dist/utils/driveImageSync.d.ts

@@ -21,6 +21,22 @@ export interface DriveImageSyncOptions {
     cleanSync?: boolean;
     /** Max concurrent downloads (default: 3) */
     concurrency?: number;
+    /**
+     * When `true` (default), a file that already exists locally is re-downloaded
+     * only when Drive's `modifiedTime` is strictly newer than the local file's
+     * last-modified timestamp. This avoids re-downloading unchanged assets on
+     * every run. When `false`, any file that already exists locally is always
+     * skipped regardless of whether Drive has a newer version.
+     */
+    incrementalSync?: boolean;
+    /**
+     * When `true` (default), local filenames are written with lowercase file
+     * extensions and `jpeg` is normalized to `jpg`.
+     * Examples: `Photo.JPEG` → `Photo.jpg`, `banner.PNG` → `banner.png`,
+     *           `icon.Svg` → `icon.svg`.
+     * Applies only to the extension; the base name is left unchanged.
+     */
+    normalizeExtensions?: boolean;
 }
 export interface DriveImageSyncResult {
     downloaded: string[];
@@ -28,6 +44,14 @@ export interface DriveImageSyncResult {
     deleted: string[];
     errors: string[];
 }
+/**
+ * Normalises a filename's extension:
+ * - Converts the extension to lowercase
+ * - Canonicalises `jpeg` → `jpg`
+ *
+ * The base name is left unchanged so that `MyPhoto.JPEG` becomes `MyPhoto.jpg`.
+ */
+export declare function normalizeExtension(name: string): string;
 /**
  * Syncs images from a Google Drive folder to a local directory.
  * Preserves subfolder structure. Uses Drive API v3 via fetch.

package/dist/utils/driveImageSync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"driveImageSync.d.ts","sourceRoot":"","sources":["../../src/utils/driveImageSync.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,MAAM,WAAW,qBAAqB;IACpC,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,iFAAiF;IACjF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAoLD;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAoE/B"}
+{"version":3,"file":"driveImageSync.d.ts","sourceRoot":"","sources":["../../src/utils/driveImageSync.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,MAAM,WAAW,qBAAqB;IACpC,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,iFAAiF;IACjF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAwCD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOvD;AAyJD;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CA4F/B"}

package/dist/utils/driveProjectIndex.d.ts

@@ -0,0 +1,74 @@
+import type { TranslationData } from '../types';
+/**
+ * Metadata for a single spreadsheet in the project manifest.
+ */
+export interface SpreadsheetManifestEntry {
+    /** Google Spreadsheet file ID */
+    id: string;
+    /** Human-readable name of the spreadsheet */
+    name: string;
+    /** Relative path within the Drive folder (e.g. "subproject/translations") */
+    folderPath: string;
+    /** Sheet / tab names that were processed */
+    sheets: string[];
+    /** ISO timestamp of last modification reported by Drive */
+    modifiedTime?: string;
+    /**
+     * Local subdirectory used for output when `flatten: false`.
+     * Undefined when `flatten: true` (all locales go to the root outputDirectory).
+     */
+    outputSubDirectory?: string;
+}
+/**
+ * Project-level manifest written to disk after every `manageDriveTranslations` run.
+ * Acts as a single source of truth for the i18n project layout.
+ */
+export interface DriveProjectManifest {
+    /** Manifest format version — increment when the shape changes */
+    version: '1';
+    /** ISO timestamp when this manifest was last generated */
+    generatedAt: string;
+    /** User-defined project name (e.g. "my-app-i18n") */
+    projectName?: string;
+    /** Project domain or site URL for reference */
+    domain?: string;
+    /** Sorted list of all locale codes available across all spreadsheets */
+    locales: string[];
+    /** Primary / source locale (e.g. "en") */
+    defaultLocale?: string;
+    /** Every spreadsheet that was processed in the last run */
+    spreadsheets: SpreadsheetManifestEntry[];
+    /** Base local directory where translation files are written */
+    outputDirectory: string;
+    /**
+     * Whether translation files use a flat layout (all locales in one dir)
+     * or a per-spreadsheet subdirectory layout.
+     */
+    flatten: boolean;
+    /** Any additional user-defined metadata */
+    projectMetadata?: Record<string, unknown>;
+}
+export interface BuildManifestOptions {
+    translations: TranslationData;
+    spreadsheets: SpreadsheetManifestEntry[];
+    outputDirectory: string;
+    flatten: boolean;
+    projectName?: string;
+    domain?: string;
+    defaultLocale?: string;
+    projectMetadata?: Record<string, unknown>;
+}
+/**
+ * Builds a DriveProjectManifest from the current run's state.
+ * Does NOT write to disk — call `writeManifest` for that.
+ */
+export declare function buildManifest(options: BuildManifestOptions): DriveProjectManifest;
+/**
+ * Writes the project manifest JSON to disk.
+ * Creates parent directories as needed.
+ *
+ * @param manifest  - The manifest to serialize
+ * @param manifestPath - Absolute or relative path for the output file
+ */
+export declare function writeManifest(manifest: DriveProjectManifest, manifestPath: string): void;
+//# sourceMappingURL=driveProjectIndex.d.ts.map

package/dist/utils/driveProjectIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driveProjectIndex.d.ts","sourceRoot":"","sources":["../../src/utils/driveProjectIndex.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,OAAO,EAAE,GAAG,CAAC;IACb,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0CAA0C;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,YAAY,EAAE,wBAAwB,EAAE,CAAC;IACzC,+DAA+D;IAC/D,eAAe,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,eAAe,CAAC;IAC9B,YAAY,EAAE,wBAAwB,EAAE,CAAC;IACzC,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,oBAAoB,CAcjF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAOxF"}

package/dist/utils/getDriveTranslations.d.ts

@@ -1,6 +1,7 @@
 import type { TranslationData } from '../types';
 import type { MultiSpreadsheetOptions } from '../getMultipleSpreadSheetsData';
 import type { DriveImageSyncOptions, DriveImageSyncResult } from './driveImageSync';
+import type { DriveProjectManifest } from './driveProjectIndex';
 export interface GoogleDriveManagerOptions {
     /**
      * Google Drive folder ID to scan for spreadsheets and/or images.
@@ -47,6 +48,34 @@ export interface GoogleDriveManagerOptions {
     translationOptions?: MultiSpreadsheetOptions;
     /** Sheet names to fetch from each discovered spreadsheet */
     docTitles?: string[];
+    /**
+     * When `false`, each spreadsheet writes translations to its own subdirectory
+     * inside `translationsOutputDir`, named after the spreadsheet (sanitized).
+     * Example with `flatten: false`:
+     *   `translations/app-i18n/en.json`
+     *   `translations/marketing/de.json`
+     * When `true` (default), all spreadsheets are merged into a flat set:
+     *   `translations/en.json`
+     */
+    flatten?: boolean;
+    /**
+     * Write an `i18n-manifest.json` index file after each run.
+     * Default: `true` when `driveFolderId` is set, `false` otherwise.
+     */
+    createManifest?: boolean;
+    /**
+     * Path for the manifest file.
+     * Default: `path.join(translationsOutputDir, 'i18n-manifest.json')`
+     */
+    manifestPath?: string;
+    /** Human-readable project name stored in the manifest */
+    projectName?: string;
+    /** Site domain / URL stored in the manifest */
+    domain?: string;
+    /** Primary locale code stored in the manifest (e.g. "en") */
+    defaultLocale?: string;
+    /** Arbitrary metadata stored in the manifest */
+    projectMetadata?: Record<string, unknown>;
 }
 export interface GoogleDriveManagerResult {
     translations: TranslationData;
@@ -54,6 +83,8 @@ export interface GoogleDriveManagerResult {
     spreadsheetIds: string[];
     /** Image sync result (only present if syncImages: true) */
     imageSync?: DriveImageSyncResult;
+    /** Project manifest written during this run (only present when `createManifest: true`) */
+    manifest?: DriveProjectManifest;
 }
 /**
  * Top-level "headless CMS bridge" function.

package/dist/utils/getDriveTranslations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getDriveTranslations.d.ts","sourceRoot":"","sources":["../../src/utils/getDriveTranslations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAI9E,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAGpF,MAAM,WAAW,yBAAyB;IACzC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAElD;;;OAGG;IACH,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;IAE7C,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACxC,YAAY,EAAE,eAAe,CAAC;IAC9B,kDAAkD;IAClD,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,oBAAoB,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,uBAAuB,CAC5C,OAAO,EAAE,yBAAyB,GAChC,OAAO,CAAC,wBAAwB,CAAC,CAkEnC"}
+{"version":3,"file":"getDriveTranslations.d.ts","sourceRoot":"","sources":["../../src/utils/getDriveTranslations.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAM9E,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAEpF,OAAO,KAAK,EAAE,oBAAoB,EAA4B,MAAM,qBAAqB,CAAC;AAG1F,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAElD;;;OAGG;IACH,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;IAE7C,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAErB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,eAAe,CAAC;IAC9B,kDAAkD;IAClD,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CACjC;AAaD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAiJnC"}

package/dist/utils/localImageUtils.d.ts

@@ -0,0 +1,105 @@
+export interface WalkDirectoryOptions {
+    /**
+     * Only include files whose extension (case-insensitive, including the dot)
+     * is in this list. Example: `['.jpg', '.png']`.
+     * When omitted, all files are included.
+     */
+    extensions?: string[];
+}
+/**
+ * Recursively walks a directory and returns the absolute paths of all files
+ * found inside it (and any sub-directories).
+ *
+ * Uses `fs/promises` throughout so it integrates cleanly with async pipelines.
+ *
+ * @param dir - Absolute or relative path to the directory to walk.
+ * @param options - Optional filter options.
+ * @returns Array of absolute file paths.
+ *
+ * @example
+ * const files = await walkDirectory('./src/assets/remote-images', {
+ *   extensions: ['.jpg', '.png'],
+ * });
+ * console.log(files); // ['/abs/path/projects/hero.jpg', ...]
+ */
+export declare function walkDirectory(dir: string, options?: WalkDirectoryOptions): Promise<string[]>;
+/** Default extensions treated as "image files" for validation purposes. */
+export declare const DEFAULT_IMAGE_EXTENSIONS: string[];
+export interface ImageDirectoryValidationOptions {
+    /**
+     * Absolute or relative path to the root image directory to inspect
+     * (e.g. `'./src/assets/remote-images'`).
+     */
+    rootDir: string;
+    /**
+     * File extensions (lower-case, with leading dot) that are counted as
+     * image files.
+     * Defaults to `DEFAULT_IMAGE_EXTENSIONS`.
+     */
+    imageExtensions?: string[];
+    /**
+     * When `false` (default), the presence of image files directly inside
+     * `rootDir` (rather than inside sub-directories) is treated as an **error**
+     * — it typically means the sync inadvertently flattened the folder
+     * hierarchy.
+     * Set to `true` to allow root-level images without raising an error.
+     */
+    allowRootFiles?: boolean;
+    /**
+     * Sub-folder names that are expected to be present inside `rootDir`.
+     * Any names from this list that are absent produce a **warning** (not an
+     * error), because the folder may simply be empty in Drive.
+     *
+     * Example: `['projects', 'performances', 'workshops']`
+     */
+    expectedSubfolders?: string[];
+}
+export interface ImageDirectoryValidationResult {
+    /**
+     * `true` when no errors were found.
+     * Warnings do **not** affect this flag.
+     */
+    valid: boolean;
+    /** Fatal problems that indicate incorrect state. */
+    errors: string[];
+    /** Non-fatal observations that may indicate a problem. */
+    warnings: string[];
+    /**
+     * Names of image files found directly in `rootDir` (not in sub-directories).
+     * Populated even when `allowRootFiles` is `true`.
+     */
+    rootFiles: string[];
+    /** Names of all direct sub-directories found in `rootDir`. */
+    subfolders: string[];
+}
+/**
+ * Inspects a local image directory and validates that it has the expected
+ * nested structure after a `syncDriveImages` call.
+ *
+ * Three things are checked:
+ *
+ * 1. **Root-level image files** — by default these are an error because they
+ *    usually indicate the sync flattened the Drive folder hierarchy.
+ * 2. **Presence of sub-directories** — at least one sub-directory must exist
+ *    (unless `allowRootFiles: true`).
+ * 3. **Expected sub-folder names** — if `expectedSubfolders` is provided, any
+ *    missing names produce a warning.
+ *
+ * The function never throws; all problems are reported in the returned object.
+ *
+ * @example
+ * import { validateImageDirectory } from '@el-j/google-sheet-translations';
+ *
+ * const result = await validateImageDirectory({
+ *   rootDir: './src/assets/remote-images',
+ *   expectedSubfolders: ['projects', 'performances', 'workshops'],
+ * });
+ *
+ * if (!result.valid) {
+ *   console.error('Image directory problems:', result.errors);
+ *   process.exit(1);
+ * }
+ * for (const warn of result.warnings) console.warn(warn);
+ */
+export declare function validateImageDirectory(options: ImageDirectoryValidationOptions): Promise<ImageDirectoryValidationResult>;
+//# sourceMappingURL=localImageUtils.d.ts.map

package/dist/utils/localImageUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localImageUtils.d.ts","sourceRoot":"","sources":["../../src/utils/localImageUtils.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,MAAM,EAAE,CAAC,CAuBnB;AAMD,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,UAWpC,CAAC;AAEF,MAAM,WAAW,+BAA+B;IAC9C;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,8BAA8B;IAC7C;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC;IACf,oDAAoD;IACpD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;OAGG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,8BAA8B,CAAC,CAsEzC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@el-j/google-sheet-translations",
-  "version": "2.2.0-beta.1",
+  "version": "2.2.0-beta.2",
   "description": "A package to manage translations stored in Google Spreadsheets",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",
@@ -39,7 +39,8 @@
     "docs:build": "vitepress build website",
     "docs:preview": "vitepress preview website",
     "test:integration": "INTEGRATION=true jest --testPathPatterns=integration --testTimeout=60000 --coverage=false",
-    "sync:translations": "node scripts/sync-demo-translations.mjs"
+    "sync:translations": "node scripts/sync-demo-translations.mjs",
+    "changelog:preview": "node scripts/changelog-preview.mjs"
   },
   "keywords": [
     "google-sheets",