@el-j/google-sheet-translations 2.0.1 → 2.1.0

package/dist/action-entrypoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-entrypoint.d.ts","sourceRoot":"","sources":["../src/action-entrypoint.ts"],"names":[],"mappings":"AAKA,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CA6DzC"}
+{"version":3,"file":"action-entrypoint.d.ts","sourceRoot":"","sources":["../src/action-entrypoint.ts"],"names":[],"mappings":"AAKA,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CA+DzC"}

package/dist/esm/index.js

@@ -80,7 +80,11 @@ function normalizeConfig(options = {}) {
     // Default to true
     spreadsheetTitle: options.spreadsheetTitle ?? "google-sheet-translations",
     sourceLocale: options.sourceLocale ?? "en",
-    targetLocales: options.targetLocales ?? ["de", "fr", "es", "it", "pt", "ja", "zh"]
+    targetLocales: options.targetLocales ?? ["de", "fr", "es", "it", "pt", "ja", "zh"],
+    override: options.override === true,
+    // Default to false
+    cleanPush: options.cleanPush === true
+    // Default to false
   };
 }
 
@@ -529,7 +533,7 @@ function columnIndexToLetter(index) {
   } while (i >= 0);
   return result;
 }
-async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, autoTranslate = false, localeMapping = {}) {
+async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, autoTranslate = false, localeMapping = {}, override = false) {
   console.log("Updating spreadsheet with local changes...");
   const baseDelayMs = waitSeconds * 1e3;
   for (const sheetTitle of new Set(
@@ -589,6 +593,27 @@ async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, auto
     });
     const newKeys = /* @__PURE__ */ new Map();
     const keyLocalesMap = /* @__PURE__ */ new Map();
+    const pushedLocaleHeadersPerKey = /* @__PURE__ */ new Map();
+    if (autoTranslate) {
+      for (const pushedLocale of Object.keys(changes)) {
+        if (!changes[pushedLocale]?.[sheetTitle]) continue;
+        for (const pushedKey of Object.keys(changes[pushedLocale][sheetTitle])) {
+          const pushedKeyLower = pushedKey.toLowerCase();
+          if (!existingKeys.has(pushedKeyLower)) continue;
+          let pushedHeader = getOriginalHeaderForLocale(pushedLocale, localeMapping);
+          if (!pushedHeader) {
+            const prefix = getLanguagePrefix(pushedLocale);
+            pushedHeader = originalHeaders.find((h) => getLanguagePrefix(h) === prefix);
+          }
+          if (pushedHeader) {
+            if (!pushedLocaleHeadersPerKey.has(pushedKeyLower)) {
+              pushedLocaleHeadersPerKey.set(pushedKeyLower, /* @__PURE__ */ new Set());
+            }
+            pushedLocaleHeadersPerKey.get(pushedKeyLower).add(pushedHeader.toLowerCase());
+          }
+        }
+      }
+    }
     for (const locale of Object.keys(changes)) {
       if (!changes[locale]?.[sheetTitle]) continue;
       const localeData = changes[locale][sheetTitle];
@@ -631,6 +656,35 @@ async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, auto
           }
           if (localeHeader) {
             row.set(localeHeader, String(localeData[key]));
+            if (autoTranslate) {
+              const sourceHeaderLower = localeHeader.toLowerCase();
+              const sourceHeaderIndex = headerRow.indexOf(sourceHeaderLower);
+              if (sourceHeaderIndex >= 0) {
+                const sourceColumnLetter = columnIndexToLetter(sourceHeaderIndex);
+                const rowObj = row.toObject();
+                const pushedHeaders = pushedLocaleHeadersPerKey.get(keyLower) ?? /* @__PURE__ */ new Set();
+                for (const targetLocaleHeader of locales) {
+                  const targetLower = targetLocaleHeader.toLowerCase();
+                  if (targetLower === sourceHeaderLower) continue;
+                  if (pushedHeaders.has(targetLower)) continue;
+                  const targetHeaderIndex = headerRow.indexOf(targetLower);
+                  if (targetHeaderIndex < 0) continue;
+                  const exactTargetHeader = originalHeaders.find(
+                    (h) => h.toLowerCase() === targetLower
+                  );
+                  if (!exactTargetHeader) continue;
+                  const existingValue = rowObj[exactTargetHeader];
+                  const isEmpty = !existingValue || existingValue.toString().trim() === "";
+                  if (isEmpty || override) {
+                    const targetColumnLetter = columnIndexToLetter(targetHeaderIndex);
+                    row.set(
+                      exactTargetHeader,
+                      `=GOOGLETRANSLATE(INDIRECT("${sourceColumnLetter}"&ROW());$${sourceColumnLetter}$1;${targetColumnLetter}$1)`
+                    );
+                  }
+                }
+              }
+            }
             try {
               await withRetry(
                 () => row.save(),
@@ -779,19 +833,23 @@ function readDataJson(dataJsonPath) {
 }
 
 // src/utils/syncManager.ts
-async function handleBidirectionalSync(doc, dataJsonPath, translationsOutputDir, syncLocalChanges, autoTranslate, spreadsheetData, waitSeconds, localeMapping = {}) {
+async function handleBidirectionalSync(doc, dataJsonPath, translationsOutputDir, syncLocalChanges, autoTranslate, spreadsheetData, waitSeconds, localeMapping = {}, override = false, cleanPush = false) {
   const result = {
     shouldRefresh: false,
     hasChanges: false
   };
   const localData = readDataJson(dataJsonPath);
   const dataJsonExists = localData !== null;
-  const shouldSyncToSheet = syncLocalChanges && dataJsonExists && isDataJsonNewer(dataJsonPath, translationsOutputDir);
+  const shouldSyncToSheet = dataJsonExists && (cleanPush || syncLocalChanges && isDataJsonNewer(dataJsonPath, translationsOutputDir));
   if (!shouldSyncToSheet || !localData) {
     return result;
   }
-  console.log("Local languageData.json is newer than translation files. Checking for changes...");
-  const changes = findLocalChanges(localData, spreadsheetData);
+  if (cleanPush) {
+    console.log("Clean push enabled \u2013 pushing ALL keys from languageData.json to the spreadsheet...");
+  } else {
+    console.log("Local languageData.json is newer than translation files. Checking for changes...");
+  }
+  const changes = cleanPush ? localData : findLocalChanges(localData, spreadsheetData);
   const hasChanges = Object.keys(changes).length > 0 && Object.keys(changes).some(
     (locale) => Object.keys(changes[locale]).length > 0
   );
@@ -801,9 +859,10 @@ async function handleBidirectionalSync(doc, dataJsonPath, translationsOutputDir,
   }
   const localesCount = Object.keys(changes).length;
   const keysCount = Object.values(changes).flatMap((l) => Object.values(l)).flatMap((s) => Object.keys(s)).length;
-  console.log(`Found local changes: ${localesCount} locale(s), ~${keysCount} key(s) to sync to the spreadsheet.`);
+  const pushMode = cleanPush ? "clean push" : "incremental sync";
+  console.log(`Found local changes (${pushMode}): ${localesCount} locale(s), ~${keysCount} key(s) to sync to the spreadsheet.`);
   try {
-    await updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, autoTranslate, localeMapping);
+    await updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, autoTranslate, localeMapping, override);
     result.shouldRefresh = true;
     result.hasChanges = true;
   } catch (err) {
@@ -1132,7 +1191,9 @@ async function getSpreadSheetData(_docTitle, options = {}, _refreshDepth = 0) {
       config.autoTranslate,
       finalTranslations,
       config.waitSeconds,
-      globalLocaleMapping
+      globalLocaleMapping,
+      config.override,
+      config.cleanPush
     );
     if (syncResult.shouldRefresh && _refreshDepth < MAX_SYNC_REFRESH_DEPTH) {
       return getSpreadSheetData(

package/dist/getSpreadSheetData.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getSpreadSheetData.d.ts","sourceRoot":"","sources":["../src/getSpreadSheetData.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,EAAmB,KAAK,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAOxF,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAsChC,wBAAsB,kBAAkB,CACvC,SAAS,CAAC,EAAE,MAAM,EAAE,EACpB,OAAO,GAAE,kBAAuB,EAChC,aAAa,SAAI,GACf,OAAO,CAAC,eAAe,CAAC,CAyJ1B;AAED,eAAe,kBAAkB,CAAC"}
+{"version":3,"file":"getSpreadSheetData.d.ts","sourceRoot":"","sources":["../src/getSpreadSheetData.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,EAAmB,KAAK,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAOxF,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAsChC,wBAAsB,kBAAkB,CACvC,SAAS,CAAC,EAAE,MAAM,EAAE,EACpB,OAAO,GAAE,kBAAuB,EAChC,aAAa,SAAI,GACf,OAAO,CAAC,eAAe,CAAC,CA2J1B;AAED,eAAe,kBAAkB,CAAC"}

package/dist/index.js

@@ -145,7 +145,11 @@ function normalizeConfig(options = {}) {
     // Default to true
     spreadsheetTitle: options.spreadsheetTitle ?? "google-sheet-translations",
     sourceLocale: options.sourceLocale ?? "en",
-    targetLocales: options.targetLocales ?? ["de", "fr", "es", "it", "pt", "ja", "zh"]
+    targetLocales: options.targetLocales ?? ["de", "fr", "es", "it", "pt", "ja", "zh"],
+    override: options.override === true,
+    // Default to false
+    cleanPush: options.cleanPush === true
+    // Default to false
   };
 }
 
@@ -594,7 +598,7 @@ function columnIndexToLetter(index) {
   } while (i >= 0);
   return result;
 }
-async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, autoTranslate = false, localeMapping = {}) {
+async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, autoTranslate = false, localeMapping = {}, override = false) {
   console.log("Updating spreadsheet with local changes...");
   const baseDelayMs = waitSeconds * 1e3;
   for (const sheetTitle of new Set(
@@ -654,6 +658,27 @@ async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, auto
     });
     const newKeys = /* @__PURE__ */ new Map();
     const keyLocalesMap = /* @__PURE__ */ new Map();
+    const pushedLocaleHeadersPerKey = /* @__PURE__ */ new Map();
+    if (autoTranslate) {
+      for (const pushedLocale of Object.keys(changes)) {
+        if (!changes[pushedLocale]?.[sheetTitle]) continue;
+        for (const pushedKey of Object.keys(changes[pushedLocale][sheetTitle])) {
+          const pushedKeyLower = pushedKey.toLowerCase();
+          if (!existingKeys.has(pushedKeyLower)) continue;
+          let pushedHeader = getOriginalHeaderForLocale(pushedLocale, localeMapping);
+          if (!pushedHeader) {
+            const prefix = getLanguagePrefix(pushedLocale);
+            pushedHeader = originalHeaders.find((h) => getLanguagePrefix(h) === prefix);
+          }
+          if (pushedHeader) {
+            if (!pushedLocaleHeadersPerKey.has(pushedKeyLower)) {
+              pushedLocaleHeadersPerKey.set(pushedKeyLower, /* @__PURE__ */ new Set());
+            }
+            pushedLocaleHeadersPerKey.get(pushedKeyLower).add(pushedHeader.toLowerCase());
+          }
+        }
+      }
+    }
     for (const locale of Object.keys(changes)) {
       if (!changes[locale]?.[sheetTitle]) continue;
       const localeData = changes[locale][sheetTitle];
@@ -696,6 +721,35 @@ async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, auto
           }
           if (localeHeader) {
             row.set(localeHeader, String(localeData[key]));
+            if (autoTranslate) {
+              const sourceHeaderLower = localeHeader.toLowerCase();
+              const sourceHeaderIndex = headerRow.indexOf(sourceHeaderLower);
+              if (sourceHeaderIndex >= 0) {
+                const sourceColumnLetter = columnIndexToLetter(sourceHeaderIndex);
+                const rowObj = row.toObject();
+                const pushedHeaders = pushedLocaleHeadersPerKey.get(keyLower) ?? /* @__PURE__ */ new Set();
+                for (const targetLocaleHeader of locales) {
+                  const targetLower = targetLocaleHeader.toLowerCase();
+                  if (targetLower === sourceHeaderLower) continue;
+                  if (pushedHeaders.has(targetLower)) continue;
+                  const targetHeaderIndex = headerRow.indexOf(targetLower);
+                  if (targetHeaderIndex < 0) continue;
+                  const exactTargetHeader = originalHeaders.find(
+                    (h) => h.toLowerCase() === targetLower
+                  );
+                  if (!exactTargetHeader) continue;
+                  const existingValue = rowObj[exactTargetHeader];
+                  const isEmpty = !existingValue || existingValue.toString().trim() === "";
+                  if (isEmpty || override) {
+                    const targetColumnLetter = columnIndexToLetter(targetHeaderIndex);
+                    row.set(
+                      exactTargetHeader,
+                      `=GOOGLETRANSLATE(INDIRECT("${sourceColumnLetter}"&ROW());$${sourceColumnLetter}$1;${targetColumnLetter}$1)`
+                    );
+                  }
+                }
+              }
+            }
             try {
               await withRetry(
                 () => row.save(),
@@ -844,19 +898,23 @@ function readDataJson(dataJsonPath) {
 }
 
 // src/utils/syncManager.ts
-async function handleBidirectionalSync(doc, dataJsonPath, translationsOutputDir, syncLocalChanges, autoTranslate, spreadsheetData, waitSeconds, localeMapping = {}) {
+async function handleBidirectionalSync(doc, dataJsonPath, translationsOutputDir, syncLocalChanges, autoTranslate, spreadsheetData, waitSeconds, localeMapping = {}, override = false, cleanPush = false) {
   const result = {
     shouldRefresh: false,
     hasChanges: false
   };
   const localData = readDataJson(dataJsonPath);
   const dataJsonExists = localData !== null;
-  const shouldSyncToSheet = syncLocalChanges && dataJsonExists && isDataJsonNewer(dataJsonPath, translationsOutputDir);
+  const shouldSyncToSheet = dataJsonExists && (cleanPush || syncLocalChanges && isDataJsonNewer(dataJsonPath, translationsOutputDir));
   if (!shouldSyncToSheet || !localData) {
     return result;
   }
-  console.log("Local languageData.json is newer than translation files. Checking for changes...");
-  const changes = findLocalChanges(localData, spreadsheetData);
+  if (cleanPush) {
+    console.log("Clean push enabled \u2013 pushing ALL keys from languageData.json to the spreadsheet...");
+  } else {
+    console.log("Local languageData.json is newer than translation files. Checking for changes...");
+  }
+  const changes = cleanPush ? localData : findLocalChanges(localData, spreadsheetData);
   const hasChanges = Object.keys(changes).length > 0 && Object.keys(changes).some(
     (locale) => Object.keys(changes[locale]).length > 0
   );
@@ -866,9 +924,10 @@ async function handleBidirectionalSync(doc, dataJsonPath, translationsOutputDir,
   }
   const localesCount = Object.keys(changes).length;
   const keysCount = Object.values(changes).flatMap((l) => Object.values(l)).flatMap((s) => Object.keys(s)).length;
-  console.log(`Found local changes: ${localesCount} locale(s), ~${keysCount} key(s) to sync to the spreadsheet.`);
+  const pushMode = cleanPush ? "clean push" : "incremental sync";
+  console.log(`Found local changes (${pushMode}): ${localesCount} locale(s), ~${keysCount} key(s) to sync to the spreadsheet.`);
   try {
-    await updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, autoTranslate, localeMapping);
+    await updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, autoTranslate, localeMapping, override);
     result.shouldRefresh = true;
     result.hasChanges = true;
   } catch (err) {
@@ -1197,7 +1256,9 @@ async function getSpreadSheetData(_docTitle, options = {}, _refreshDepth = 0) {
       config.autoTranslate,
       finalTranslations,
       config.waitSeconds,
-      globalLocaleMapping
+      globalLocaleMapping,
+      config.override,
+      config.cleanPush
     );
     if (syncResult.shouldRefresh && _refreshDepth < MAX_SYNC_REFRESH_DEPTH) {
       return getSpreadSheetData(

package/dist/utils/configurationHandler.d.ts

@@ -47,6 +47,23 @@ export interface SpreadsheetOptions {
      * Default: ['de', 'fr', 'es', 'it', 'pt', 'ja', 'zh'].
      */
     targetLocales?: string[];
+    /**
+     * When `true`, existing translations in other language columns are overwritten
+     * with GOOGLETRANSLATE formulas when `autoTranslate` is also enabled and keys
+     * are pushed.  When `false` (the default), only **empty** cells receive a
+     * formula – cells that already contain a translation are left untouched.
+     */
+    override?: boolean;
+    /**
+     * When `true`, **all** keys from the local `languageData.json` are pushed to
+     * the spreadsheet – including keys that already exist there.  This is useful
+     * when the file has been copied from another project and the spreadsheet needs
+     * a complete refresh.  The file-timestamp guard (`isDataJsonNewer`) is
+     * bypassed.  Whether existing cell values are overwritten depends on the usual
+     * `override` + `autoTranslate` flags.  Implies `syncLocalChanges`.
+     * Default: `false`.
+     */
+    cleanPush?: boolean;
 }
 /**
  * Normalized configuration with all defaults applied
@@ -65,6 +82,8 @@ export interface NormalizedConfig {
     spreadsheetTitle: string;
     sourceLocale: string;
     targetLocales: string[];
+    override: boolean;
+    cleanPush: boolean;
 }
 /**
  * Normalizes configuration options by applying defaults

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

@@ -1 +1 @@
-{"version":3,"file":"configurationHandler.d.ts","sourceRoot":"","sources":["../../src/utils/configurationHandler.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,kBAAuB,GAAG,gBAAgB,CAgBlF"}
+{"version":3,"file":"configurationHandler.d.ts","sourceRoot":"","sources":["../../src/utils/configurationHandler.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,kBAAuB,GAAG,gBAAgB,CAkBlF"}

package/dist/utils/spreadsheetUpdater.d.ts

@@ -8,6 +8,8 @@ import type { TranslationData } from "../types";
  * - For languages missing translations, it automatically adds Google Translate formulas
  * - The formula format is: =GOOGLETRANSLATE(INDIRECT(sourceColumn&ROW());$sourceColumn$1;targetColumn$1)
  * - This dynamic formula uses cell references for language codes and automatically adapts to the correct row
+ * - For **existing** keys the same logic applies: empty cells in other language columns receive a
+ *   formula; cells that already contain a translation are only overwritten when `override` is true.
  *
  * If a sheet named `sheetTitle` does not yet exist in the document and `localeMapping` is
  * non-empty, the sheet is **created automatically** with "key" as the first column followed by
@@ -24,7 +26,10 @@ import type { TranslationData } from "../types";
  * @param waitSeconds - Base back-off delay in seconds for retrying rate-limited API calls
  * @param autoTranslate - Whether to add Google Translate formulas for missing translations (default: false)
  * @param localeMapping - Mapping from normalized locale codes to original spreadsheet headers
+ * @param override - When true AND autoTranslate is true, existing translations in other language
+ *   columns are overwritten with GOOGLETRANSLATE formulas.  When false (default) only empty cells
+ *   receive a formula.
  * @returns Promise that resolves when the update is complete
  */
-export declare function updateSpreadsheetWithLocalChanges(doc: GoogleSpreadsheet, changes: TranslationData, waitSeconds: number, autoTranslate?: boolean, localeMapping?: Record<string, string>): Promise<void>;
+export declare function updateSpreadsheetWithLocalChanges(doc: GoogleSpreadsheet, changes: TranslationData, waitSeconds: number, autoTranslate?: boolean, localeMapping?: Record<string, string>, override?: boolean): Promise<void>;
 //# sourceMappingURL=spreadsheetUpdater.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"spreadsheetUpdater.d.ts","sourceRoot":"","sources":["../../src/utils/spreadsheetUpdater.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAA8B,MAAM,oBAAoB,CAAC;AACxF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAgBhD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,iCAAiC,CACnD,GAAG,EAAE,iBAAiB,EACtB,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,MAAM,EACnB,aAAa,UAAQ,EACrB,aAAa,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAC3C,OAAO,CAAC,IAAI,CAAC,CA4Pf"}
+{"version":3,"file":"spreadsheetUpdater.d.ts","sourceRoot":"","sources":["../../src/utils/spreadsheetUpdater.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAA8B,MAAM,oBAAoB,CAAC;AACxF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAgBhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,iCAAiC,CACnD,GAAG,EAAE,iBAAiB,EACtB,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,MAAM,EACnB,aAAa,UAAQ,EACrB,aAAa,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EAC1C,QAAQ,UAAQ,GACjB,OAAO,CAAC,IAAI,CAAC,CAsUf"}

package/dist/utils/syncManager.d.ts

@@ -17,7 +17,9 @@ export interface SyncResult {
  * @param spreadsheetData Current data from the spreadsheet
  * @param waitSeconds Time to wait between API calls
  * @param localeMapping Mapping from normalized locale codes to original spreadsheet headers
+ * @param override When true AND autoTranslate is true, overwrite existing translations with formulas
+ * @param cleanPush When true, push ALL keys from localData (bypasses timestamp guard and diff)
  * @returns Sync operation result
  */
-export declare function handleBidirectionalSync(doc: GoogleSpreadsheet, dataJsonPath: string, translationsOutputDir: string, syncLocalChanges: boolean, autoTranslate: boolean, spreadsheetData: TranslationData, waitSeconds: number, localeMapping?: Record<string, string>): Promise<SyncResult>;
+export declare function handleBidirectionalSync(doc: GoogleSpreadsheet, dataJsonPath: string, translationsOutputDir: string, syncLocalChanges: boolean, autoTranslate: boolean, spreadsheetData: TranslationData, waitSeconds: number, localeMapping?: Record<string, string>, override?: boolean, cleanPush?: boolean): Promise<SyncResult>;
 //# sourceMappingURL=syncManager.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"syncManager.d.ts","sourceRoot":"","sources":["../../src/utils/syncManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAMhD;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAC5C,GAAG,EAAE,iBAAiB,EACtB,YAAY,EAAE,MAAM,EACpB,qBAAqB,EAAE,MAAM,EAC7B,gBAAgB,EAAE,OAAO,EACzB,aAAa,EAAE,OAAO,EACtB,eAAe,EAAE,eAAe,EAChC,WAAW,EAAE,MAAM,EACnB,aAAa,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACxC,OAAO,CAAC,UAAU,CAAC,CAoDrB"}
+{"version":3,"file":"syncManager.d.ts","sourceRoot":"","sources":["../../src/utils/syncManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAMhD;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,uBAAuB,CAC5C,GAAG,EAAE,iBAAiB,EACtB,YAAY,EAAE,MAAM,EACpB,qBAAqB,EAAE,MAAM,EAC7B,gBAAgB,EAAE,OAAO,EACzB,aAAa,EAAE,OAAO,EACtB,eAAe,EAAE,eAAe,EAChC,WAAW,EAAE,MAAM,EACnB,aAAa,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EAC1C,QAAQ,UAAQ,EAChB,SAAS,UAAQ,GACf,OAAO,CAAC,UAAU,CAAC,CA4DrB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@el-j/google-sheet-translations",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "A package to manage translations stored in Google Spreadsheets",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",
@@ -75,10 +75,10 @@
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.4.0",
+    "@types/node": "^25.5.0",
     "@typescript-eslint/eslint-plugin": "^8.57.0",
     "@typescript-eslint/parser": "^8.57.0",
-    "esbuild": "^0.26.0",
+    "esbuild": "^0.27.4",
     "conventional-changelog-conventionalcommits": "^9.3.0",
     "dotenv": "17.3.1",
     "eslint": "^10.0.3",