@el-j/google-sheet-translations 2.1.2 → 2.1.3

package/dist/esm/index.js

@@ -521,6 +521,7 @@ function findLocalChanges(localData, spreadsheetData) {
 }
 
 // src/utils/spreadsheetUpdater.ts
+import { setTimeout as delay2 } from "node:timers/promises";
 function columnIndexToLetter(index) {
   let result = "";
   let i = index;
@@ -530,6 +531,9 @@ function columnIndexToLetter(index) {
   } while (i >= 0);
   return result;
 }
+function langCodeFormula(cellRef) {
+  return `LOWER(IFERROR(LEFT(${cellRef},FIND("-",${cellRef})-1),${cellRef}))`;
+}
 async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, autoTranslate = false, localeMapping = {}, override = false) {
   console.log("Updating spreadsheet with local changes...");
   const baseDelayMs = waitSeconds * 1e3;
@@ -676,7 +680,7 @@ async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, auto
                     const targetColumnLetter = columnIndexToLetter(targetHeaderIndex);
                     row.set(
                       exactTargetHeader,
-                      `=GOOGLETRANSLATE(INDIRECT("${sourceColumnLetter}"&ROW());$${sourceColumnLetter}$1;${targetColumnLetter}$1)`
+                      `=GOOGLETRANSLATE(INDIRECT("${sourceColumnLetter}"&ROW());${langCodeFormula(`$${sourceColumnLetter}$1`)};${langCodeFormula(`${targetColumnLetter}$1`)})`
                     );
                   }
                 }
@@ -688,6 +692,9 @@ async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, auto
                 `save row ${rowIndex} in ${sheetTitle}`,
                 baseDelayMs
               );
+              if (baseDelayMs > 0) {
+                await delay2(baseDelayMs);
+              }
             } catch (err) {
               console.error(
                 `Failed to save row for key "${keyLower}" in sheet "${sheetTitle}":`,
@@ -722,7 +729,7 @@ async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, auto
                 }
                 const sourceColumnLetter = columnIndexToLetter(sourceHeaderIndex);
                 const targetColumnLetter = columnIndexToLetter(targetHeaderIndex);
-                rowData[exactHeaderName] = `=GOOGLETRANSLATE(INDIRECT("${sourceColumnLetter}"&ROW());$${sourceColumnLetter}$1;${targetColumnLetter}$1)`;
+                rowData[exactHeaderName] = `=GOOGLETRANSLATE(INDIRECT("${sourceColumnLetter}"&ROW());${langCodeFormula(`$${sourceColumnLetter}$1`)};${langCodeFormula(`${targetColumnLetter}$1`)})`;
               }
             }
           }
@@ -737,6 +744,9 @@ async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, auto
           `addRows chunk ${Math.floor(i / CHUNK_SIZE) + 1} in ${sheetTitle}`,
           baseDelayMs
         );
+        if (baseDelayMs > 0 && i + CHUNK_SIZE < newRows.length) {
+          await delay2(baseDelayMs);
+        }
       }
     }
   }
@@ -975,6 +985,9 @@ function colLetter(index) {
   } while (i >= 0);
   return result;
 }
+function langCodeFormula2(cellRef) {
+  return `LOWER(IFERROR(LEFT(${cellRef},FIND("-",${cellRef})-1),${cellRef}))`;
+}
 var DEFAULT_TARGET_LOCALES = ["de", "fr", "es", "it", "pt", "ja", "zh"];
 var STARTER_KEYS = {
   "app.name": "My App",
@@ -1059,7 +1072,7 @@ async function createSpreadsheet(authClient, options = {}) {
       const row = { key, [sourceLocale]: sourceValue };
       targetLocales.forEach((locale, idx) => {
         const targetColLetter = colLetter(2 + idx);
-        row[locale] = `=GOOGLETRANSLATE(INDIRECT("${sourceColLetter}"&ROW());$${sourceColLetter}$1;${targetColLetter}$1)`;
+        row[locale] = `=GOOGLETRANSLATE(INDIRECT("${sourceColLetter}"&ROW());${langCodeFormula2(`$${sourceColLetter}$1`)};${langCodeFormula2(`${targetColLetter}$1`)})`;
       });
       return row;
     });
@@ -1235,10 +1248,10 @@ async function getSpreadSheetData(_docTitle, options = {}, _refreshDepth = 0) {
 }
 
 // src/utils/wait.ts
-import { setTimeout as delay2 } from "node:timers/promises";
+import { setTimeout as delay3 } from "node:timers/promises";
 function wait(seconds, reason) {
   console.log("wait", seconds, reason);
-  return delay2(seconds * 1e3);
+  return delay3(seconds * 1e3);
 }
 
 // src/utils/translationHelpers.ts

package/dist/index.js

@@ -586,6 +586,7 @@ function findLocalChanges(localData, spreadsheetData) {
 }
 
 // src/utils/spreadsheetUpdater.ts
+var import_promises2 = require("node:timers/promises");
 function columnIndexToLetter(index) {
   let result = "";
   let i = index;
@@ -595,6 +596,9 @@ function columnIndexToLetter(index) {
   } while (i >= 0);
   return result;
 }
+function langCodeFormula(cellRef) {
+  return `LOWER(IFERROR(LEFT(${cellRef},FIND("-",${cellRef})-1),${cellRef}))`;
+}
 async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, autoTranslate = false, localeMapping = {}, override = false) {
   console.log("Updating spreadsheet with local changes...");
   const baseDelayMs = waitSeconds * 1e3;
@@ -741,7 +745,7 @@ async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, auto
                     const targetColumnLetter = columnIndexToLetter(targetHeaderIndex);
                     row.set(
                       exactTargetHeader,
-                      `=GOOGLETRANSLATE(INDIRECT("${sourceColumnLetter}"&ROW());$${sourceColumnLetter}$1;${targetColumnLetter}$1)`
+                      `=GOOGLETRANSLATE(INDIRECT("${sourceColumnLetter}"&ROW());${langCodeFormula(`$${sourceColumnLetter}$1`)};${langCodeFormula(`${targetColumnLetter}$1`)})`
                     );
                   }
                 }
@@ -753,6 +757,9 @@ async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, auto
                 `save row ${rowIndex} in ${sheetTitle}`,
                 baseDelayMs
               );
+              if (baseDelayMs > 0) {
+                await (0, import_promises2.setTimeout)(baseDelayMs);
+              }
             } catch (err) {
               console.error(
                 `Failed to save row for key "${keyLower}" in sheet "${sheetTitle}":`,
@@ -787,7 +794,7 @@ async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, auto
                 }
                 const sourceColumnLetter = columnIndexToLetter(sourceHeaderIndex);
                 const targetColumnLetter = columnIndexToLetter(targetHeaderIndex);
-                rowData[exactHeaderName] = `=GOOGLETRANSLATE(INDIRECT("${sourceColumnLetter}"&ROW());$${sourceColumnLetter}$1;${targetColumnLetter}$1)`;
+                rowData[exactHeaderName] = `=GOOGLETRANSLATE(INDIRECT("${sourceColumnLetter}"&ROW());${langCodeFormula(`$${sourceColumnLetter}$1`)};${langCodeFormula(`${targetColumnLetter}$1`)})`;
               }
             }
           }
@@ -802,6 +809,9 @@ async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, auto
           `addRows chunk ${Math.floor(i / CHUNK_SIZE) + 1} in ${sheetTitle}`,
           baseDelayMs
         );
+        if (baseDelayMs > 0 && i + CHUNK_SIZE < newRows.length) {
+          await (0, import_promises2.setTimeout)(baseDelayMs);
+        }
       }
     }
   }
@@ -1040,6 +1050,9 @@ function colLetter(index) {
   } while (i >= 0);
   return result;
 }
+function langCodeFormula2(cellRef) {
+  return `LOWER(IFERROR(LEFT(${cellRef},FIND("-",${cellRef})-1),${cellRef}))`;
+}
 var DEFAULT_TARGET_LOCALES = ["de", "fr", "es", "it", "pt", "ja", "zh"];
 var STARTER_KEYS = {
   "app.name": "My App",
@@ -1124,7 +1137,7 @@ async function createSpreadsheet(authClient, options = {}) {
       const row = { key, [sourceLocale]: sourceValue };
       targetLocales.forEach((locale, idx) => {
         const targetColLetter = colLetter(2 + idx);
-        row[locale] = `=GOOGLETRANSLATE(INDIRECT("${sourceColLetter}"&ROW());$${sourceColLetter}$1;${targetColLetter}$1)`;
+        row[locale] = `=GOOGLETRANSLATE(INDIRECT("${sourceColLetter}"&ROW());${langCodeFormula2(`$${sourceColLetter}$1`)};${langCodeFormula2(`${targetColLetter}$1`)})`;
       });
       return row;
     });
@@ -1300,10 +1313,10 @@ async function getSpreadSheetData(_docTitle, options = {}, _refreshDepth = 0) {
 }
 
 // src/utils/wait.ts
-var import_promises2 = require("node:timers/promises");
+var import_promises3 = require("node:timers/promises");
 function wait(seconds, reason) {
   console.log("wait", seconds, reason);
-  return (0, import_promises2.setTimeout)(seconds * 1e3);
+  return (0, import_promises3.setTimeout)(seconds * 1e3);
 }
 
 // src/utils/translationHelpers.ts

package/dist/utils/configurationHandler.d.ts

@@ -4,9 +4,10 @@
 export interface SpreadsheetOptions {
     rowLimit?: number;
     /**
-     * Base back-off delay in seconds used when retrying Google Sheets API
-     * calls that fail with a rate-limit response (HTTP 429 / 503).
-     * The actual delay for each retry attempt is `waitSeconds * 2^attempt`,
+     * Seconds to wait between consecutive Google Sheets write API calls
+     * (proactive throttle) and as the base back-off delay when retrying calls
+     * that fail with a rate-limit response (HTTP 429 / 503).
+     * The actual retry delay for each attempt is `waitSeconds * 2^attempt`,
      * capped at 30 seconds.  Defaults to 1.
      */
     waitSeconds?: number;

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;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"}
+{"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;;;;;;OAMG;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/spreadsheetCreator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spreadsheetCreator.d.ts","sourceRoot":"","sources":["../../src/utils/spreadsheetCreator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAiB/C,MAAM,WAAW,wBAAwB;IACxC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mGAAmG;IACnG,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACZ;AAiBD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACtC,UAAU,EAAE,GAAG,EACf,OAAO,GAAE,wBAA6B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CA8GjC"}
+{"version":3,"file":"spreadsheetCreator.d.ts","sourceRoot":"","sources":["../../src/utils/spreadsheetCreator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AA8B/C,MAAM,WAAW,wBAAwB;IACxC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mGAAmG;IACnG,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACZ;AAiBD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACtC,UAAU,EAAE,GAAG,EACf,OAAO,GAAE,wBAA6B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAgHjC"}

package/dist/utils/spreadsheetUpdater.d.ts

@@ -6,11 +6,18 @@ import type { TranslationData } from "../types";
  * When autoTranslate is enabled:
  * - For each new key added to the spreadsheet, the system checks which languages have translations
  * - For languages missing translations, it automatically adds Google Translate formulas
- * - The formula format is: =GOOGLETRANSLATE(INDIRECT(sourceColumn&ROW());$sourceColumn$1;targetColumn$1)
+ * - The formula extracts the language prefix from the header cell (e.g. "tr-TR" → "tr") because
+ *   GOOGLETRANSLATE only accepts ISO 639-1 codes for most languages
+ * - The formula format is:
+ *   =GOOGLETRANSLATE(INDIRECT(sourceColumn&ROW());LOWER(IFERROR(LEFT($sourceColumn$1,FIND("-",$sourceColumn$1)-1),$sourceColumn$1));LOWER(IFERROR(LEFT(targetColumn$1,FIND("-",targetColumn$1)-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.
  *
+ * A proactive inter-request delay of `waitSeconds` seconds is inserted between each
+ * individual row save and between each addRows chunk to avoid exceeding Google's
+ * "Write requests per minute per user" quota before a 429 is even returned.
+ *
  * 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
  * the original locale-header names from `localeMapping`.  This ensures that new feature sheets
@@ -18,12 +25,13 @@ import type { TranslationData } from "../types";
  *
  * Example:
  * If a new key "welcome" has an English translation in column B but no German translation in column C,
- * and autoTranslate is enabled, the system will add:
- * =GOOGLETRANSLATE(INDIRECT("B"&ROW());$B$1;C$1) to the German column
+ * and autoTranslate is enabled, the system will add a formula that translates from English ("en")
+ * to the language code extracted from the German column header to the German column.
  *
  * @param doc - The Google Spreadsheet instance
  * @param changes - Object containing new keys to add to the spreadsheet
- * @param waitSeconds - Base back-off delay in seconds for retrying rate-limited API calls
+ * @param waitSeconds - Seconds to wait between consecutive write API calls (throttle) and as the
+ *   base back-off delay when retrying rate-limited calls (HTTP 429/503).  Must be ≥ 1.
  * @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

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"spreadsheetUpdater.d.ts","sourceRoot":"","sources":["../../src/utils/spreadsheetUpdater.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAA8B,MAAM,oBAAoB,CAAC;AACxF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAiChD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;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,CAiVf"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@el-j/google-sheet-translations",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "description": "A package to manage translations stored in Google Spreadsheets",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",