@el-j/google-sheet-translations 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+# Google Sheet Translations
+
+A Node.js package for managing translations stored in Google Sheets.
+
+## Features
+
+- ✅ **Bidirectional Sync**: Sync changes from local files back to Google Sheets
+- ✅ **Auto-Translation**: Automatic Google Translate formula generation for missing translations
+- ✅ **Smart Locale Filtering**: Only locales with actual translations in content sheets are included in output files
+- ✅ **TypeScript Support**: Full TypeScript definitions included
+- ✅ **Modular Architecture**: Well-tested, maintainable codebase with clear separation of concerns
+- ✅ **Next.js Integration**: Built-in support for Next.js static export workflows
+- ✅ **Flexible Configuration**: Customizable paths, wait times, and processing options
+
+## Installation
+
+```bash
+npm install @el-j/google-sheet-translations
+```
+
+## Prepare Google Spreadsheet
+1. Create Google Spreadsheet(s) with the following structure:
+   - **First Row**: Header Row with Key | [language(-country)] | [language(-country)] | ... 
+   - **Subsequent Rows**: Translation Rows with Key used as variable name and corresponding translations.
+   
+2. Auto-translation for missing translations can be managed in two ways:
+   - Manually, by using the `=GOOGLETRANSLATE()` function in the spreadsheet
+   - Automatically, by enabling the `autoTranslate` option when using this package (see API Reference)
+
+## Environment Variables
+
+Make sure to set the following environment variables:
+
+- `GOOGLE_CLIENT_EMAIL`: Your Google service account email
+- `GOOGLE_PRIVATE_KEY`: Your Google service account private key
+- `GOOGLE_SPREADSHEET_ID`: ID of the Google Spreadsheet containing translations
+
+## Usage
+
+```typescript
+import { getSpreadSheetData, validateEnv } from '@el-j/google-sheet-translations';
+
+// Ensure environment variables are set
+validateEnv();
+
+// Fetch translations
+async function fetchTranslations() {
+  try {
+    const translations = await getSpreadSheetData(
+      ['sheet1', 'sheet2'], // Array of sheet names to process
+      {
+        rowLimit: 100, // Optional: rowLimit parameter (default is 100)
+        waitSeconds: 3, // Optional: Time to wait between API calls (default is 1)
+        dataJsonPath: 'path/to/languageData.json', // Optional: Custom path for languageData.json
+        localesOutputPath: 'path/to/locales.ts', // Optional: Custom path for locales.ts
+        translationsOutputDir: 'path/to/translations', // Optional: Custom translations output directory
+      }
+    );
+
+    console.log('Translations fetched successfully');
+  } catch (error) {
+    console.error('Error fetching translations:', error);
+  }
+}
+
+fetchTranslations();
+```
+
+### Usage with NEXTJS 
+
+for nextjs, you can use the package in your `instrumentation.ts` file. This is useful for pre-fetching translations during the build process
+and storing them in a JSON file. Practically for `static:export` in `next build`
+
+```typescript:instrumentation.ts
+export async function register() {
+	if (process.env.NEXT_RUNTIME === "nodejs") {
+		const getData = await import("@el-j/google-sheet-translations");
+		await getData.getSpreadSheetData(["Index"]);
+		console.log("register done");
+	}
+}
+```
+
+read more [internationalization with nextjs](https://nextjs.org/docs/pages/building-your-application/routing/internationalization)
+
+## API Reference
+
+### `getSpreadSheetData(sheetTitles?, options?)`
+
+Fetches and processes data from a Google Spreadsheet.
+
+#### Parameters
+
+- `sheetTitles`: (Optional) Array of sheet titles to process. If not provided, only the "i18n" sheet will be processed.
+- `options`: (Optional) Configuration object
+  - `rowLimit`: Number - Maximum number of rows to fetch (default: 100)
+  - `waitSeconds`: Number - Time to wait between API calls (default: 1)
+  - `dataJsonPath`: String - Path for languageData.json file (default: 'src/lib/languageData.json')
+  - `localesOutputPath`: String - Path for locales.ts file (default: 'src/i18n/locales.ts')
+  - `translationsOutputDir`: String - Directory for translations output (default: 'translations')
+  - `syncLocalChanges`: Boolean - Whether to sync local changes back to the spreadsheet (default: true)
+  - `autoTranslate`: Boolean - Whether to auto-generate Google Translate formulas for missing translations (default: false)
+
+#### Returns
+
+A Promise resolving to the processed translation data object.
+
+### `validateEnv()`
+
+Validates that all required environment variables are set.
+
+#### Returns
+
+An object containing the validated environment variables.
+
+#### Throws
+
+Error if any required environment variable is missing.
+
+## Locale Filtering
+
+The package includes intelligent locale filtering to ensure only valid locale identifiers with actual translation content are included in the generated `locales.ts` file. 
+
+### Smart Content-Based Filtering
+
+The `locales.ts` file will **only include locales that have actual translations in non-i18n sheets**. This means:
+
+- ✅ Locales with translations in content sheets (like 'home', 'products', etc.) are included
+- ❌ Locales that only exist in the 'i18n' configuration sheet are excluded
+- ❌ Locales with empty translations in content sheets are excluded
+- ❌ Common spreadsheet column names are filtered out
+
+**Example:**
+```
+Spreadsheet structure:
+- Sheet "content": key | en | de | fr | es
+  - Row: "welcome" | "Welcome" | "Willkommen" | "" | ""
+- Sheet "i18n": key | en | de | fr | es  
+  - Row: "config" | "Config" | "Konfiguration" | "Configuration" | "Configuración"
+
+Result: locales.ts will only contain ["en", "de"]
+```
+
+This ensures your application only includes locales that have meaningful content for users.
+
+### Supported Locale Formats
+
+- Two-letter language codes: `en`, `de`, `fr`, `ja`
+- Language-country codes with hyphens: `en-us`, `de-de`, `fr-ca`
+- Language-country codes with underscores: `en_us`, `de_de`, `zh_cn`
+- Extended locale codes: `en-us-traditional`, `zh-cn-simplified`
+
+### Filtered Keywords
+
+The following common spreadsheet column names are automatically filtered out:
+- `key`, `keys`, `id`, `identifier`, `name`, `title`, `label`
+- `description`, `comment`, `note`, `context`, `category`, `type`
+- `status`, `updated`, `created`, `modified`, `version`, `source`
+- `i18n`, `translation`, `namespace`, `section`
+
+## Additional Utilities
+
+The package exports several utility functions that can be used independently:
+
+```typescript
+import { 
+  validateEnv,
+  isValidLocale,
+  filterValidLocales,
+  normalizeConfig,
+  processSheet,
+  writeTranslationFiles,
+  convertToDataJsonFormat,
+  convertFromDataJsonFormat,
+  findLocalChanges
+} from '@el-j/google-sheet-translations';
+
+// Validate locale identifiers
+console.log(isValidLocale('en-us')); // true
+console.log(isValidLocale('description')); // false
+
+// Filter valid locales from header row
+const validLocales = filterValidLocales(['key', 'en', 'description', 'de'], 'key');
+console.log(validLocales); // ['en', 'de']
+
+// Normalize configuration with defaults
+const config = normalizeConfig({ waitSeconds: 2 });
+```
+
+## Bidirectional Sync Feature
+
+This package supports bidirectional synchronization between local translation files and the Google Spreadsheet:
+
+1. **Pull from Spreadsheet**: Fetches translations from Google Sheets and saves them to local JSON files.
+2. **Push to Spreadsheet**: Detects changes in local files and pushes them back to the spreadsheet.
+
+### How Bidirectional Sync Works
+
+1. The system checks if `languageData.json` has been modified more recently than the translation output files.
+2. If so, it compares the local `languageData.json` content with the data fetched from the spreadsheet.
+3. Any new keys found in the local data that don't exist in the spreadsheet will be added to the spreadsheet.
+4. If auto-translation is enabled, Google Translate formulas will be automatically added for missing translations when new keys are added.
+
+This workflow allows developers to:
+
+1. Add new translation keys in local files during development.
+2. Run `getSpreadSheetData()` to push those new keys to the shared spreadsheet.
+3. Run it again later to pull the completed translations once they're filled in by translators.
+
+### Auto-Translation Feature
+
+When enabled, the auto-translation feature automatically adds Google Translate formulas for missing translations when new keys are added to the spreadsheet. This helps translators by providing initial machine translations as a starting point.
+
+The formula follows this format:
+```
+=GOOGLETRANSLATE(INDIRECT(sourceColumn&ROW());$sourceColumn$1;targetColumn$1)
+```
+
+For example, if you add a new key with an English translation in column B but no German translation in column C, the system will automatically add:
+```
+=GOOGLETRANSLATE(INDIRECT("B"&ROW());$B$1;C$1)
+```
+
+Where:
+- `INDIRECT("B"&ROW())` dynamically references the source text cell in the same row
+- `$B$1` references the header cell containing the source language code
+- `C$1` references the header cell containing the target language code
+
+[View the complete Auto-Translation Guide](docs/auto-translation-guide.md) for more details and best practices.
+
+### Example Workflow
+
+```typescript
+// During development: add new keys to local translation files
+
+// Then run this to sync changes back to the spreadsheet
+await getSpreadSheetData(['sheet1'], {
+  syncLocalChanges: true  // This is true by default
+});
+
+// Later, run again to pull completed translations
+await getSpreadSheetData(['sheet1']);
+
+// Example with auto-translation enabled
+await getSpreadSheetData(['sheet1'], {
+  autoTranslate: true  // Automatically generate Google Translate formulas for missing translations
+});
+```
+
+For more detailed examples, check out the [examples directory](examples) where you'll find working code samples for all features including:
+- Basic usage
+- Bidirectional sync
+- Auto-translation
+- Next.js integration
+
+## License
+
+MIT

package/dist/constants.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Package-wide constants
+ */
+/** Default wait time between Google Sheets API calls (in seconds) */
+export declare const DEFAULT_WAIT_SECONDS = 1;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qEAAqE;AACrE,eAAO,MAAM,oBAAoB,IAAI,CAAC"}

package/dist/constants.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Package-wide constants
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_WAIT_SECONDS = void 0;
+/** Default wait time between Google Sheets API calls (in seconds) */
+exports.DEFAULT_WAIT_SECONDS = 1;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,qEAAqE;AACxD,QAAA,oBAAoB,GAAG,CAAC,CAAC"}

package/dist/getSpreadSheetData.d.ts

@@ -0,0 +1,7 @@
+import type { TranslationData } from "./types";
+import { type SpreadsheetOptions } from "./utils/configurationHandler";
+import { DEFAULT_WAIT_SECONDS } from "./constants";
+export { DEFAULT_WAIT_SECONDS };
+export declare function getSpreadSheetData(_docTitle?: string[], options?: SpreadsheetOptions, _refreshDepth?: number): Promise<TranslationData>;
+export default getSpreadSheetData;
+//# sourceMappingURL=getSpreadSheetData.d.ts.map

package/dist/getSpreadSheetData.d.ts.map

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

package/dist/getSpreadSheetData.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_WAIT_SECONDS = void 0;
+exports.getSpreadSheetData = getSpreadSheetData;
+const google_spreadsheet_1 = require("google-spreadsheet");
+const wait_1 = require("./utils/wait");
+const auth_1 = require("./utils/auth");
+const validateEnv_1 = require("./utils/validateEnv");
+const configurationHandler_1 = require("./utils/configurationHandler");
+const sheetProcessor_1 = require("./utils/sheetProcessor");
+const fileWriter_1 = require("./utils/fileWriter");
+const syncManager_1 = require("./utils/syncManager");
+const constants_1 = require("./constants");
+Object.defineProperty(exports, "DEFAULT_WAIT_SECONDS", { enumerable: true, get: function () { return constants_1.DEFAULT_WAIT_SECONDS; } });
+/**
+ * Fetches and processes data from a Google Spreadsheet
+ * @param _docTitle - Array of sheet titles to process
+ * @param options - Additional options for fetching data
+ * @returns Processed translation data
+ */
+const MAX_SYNC_REFRESH_DEPTH = 1;
+async function getSpreadSheetData(_docTitle, options = {}, _refreshDepth = 0) {
+    // Normalize configuration with defaults
+    const config = (0, configurationHandler_1.normalizeConfig)(options);
+    // Get spreadsheet ID from environment variables
+    const { GOOGLE_SPREADSHEET_ID } = (0, validateEnv_1.validateEnv)();
+    // Initialize Google Spreadsheet connection
+    const serviceAuthClient = (0, auth_1.createAuthClient)();
+    const doc = new google_spreadsheet_1.GoogleSpreadsheet(GOOGLE_SPREADSHEET_ID, serviceAuthClient);
+    try {
+        await doc.loadInfo(true);
+    }
+    catch (err) {
+        throw new Error(`Failed to load spreadsheet "${GOOGLE_SPREADSHEET_ID}"`, { cause: err });
+    }
+    // Prepare sheet titles to process
+    const docTitle = _docTitle ?? [];
+    if (docTitle.length === 0) {
+        console.warn("No sheet titles provided, cannot process spreadsheet data");
+        return {};
+    }
+    // Always include i18n sheet if not already present
+    if (!docTitle.includes("i18n")) {
+        docTitle.push("i18n");
+    }
+    console.log(`Processing ${docTitle.length} sheets: ${docTitle.join(", ")}`);
+    // Initialize result containers
+    const finalTranslations = {};
+    const allLocales = new Set();
+    const localesWithContent = new Set(); // Track locales with actual translations in non-i18n sheets
+    const globalLocaleMapping = {}; // normalized -> original header
+    const globalOriginalMapping = {}; // original header -> normalized
+    // Process each sheet in parallel
+    await Promise.all(docTitle.map(async (title) => {
+        await (0, wait_1.wait)(config.waitSeconds, `before get cells for sheet: ${title}`);
+        const sheet = doc.sheetsByTitle[title];
+        if (!sheet) {
+            console.warn(`Sheet "${title}" not found in the document`);
+            return;
+        }
+        const result = await (0, sheetProcessor_1.processSheet)(sheet, title, config.rowLimit, config.waitSeconds);
+        if (result.success) {
+            // Merge locale mappings - prioritize first occurrence for consistency
+            for (const [normalized, original] of Object.entries(result.localeMapping)) {
+                if (!globalLocaleMapping[normalized]) {
+                    globalLocaleMapping[normalized] = original;
+                }
+            }
+            for (const [original, normalized] of Object.entries(result.originalMapping)) {
+                if (!globalOriginalMapping[original]) {
+                    globalOriginalMapping[original] = normalized;
+                }
+            }
+            // Merge translations from this sheet into final result
+            for (const locale of result.locales) {
+                if (finalTranslations[locale]) {
+                    finalTranslations[locale] = {
+                        ...finalTranslations[locale],
+                        ...result.translations[locale]
+                    };
+                }
+                else {
+                    finalTranslations[locale] = result.translations[locale];
+                }
+                allLocales.add(locale);
+                // Only track locales with content from non-i18n sheets
+                if (title !== "i18n" && result.translations[locale] && Object.keys(result.translations[locale]).length > 0) {
+                    // Check if this locale actually has translation content (not just empty objects)
+                    const hasActualTranslations = Object.values(result.translations[locale]).some(sheetTranslations => Object.keys(sheetTranslations).length > 0);
+                    if (hasActualTranslations) {
+                        localesWithContent.add(locale);
+                    }
+                }
+            }
+        }
+    }));
+    // Use locales with actual content for the locales file, fall back to all locales if none found
+    const localesForOutput = localesWithContent.size > 0 ? Array.from(localesWithContent) : Array.from(allLocales);
+    const allLocalesArray = Array.from(allLocales);
+    // Handle bidirectional sync if needed
+    const syncResult = await (0, syncManager_1.handleBidirectionalSync)(doc, config.dataJsonPath, config.translationsOutputDir, config.syncLocalChanges, config.autoTranslate, finalTranslations, config.waitSeconds, globalLocaleMapping);
+    // If sync requested a refresh, recursively call with updated data (depth-limited)
+    if (syncResult.shouldRefresh && _refreshDepth < MAX_SYNC_REFRESH_DEPTH) {
+        return getSpreadSheetData(_docTitle, {
+            ...options,
+            syncLocalChanges: false,
+        }, _refreshDepth + 1);
+    }
+    // Write output files - use all locales for translation files but filtered locales for locales.ts
+    (0, fileWriter_1.writeTranslationFiles)(finalTranslations, allLocalesArray, config.translationsOutputDir);
+    (0, fileWriter_1.writeLocalesFile)(localesForOutput, globalLocaleMapping, config.localesOutputPath);
+    console.log(`Writing locales file with ${localesForOutput.length} locales that have actual translations:`, localesForOutput);
+    // Write languageData.json if we have fresh data or it doesn't exist
+    const hasData = Object.keys(finalTranslations).length > 0;
+    if (hasData) {
+        (0, fileWriter_1.writeLanguageDataFile)(finalTranslations, allLocalesArray, config.dataJsonPath);
+    }
+    return finalTranslations;
+}
+exports.default = getSpreadSheetData;
+//# sourceMappingURL=getSpreadSheetData.js.map

package/dist/getSpreadSheetData.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getSpreadSheetData.js","sourceRoot":"","sources":["../src/getSpreadSheetData.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Google Sheet Translation Manager Package
+ * v2.0.0 – public API surface
+ */
+export { getSpreadSheetData, DEFAULT_WAIT_SECONDS } from './getSpreadSheetData';
+export type { SpreadsheetOptions } from './utils/configurationHandler';
+export { wait } from './utils/wait';
+export { validateEnv } from './utils/validateEnv';
+export { createAuthClient } from './utils/auth';
+export { convertToDataJsonFormat } from './utils/dataConverter/convertToDataJsonFormat';
+export { convertFromDataJsonFormat } from './utils/dataConverter/convertFromDataJsonFormat';
+export { findLocalChanges } from './utils/dataConverter/findLocalChanges';
+export { updateSpreadsheetWithLocalChanges } from './utils/spreadsheetUpdater';
+export { isValidLocale, filterValidLocales } from './utils/localeFilter';
+export type { TranslationData, TranslationValue, SheetRow, GoogleEnvVars, } from './types';
+import { getSpreadSheetData } from './getSpreadSheetData';
+export default getSpreadSheetData;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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,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,aAAa,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAGzE,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,aAAa,GACd,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,eAAe,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Google Sheet Translation Manager Package
+ * v2.0.0 – public API surface
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterValidLocales = exports.isValidLocale = exports.updateSpreadsheetWithLocalChanges = exports.findLocalChanges = exports.convertFromDataJsonFormat = exports.convertToDataJsonFormat = exports.createAuthClient = exports.validateEnv = exports.wait = exports.DEFAULT_WAIT_SECONDS = exports.getSpreadSheetData = void 0;
+// Main entry point
+var getSpreadSheetData_1 = require("./getSpreadSheetData");
+Object.defineProperty(exports, "getSpreadSheetData", { enumerable: true, get: function () { return getSpreadSheetData_1.getSpreadSheetData; } });
+Object.defineProperty(exports, "DEFAULT_WAIT_SECONDS", { enumerable: true, get: function () { return getSpreadSheetData_1.DEFAULT_WAIT_SECONDS; } });
+// Utility functions required by dependents
+var wait_1 = require("./utils/wait");
+Object.defineProperty(exports, "wait", { enumerable: true, get: function () { return wait_1.wait; } });
+var validateEnv_1 = require("./utils/validateEnv");
+Object.defineProperty(exports, "validateEnv", { enumerable: true, get: function () { return validateEnv_1.validateEnv; } });
+var auth_1 = require("./utils/auth");
+Object.defineProperty(exports, "createAuthClient", { enumerable: true, get: function () { return auth_1.createAuthClient; } });
+var convertToDataJsonFormat_1 = require("./utils/dataConverter/convertToDataJsonFormat");
+Object.defineProperty(exports, "convertToDataJsonFormat", { enumerable: true, get: function () { return convertToDataJsonFormat_1.convertToDataJsonFormat; } });
+var convertFromDataJsonFormat_1 = require("./utils/dataConverter/convertFromDataJsonFormat");
+Object.defineProperty(exports, "convertFromDataJsonFormat", { enumerable: true, get: function () { return convertFromDataJsonFormat_1.convertFromDataJsonFormat; } });
+var findLocalChanges_1 = require("./utils/dataConverter/findLocalChanges");
+Object.defineProperty(exports, "findLocalChanges", { enumerable: true, get: function () { return findLocalChanges_1.findLocalChanges; } });
+var spreadsheetUpdater_1 = require("./utils/spreadsheetUpdater");
+Object.defineProperty(exports, "updateSpreadsheetWithLocalChanges", { enumerable: true, get: function () { return spreadsheetUpdater_1.updateSpreadsheetWithLocalChanges; } });
+// Locale validation utilities (useful standalone)
+var localeFilter_1 = require("./utils/localeFilter");
+Object.defineProperty(exports, "isValidLocale", { enumerable: true, get: function () { return localeFilter_1.isValidLocale; } });
+Object.defineProperty(exports, "filterValidLocales", { enumerable: true, get: function () { return localeFilter_1.filterValidLocales; } });
+// Default export
+const getSpreadSheetData_2 = require("./getSpreadSheetData");
+exports.default = getSpreadSheetData_2.getSpreadSheetData;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,mBAAmB;AACnB,2DAAgF;AAAvE,wHAAA,kBAAkB,OAAA;AAAE,0HAAA,oBAAoB,OAAA;AAKjD,2CAA2C;AAC3C,qCAAoC;AAA3B,4FAAA,IAAI,OAAA;AACb,mDAAkD;AAAzC,0GAAA,WAAW,OAAA;AACpB,qCAAgD;AAAvC,wGAAA,gBAAgB,OAAA;AACzB,yFAAwF;AAA/E,kIAAA,uBAAuB,OAAA;AAChC,6FAA4F;AAAnF,sIAAA,yBAAyB,OAAA;AAClC,2EAA0E;AAAjE,oHAAA,gBAAgB,OAAA;AACzB,iEAA+E;AAAtE,uIAAA,iCAAiC,OAAA;AAE1C,kDAAkD;AAClD,qDAAyE;AAAhE,6GAAA,aAAa,OAAA;AAAE,kHAAA,kBAAkB,OAAA;AAU1C,iBAAiB;AACjB,6DAA0D;AAC1D,kBAAe,uCAAkB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Types for translation values
+ */
+export type TranslationValue = string | number | boolean | Record<string, unknown> | unknown[];
+/**
+ * Structure of translation data
+ * locale -> sheet -> key -> value
+ */
+export type TranslationData = Record<string, Record<string, Record<string, TranslationValue>>>;
+/**
+ * Structure for a Google Sheet row
+ */
+export type SheetRow = Record<string, string>;
+/**
+ * Environment variables required by the package
+ */
+export interface GoogleEnvVars {
+    GOOGLE_CLIENT_EMAIL: string;
+    GOOGLE_PRIVATE_KEY: string;
+    GOOGLE_SPREADSHEET_ID: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACzB,MAAM,GACN,MAAM,GACN,OAAO,GACP,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACvB,OAAO,EAAE,CAAC;AAEb;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CACnC,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAChD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qBAAqB,EAAE,MAAM,CAAC;CAC9B"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/utils/auth.d.ts

@@ -0,0 +1,8 @@
+import { JWT } from "google-auth-library";
+/**
+ * Creates and returns a JWT auth client for Google Sheets API
+ * @returns JWT authentication client
+ */
+export declare function createAuthClient(): JWT;
+export default createAuthClient;
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/utils/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAG1C;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,GAAG,CAQtC;AAED,eAAe,gBAAgB,CAAC"}

package/dist/utils/auth.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAuthClient = createAuthClient;
+const google_auth_library_1 = require("google-auth-library");
+const validateEnv_1 = require("./validateEnv");
+/**
+ * Creates and returns a JWT auth client for Google Sheets API
+ * @returns JWT authentication client
+ */
+function createAuthClient() {
+    const { GOOGLE_CLIENT_EMAIL, GOOGLE_PRIVATE_KEY } = (0, validateEnv_1.validateEnv)();
+    return new google_auth_library_1.JWT({
+        email: GOOGLE_CLIENT_EMAIL,
+        key: GOOGLE_PRIVATE_KEY,
+        scopes: ["https://www.googleapis.com/auth/spreadsheets"],
+    });
+}
+exports.default = createAuthClient;
+//# sourceMappingURL=auth.js.map

package/dist/utils/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/utils/auth.ts"],"names":[],"mappings":";;AAOA,4CAQC;AAfD,6DAA0C;AAC1C,+CAA4C;AAE5C;;;GAGG;AACH,SAAgB,gBAAgB;IAC/B,MAAM,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,GAAG,IAAA,yBAAW,GAAE,CAAC;IAElE,OAAO,IAAI,yBAAG,CAAC;QACd,KAAK,EAAE,mBAAmB;QAC1B,GAAG,EAAE,kBAAkB;QACvB,MAAM,EAAE,CAAC,8CAA8C,CAAC;KACxD,CAAC,CAAC;AACJ,CAAC;AAED,kBAAe,gBAAgB,CAAC"}

package/dist/utils/configurationHandler.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Configuration options for getSpreadSheetData
+ */
+export interface SpreadsheetOptions {
+    rowLimit?: number;
+    waitSeconds?: number;
+    dataJsonPath?: string;
+    localesOutputPath?: string;
+    translationsOutputDir?: string;
+    syncLocalChanges?: boolean;
+    autoTranslate?: boolean;
+}
+/**
+ * Normalized configuration with all defaults applied
+ */
+export interface NormalizedConfig {
+    rowLimit: number;
+    waitSeconds: number;
+    dataJsonPath: string;
+    localesOutputPath: string;
+    translationsOutputDir: string;
+    syncLocalChanges: boolean;
+    autoTranslate: boolean;
+}
+/**
+ * Normalizes configuration options by applying defaults
+ */
+export declare function normalizeConfig(options?: SpreadsheetOptions): NormalizedConfig;
+//# sourceMappingURL=configurationHandler.d.ts.map

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

@@ -0,0 +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,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;CACxB;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;CACvB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,kBAAuB,GAAG,gBAAgB,CAUlF"}

package/dist/utils/configurationHandler.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeConfig = normalizeConfig;
+const node_path_1 = __importDefault(require("node:path"));
+const constants_1 = require("../constants");
+/**
+ * Normalizes configuration options by applying defaults
+ */
+function normalizeConfig(options = {}) {
+    return {
+        rowLimit: options.rowLimit ?? 100,
+        waitSeconds: options.waitSeconds ?? constants_1.DEFAULT_WAIT_SECONDS,
+        dataJsonPath: options.dataJsonPath ?? node_path_1.default.join(process.cwd(), "src/lib/languageData.json"),
+        localesOutputPath: options.localesOutputPath ?? "src/i18n/locales.ts",
+        translationsOutputDir: options.translationsOutputDir ?? "translations",
+        syncLocalChanges: options.syncLocalChanges !== false, // Default to true
+        autoTranslate: options.autoTranslate === true, // Default to false
+    };
+}
+//# sourceMappingURL=configurationHandler.js.map

package/dist/utils/configurationHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configurationHandler.js","sourceRoot":"","sources":["../../src/utils/configurationHandler.ts"],"names":[],"mappings":";;;;;AAgCA,0CAUC;AA1CD,0DAA6B;AAC7B,4CAAoD;AA4BpD;;GAEG;AACH,SAAgB,eAAe,CAAC,UAA8B,EAAE;IAC/D,OAAO;QACN,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,GAAG;QACjC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,gCAAoB;QACxD,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,mBAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,2BAA2B,CAAC;QAC3F,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,IAAI,qBAAqB;QACrE,qBAAqB,EAAE,OAAO,CAAC,qBAAqB,IAAI,cAAc;QACtE,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,KAAK,KAAK,EAAE,kBAAkB;QACxE,aAAa,EAAE,OAAO,CAAC,aAAa,KAAK,IAAI,EAAE,mBAAmB;KAClE,CAAC;AACH,CAAC"}