gsheets-i18n 1.0.0

package/dist/cjs/lib/defaultKeyMap.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LOCALE_KEY_MAP = void 0;
+/**
+ * Built-in mapping from common sheet column header spellings to BCP-47 codes.
+ *
+ * The sheet's own `_keymap` tab and the caller's `localeKeyMap` option are
+ * merged on top of this at runtime, so any entry here can be overridden.
+ */
+exports.DEFAULT_LOCALE_KEY_MAP = {
+    // Short codes
+    EN: "en",
+    ENG: "en",
+    CHT: "zh-TW",
+    CHS: "zh-CN",
+    SCH: "zh-CN",
+    TCH: "zh-TW",
+    CZE: "cs",
+    DAN: "da",
+    DUT: "nl",
+    FIN: "fi",
+    FRE: "fr",
+    GER: "de",
+    GRK: "el",
+    HUN: "hu",
+    ITA: "it",
+    JPN: "ja",
+    KOR: "ko",
+    NOR: "no",
+    POL: "pl",
+    POR: "pt",
+    ROM: "ro",
+    RUS: "ru",
+    SPA: "es",
+    SWE: "sv",
+    THA: "th",
+    TUR: "tr",
+    // Long codes with parenthetical hints
+    "TCH (Tchinese)": "zh-TW",
+    "SCH (Schinese)": "zh-CN",
+    "CZE (Czech)": "cs",
+    "DAN (Danish)": "da",
+    "DUT (Dutch)": "nl",
+    "FIN (Finnish)": "fi",
+    "FRE (French)": "fr",
+    "GER (German)": "de",
+    "GRK (Greek)": "el",
+    "HUN (Hungarian)": "hu",
+    "ITA (Italian)": "it",
+    "JPN (Japanese)": "ja",
+    "KOR (Korean)": "ko",
+    "NOR (Norwegian)": "no",
+    "POL (Polish)": "pl",
+    "POR (Portuguese-Brazil)": "pt",
+    "ROM (Romanian)": "ro",
+    "RUS (Russian)": "ru",
+    "SPA (Spanish-Latin)": "es",
+    "SWE (Swedish)": "sv",
+    "THA (Thai)": "th",
+    "TUR (Turkish)": "tr",
+    // Full English names
+    English: "en",
+    Czech: "cs",
+    Danish: "da",
+    Dutch: "nl",
+    Finnish: "fi",
+    French: "fr",
+    German: "de",
+    Greek: "el",
+    Hungarian: "hu",
+    Italian: "it",
+    Japanese: "ja",
+    Korean: "ko",
+    Norwegian: "no",
+    Polish: "pl",
+    Portuguese: "pt",
+    Romanian: "ro",
+    Russian: "ru",
+    "Spanish (Spain)": "es",
+    Swedish: "sv",
+    Thai: "th",
+    Turkish: "tr",
+    // Native names
+    "繁體中文": "zh-TW",
+    "简体中文": "zh-CN",
+    Dansk: "da",
+    Nederlands: "nl",
+    Suomi: "fi",
+    Français: "fr",
+    Deutsch: "de",
+    "Ελληνικά": "el",
+    Magyar: "hu",
+    Italiano: "it",
+    "日本語": "ja",
+    "한글": "ko",
+    Norsk: "no",
+    Polski: "pl",
+    "Português": "pt",
+    "Română": "ro",
+    "Русский": "ru",
+    "Español": "es",
+    Svenska: "sv",
+    "ไทย": "th",
+    "Turk dili": "tr",
+};
+//# sourceMappingURL=defaultKeyMap.js.map

package/dist/cjs/lib/defaultKeyMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaultKeyMap.js","sourceRoot":"","sources":["../../../src/lib/defaultKeyMap.ts"],"names":[],"mappings":";;;AAEA;;;;;GAKG;AACU,QAAA,sBAAsB,GAAiB;IAClD,cAAc;IACd,EAAE,EAAE,IAAI;IACR,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,OAAO;IACZ,GAAG,EAAE,OAAO;IACZ,GAAG,EAAE,OAAO;IACZ,GAAG,EAAE,OAAO;IACZ,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IAET,sCAAsC;IACtC,gBAAgB,EAAE,OAAO;IACzB,gBAAgB,EAAE,OAAO;IACzB,aAAa,EAAE,IAAI;IACnB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,IAAI;IACnB,eAAe,EAAE,IAAI;IACrB,cAAc,EAAE,IAAI;IACpB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,IAAI;IACnB,iBAAiB,EAAE,IAAI;IACvB,eAAe,EAAE,IAAI;IACrB,gBAAgB,EAAE,IAAI;IACtB,cAAc,EAAE,IAAI;IACpB,iBAAiB,EAAE,IAAI;IACvB,cAAc,EAAE,IAAI;IACpB,yBAAyB,EAAE,IAAI;IAC/B,gBAAgB,EAAE,IAAI;IACtB,eAAe,EAAE,IAAI;IACrB,qBAAqB,EAAE,IAAI;IAC3B,eAAe,EAAE,IAAI;IACrB,YAAY,EAAE,IAAI;IAClB,eAAe,EAAE,IAAI;IAErB,qBAAqB;IACrB,OAAO,EAAE,IAAI;IACb,KAAK,EAAE,IAAI;IACX,MAAM,EAAE,IAAI;IACZ,KAAK,EAAE,IAAI;IACX,OAAO,EAAE,IAAI;IACb,MAAM,EAAE,IAAI;IACZ,MAAM,EAAE,IAAI;IACZ,KAAK,EAAE,IAAI;IACX,SAAS,EAAE,IAAI;IACf,OAAO,EAAE,IAAI;IACb,QAAQ,EAAE,IAAI;IACd,MAAM,EAAE,IAAI;IACZ,SAAS,EAAE,IAAI;IACf,MAAM,EAAE,IAAI;IACZ,UAAU,EAAE,IAAI;IAChB,QAAQ,EAAE,IAAI;IACd,OAAO,EAAE,IAAI;IACb,iBAAiB,EAAE,IAAI;IACvB,OAAO,EAAE,IAAI;IACb,IAAI,EAAE,IAAI;IACV,OAAO,EAAE,IAAI;IAEb,eAAe;IACf,MAAM,EAAE,OAAO;IACf,MAAM,EAAE,OAAO;IACf,KAAK,EAAE,IAAI;IACX,UAAU,EAAE,IAAI;IAChB,KAAK,EAAE,IAAI;IACX,QAAQ,EAAE,IAAI;IACd,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,IAAI;IAChB,MAAM,EAAE,IAAI;IACZ,QAAQ,EAAE,IAAI;IACd,KAAK,EAAE,IAAI;IACX,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,IAAI;IACX,MAAM,EAAE,IAAI;IACZ,WAAW,EAAE,IAAI;IACjB,QAAQ,EAAE,IAAI;IACd,SAAS,EAAE,IAAI;IACf,SAAS,EAAE,IAAI;IACf,OAAO,EAAE,IAAI;IACb,KAAK,EAAE,IAAI;IACX,WAAW,EAAE,IAAI;CAClB,CAAC"}

package/dist/cjs/lib/driveClient.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listFolderContents = listFolderContents;
+exports.isSpreadsheet = isSpreadsheet;
+exports.isFolder = isFolder;
+exports.isInternal = isInternal;
+exports.isKeymapSheet = isKeymapSheet;
+const googleapis_1 = require("googleapis");
+const MIME_SHEET = "application/vnd.google-apps.spreadsheet";
+const MIME_FOLDER = "application/vnd.google-apps.folder";
+/**
+ * Lists all files and sub-folders directly inside a Drive folder.
+ * Handles pagination automatically.
+ */
+async function listFolderContents(auth, folderId) {
+    const drive = googleapis_1.google.drive({ version: "v3", auth });
+    const files = [];
+    let pageToken;
+    do {
+        const response = await drive.files.list({
+            q: `'${folderId}' in parents and trashed = false`,
+            pageSize: 1000,
+            fields: "nextPageToken, files(id, name, mimeType)",
+            ...(pageToken ? { pageToken } : {}),
+        });
+        const page = response.data.files ?? [];
+        for (const f of page) {
+            if (f.id && f.name && f.mimeType) {
+                files.push({ id: f.id, name: f.name, mimeType: f.mimeType });
+            }
+        }
+        pageToken = response.data.nextPageToken ?? undefined;
+    } while (pageToken);
+    return files;
+}
+function isSpreadsheet(file) {
+    return file.mimeType === MIME_SHEET;
+}
+function isFolder(file) {
+    return file.mimeType === MIME_FOLDER;
+}
+/** Files/folders whose name starts with `_` are treated as internal/skipped. */
+function isInternal(file) {
+    return file.name.startsWith("_");
+}
+/** A keymap sheet is a spreadsheet named `_keymap` (internal, but special). */
+function isKeymapSheet(file) {
+    return isSpreadsheet(file) && file.name === "_keymap";
+}
+//# sourceMappingURL=driveClient.js.map

package/dist/cjs/lib/driveClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driveClient.js","sourceRoot":"","sources":["../../../src/lib/driveClient.ts"],"names":[],"mappings":";;AAiBA,gDA2BC;AAED,sCAEC;AAED,4BAEC;AAGD,gCAEC;AAGD,sCAEC;AA9DD,2CAAoC;AAUpC,MAAM,UAAU,GAAG,yCAAyC,CAAC;AAC7D,MAAM,WAAW,GAAG,oCAAoC,CAAC;AAEzD;;;GAGG;AACI,KAAK,UAAU,kBAAkB,CACtC,IAAgB,EAChB,QAAgB;IAEhB,MAAM,KAAK,GAAG,mBAAM,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,IAAI,SAA6B,CAAC;IAElC,GAAG,CAAC;QACF,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC;YACtC,CAAC,EAAE,IAAI,QAAQ,kCAAkC;YACjD,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE,0CAA0C;YAClD,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpC,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;QACvC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACrB,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;gBACjC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC;QAED,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,aAAa,IAAI,SAAS,CAAC;IACvD,CAAC,QAAQ,SAAS,EAAE;IAEpB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAgB,aAAa,CAAC,IAAe;IAC3C,OAAO,IAAI,CAAC,QAAQ,KAAK,UAAU,CAAC;AACtC,CAAC;AAED,SAAgB,QAAQ,CAAC,IAAe;IACtC,OAAO,IAAI,CAAC,QAAQ,KAAK,WAAW,CAAC;AACvC,CAAC;AAED,gFAAgF;AAChF,SAAgB,UAAU,CAAC,IAAe;IACxC,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AACnC,CAAC;AAED,+EAA+E;AAC/E,SAAgB,aAAa,CAAC,IAAe;IAC3C,OAAO,aAAa,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC;AACxD,CAAC"}

package/dist/cjs/lib/folderExtractor.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractFromFolder = extractFromFolder;
+const driveClient_js_1 = require("./driveClient.js");
+const sheetsClient_js_1 = require("./sheetsClient.js");
+const parser_js_1 = require("./parser.js");
+/**
+ * Recursively extracts translations from all spreadsheets inside a Drive folder.
+ *
+ * Naming conventions:
+ * - Files/folders starting with `_` are skipped (treated as internal).
+ * - A spreadsheet named exactly `_keymap` inside a folder provides locale
+ *   key mappings that apply to all sheets in that folder.
+ * - Each spreadsheet's name is used as a namespace path component.
+ * - Sub-folder names become path components (e.g. folder `common` containing
+ *   sheet `buttons` → namespace `common.buttons`).
+ */
+async function extractFromFolder(options) {
+    const { auth, folderId, includeEmpty = false, userKeyMap } = options;
+    const result = {};
+    await scanFolder(auth, folderId, [], result, {
+        includeEmpty,
+        userKeyMap,
+        inheritedKeyMap: (0, parser_js_1.buildLocaleKeyMap)(userKeyMap),
+    });
+    return result;
+}
+async function scanFolder(auth, folderId, namespacePath, result, options) {
+    const { includeEmpty, userKeyMap } = options;
+    let { inheritedKeyMap } = options;
+    const files = await (0, driveClient_js_1.listFolderContents)(auth, folderId);
+    // 1. Check for a `_keymap` spreadsheet in this folder and merge it
+    const keymapSheet = files.find(driveClient_js_1.isKeymapSheet);
+    if (keymapSheet) {
+        const grid = await (0, sheetsClient_js_1.getTabData)(auth, keymapSheet.id);
+        const folderKeyMap = (0, parser_js_1.parseKeymapGrid)(grid);
+        inheritedKeyMap = (0, parser_js_1.buildLocaleKeyMap)(userKeyMap, {
+            ...inheritedKeyMap,
+            ...folderKeyMap,
+        });
+    }
+    // 2. Recurse into non-internal sub-folders
+    const subFolders = files.filter((f) => (0, driveClient_js_1.isFolder)(f) && !(0, driveClient_js_1.isInternal)(f));
+    for (const folder of subFolders) {
+        await scanFolder(auth, folder.id, [...namespacePath, folder.name], result, {
+            includeEmpty,
+            userKeyMap,
+            inheritedKeyMap,
+        });
+    }
+    // 3. Process non-internal spreadsheets
+    const sheets = files.filter((f) => (0, driveClient_js_1.isSpreadsheet)(f) && !(0, driveClient_js_1.isInternal)(f));
+    for (const sheet of sheets) {
+        const grid = await (0, sheetsClient_js_1.getTabData)(auth, sheet.id);
+        const namespace = [...namespacePath, sheet.name].join(".");
+        (0, parser_js_1.parseGrid)(grid, result, {
+            keyMap: inheritedKeyMap,
+            namespace,
+            includeEmpty,
+        });
+    }
+}
+//# sourceMappingURL=folderExtractor.js.map

package/dist/cjs/lib/folderExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"folderExtractor.js","sourceRoot":"","sources":["../../../src/lib/folderExtractor.ts"],"names":[],"mappings":";;AAmCA,8CAaC;AA/CD,qDAM0B;AAC1B,uDAA+C;AAC/C,2CAIqB;AAWrB;;;;;;;;;;GAUG;AACI,KAAK,UAAU,iBAAiB,CACrC,OAA+B;IAE/B,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,GAAG,KAAK,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IACrE,MAAM,MAAM,GAAmB,EAAE,CAAC;IAElC,MAAM,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE;QAC3C,YAAY;QACZ,UAAU;QACV,eAAe,EAAE,IAAA,6BAAiB,EAAC,UAAU,CAAC;KAC/C,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC;AAQD,KAAK,UAAU,UAAU,CACvB,IAAgB,EAChB,QAAgB,EAChB,aAAuB,EACvB,MAAsB,EACtB,OAAoB;IAEpB,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAC7C,IAAI,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC;IAElC,MAAM,KAAK,GAAG,MAAM,IAAA,mCAAkB,EAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAEvD,mEAAmE;IACnE,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,8BAAa,CAAC,CAAC;IAC9C,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,IAAI,GAAG,MAAM,IAAA,4BAAU,EAAC,IAAI,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC;QACpD,MAAM,YAAY,GAAG,IAAA,2BAAe,EAAC,IAAI,CAAC,CAAC;QAC3C,eAAe,GAAG,IAAA,6BAAiB,EAAC,UAAU,EAAE;YAC9C,GAAG,eAAe;YAClB,GAAG,YAAY;SAChB,CAAC,CAAC;IACL,CAAC;IAED,2CAA2C;IAC3C,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAA,yBAAQ,EAAC,CAAC,CAAC,IAAI,CAAC,IAAA,2BAAU,EAAC,CAAC,CAAC,CAAC,CAAC;IACtE,KAAK,MAAM,MAAM,IAAI,UAAU,EAAE,CAAC;QAChC,MAAM,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,GAAG,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE;YACzE,YAAY;YACZ,UAAU;YACV,eAAe;SAChB,CAAC,CAAC;IACL,CAAC;IAED,uCAAuC;IACvC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAA,8BAAa,EAAC,CAAC,CAAC,IAAI,CAAC,IAAA,2BAAU,EAAC,CAAC,CAAC,CAAC,CAAC;IACvE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,MAAM,IAAA,4BAAU,EAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;QAC9C,MAAM,SAAS,GAAG,CAAC,GAAG,aAAa,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAE3D,IAAA,qBAAS,EAAC,IAAI,EAAE,MAAM,EAAE;YACtB,MAAM,EAAE,eAAe;YACvB,SAAS;YACT,YAAY;SACb,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/cjs/lib/parser.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildLocaleKeyMap = buildLocaleKeyMap;
+exports.parseKeymapGrid = parseKeymapGrid;
+exports.setNestedValue = setNestedValue;
+exports.parseGrid = parseGrid;
+const defaultKeyMap_js_1 = require("./defaultKeyMap.js");
+// ─── Key map resolution ───────────────────────────────────────────────────────
+/**
+ * Merges the default key map with any user-supplied overrides and an optional
+ * `_keymap` tab extracted from the spreadsheet itself.
+ *
+ * Priority (highest → lowest):
+ *   1. Spreadsheet `_keymap` tab
+ *   2. `localeKeyMap` option passed by the caller
+ *   3. Built-in `DEFAULT_LOCALE_KEY_MAP`
+ */
+function buildLocaleKeyMap(userKeyMap, sheetKeyMap) {
+    return {
+        ...defaultKeyMap_js_1.DEFAULT_LOCALE_KEY_MAP,
+        ...(userKeyMap ?? {}),
+        ...(sheetKeyMap ?? {}),
+    };
+}
+/**
+ * Parses a `_keymap` tab (either from a dedicated sheet or from a tab named
+ * `_keymap` inside a spreadsheet).
+ *
+ * Expected layout:
+ * ```
+ * | locale code | fr    | en      | de     |
+ * | header name | French| English | German |
+ * ```
+ * Row 0 = locale codes (output keys), Row 1+ = header name variants.
+ */
+function parseKeymapGrid(grid) {
+    if (grid.length < 2)
+        return {};
+    const [localeCodes, ...headerRows] = grid;
+    const result = {};
+    for (const row of headerRows) {
+        row.forEach((headerVariant, colIndex) => {
+            if (colIndex === 0 || !headerVariant)
+                return;
+            const locale = localeCodes[colIndex];
+            if (locale)
+                result[headerVariant] = locale;
+        });
+    }
+    return result;
+}
+// ─── Nested key assignment ────────────────────────────────────────────────────
+/**
+ * Sets a value at a dotted path inside a nested object, creating intermediate
+ * objects as needed.
+ *
+ * @example
+ * setNestedValue({}, "actions.save", "Save")
+ * // → { actions: { save: "Save" } }
+ */
+function setNestedValue(obj, dotPath, value) {
+    const parts = dotPath.split(".");
+    let cursor = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (typeof cursor[part] !== "object" || cursor[part] === null) {
+            cursor[part] = {};
+        }
+        cursor = cursor[part];
+    }
+    cursor[parts[parts.length - 1]] = value;
+}
+/**
+ * Parses a single sheet grid and merges all found translations into `result`.
+ *
+ * Expected grid layout:
+ * ```
+ * | key (ignored)  | EN      | FR      | DE      |
+ * | actions.save   | Save    | Enreg.  | Speich. |
+ * | actions.cancel | Cancel  | Annuler | Abbruch |
+ * ```
+ *
+ * Column 0 is always the key column.
+ * Column 1 is the first language (index 1 in the header row).
+ */
+function parseGrid(grid, result, options) {
+    const { keyMap, namespace, startColumn = 0, includeEmpty = false } = options;
+    if (grid.length < 2)
+        return;
+    const [headerRow, ...dataRows] = grid;
+    const slicedHeader = headerRow.slice(startColumn);
+    // Map column index (relative to startColumn) → resolved locale code.
+    // Column 0 of the sliced header is the key column — skip it (index starts at 1).
+    const columnLocales = slicedHeader.map((cell, i) => {
+        if (i === 0)
+            return null; // key column
+        const resolved = keyMap[cell] ?? cell;
+        // Skip columns whose name/locale starts with "_" (internal metadata)
+        return resolved.startsWith("_") ? null : resolved;
+    });
+    for (const row of dataRows) {
+        const slicedRow = row.slice(startColumn);
+        const translationKey = slicedRow[0]?.trim();
+        if (!translationKey)
+            continue;
+        const fullKey = namespace ? `${namespace}.${translationKey}` : translationKey;
+        slicedRow.slice(1).forEach((value, colOffset) => {
+            const locale = columnLocales[colOffset + 1];
+            if (!locale)
+                return;
+            const trimmedValue = value?.trim() ?? "";
+            if (!trimmedValue && !includeEmpty)
+                return;
+            if (!result[locale])
+                result[locale] = {};
+            setNestedValue(result[locale], fullKey, trimmedValue);
+        });
+    }
+}
+//# sourceMappingURL=parser.js.map

package/dist/cjs/lib/parser.js.map

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

package/dist/cjs/lib/sheetExtractor.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractFromSheet = extractFromSheet;
+const sheetsClient_js_1 = require("./sheetsClient.js");
+const parser_js_1 = require("./parser.js");
+/**
+ * Extracts translations from a single Google Spreadsheet.
+ *
+ * - If `tabId` is given → only that tab is parsed, keys are NOT namespaced.
+ * - If `tabId` is omitted → all non-internal tabs are parsed;
+ *   each tab name becomes a namespace prefix (e.g. tab "actions" → key "actions.save").
+ *
+ * Tabs whose name starts with `_` are treated as internal and skipped,
+ * except for `_keymap` which is parsed to build a custom locale key map.
+ */
+async function extractFromSheet(options) {
+    const { auth, spreadsheetId, tabId, startColumn = 0, includeEmpty = false, userKeyMap, } = options;
+    const result = {};
+    // 1. List all tabs
+    const tabs = await (0, sheetsClient_js_1.getSpreadsheetTabs)(auth, spreadsheetId);
+    // 2. Check for a `_keymap` tab and parse it first
+    let sheetKeyMap;
+    const keymapTab = tabs.find((t) => t.title === "_keymap");
+    if (keymapTab) {
+        const grid = await (0, sheetsClient_js_1.getTabData)(auth, spreadsheetId, keymapTab.title);
+        sheetKeyMap = (0, parser_js_1.parseKeymapGrid)(grid);
+    }
+    const keyMap = (0, parser_js_1.buildLocaleKeyMap)(userKeyMap, sheetKeyMap);
+    // 3. Determine which tabs to process
+    let targetTabs = tabId !== undefined
+        ? tabs.filter((t) => t.sheetId === tabId)
+        : tabs.filter((t) => !t.title.startsWith("_"));
+    if (targetTabs.length === 0) {
+        throw new Error(tabId !== undefined
+            ? `Tab with ID ${tabId} not found in spreadsheet ${spreadsheetId}.`
+            : `No processable tabs found in spreadsheet ${spreadsheetId}.`);
+    }
+    // 4. Parse each tab
+    for (const tab of targetTabs) {
+        const grid = await (0, sheetsClient_js_1.getTabData)(auth, spreadsheetId, tab.title);
+        (0, parser_js_1.parseGrid)(grid, result, {
+            keyMap,
+            // When a specific tab is requested, don't namespace the keys.
+            // When scanning all tabs, use the tab name as namespace.
+            namespace: tabId !== undefined ? undefined : tab.title,
+            startColumn,
+            includeEmpty,
+        });
+    }
+    return result;
+}
+//# sourceMappingURL=sheetExtractor.js.map

package/dist/cjs/lib/sheetExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sheetExtractor.js","sourceRoot":"","sources":["../../../src/lib/sheetExtractor.ts"],"names":[],"mappings":";;AA+BA,4CAuDC;AArFD,uDAAmE;AACnE,2CAIqB;AAerB;;;;;;;;;GASG;AACI,KAAK,UAAU,gBAAgB,CACpC,OAA8B;IAE9B,MAAM,EACJ,IAAI,EACJ,aAAa,EACb,KAAK,EACL,WAAW,GAAG,CAAC,EACf,YAAY,GAAG,KAAK,EACpB,UAAU,GACX,GAAG,OAAO,CAAC;IAEZ,MAAM,MAAM,GAAmB,EAAE,CAAC;IAElC,mBAAmB;IACnB,MAAM,IAAI,GAAG,MAAM,IAAA,oCAAkB,EAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IAE3D,kDAAkD;IAClD,IAAI,WAAqC,CAAC;IAC1C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC;IAC1D,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,IAAI,GAAG,MAAM,IAAA,4BAAU,EAAC,IAAI,EAAE,aAAa,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;QACpE,WAAW,GAAG,IAAA,2BAAe,EAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,MAAM,GAAG,IAAA,6BAAiB,EAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IAE1D,qCAAqC;IACrC,IAAI,UAAU,GAAG,KAAK,KAAK,SAAS;QAClC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,KAAK,CAAC;QACzC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IAEjD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,KAAK,KAAK,SAAS;YACjB,CAAC,CAAC,eAAe,KAAK,6BAA6B,aAAa,GAAG;YACnE,CAAC,CAAC,4CAA4C,aAAa,GAAG,CACjE,CAAC;IACJ,CAAC;IAED,oBAAoB;IACpB,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,MAAM,IAAA,4BAAU,EAAC,IAAI,EAAE,aAAa,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;QAE9D,IAAA,qBAAS,EAAC,IAAI,EAAE,MAAM,EAAE;YACtB,MAAM;YACN,8DAA8D;YAC9D,yDAAyD;YACzD,SAAS,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK;YACtD,WAAW;YACX,YAAY;SACb,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/cjs/lib/sheetsClient.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSpreadsheetTabs = getSpreadsheetTabs;
+exports.getTabData = getTabData;
+const googleapis_1 = require("googleapis");
+/**
+ * Lists all tabs in a spreadsheet and returns their metadata.
+ */
+async function getSpreadsheetTabs(auth, spreadsheetId) {
+    const sheets = googleapis_1.google.sheets({ version: "v4", auth });
+    const response = await sheets.spreadsheets.get({ spreadsheetId });
+    const rawSheets = response.data.sheets ?? [];
+    return rawSheets
+        .map((s) => ({
+        sheetId: s.properties?.sheetId ?? 0,
+        title: s.properties?.title ?? "",
+    }))
+        .filter((s) => s.title !== "");
+}
+/**
+ * Fetches all cell values from a single tab of a spreadsheet.
+ *
+ * @param tabName - The display name of the tab. When omitted, the first tab is used.
+ */
+async function getTabData(auth, spreadsheetId, tabName) {
+    const sheets = googleapis_1.google.sheets({ version: "v4", auth });
+    // Encode the tab name to handle special characters (spaces, apostrophes, etc.)
+    const range = tabName
+        ? `'${tabName.replace(/'/g, "\\'")}'!A1:ZZ9999`
+        : "A1:ZZ9999";
+    const response = await sheets.spreadsheets.values.get({
+        spreadsheetId,
+        range,
+    });
+    return response.data.values ?? [];
+}
+//# sourceMappingURL=sheetsClient.js.map

package/dist/cjs/lib/sheetsClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sheetsClient.js","sourceRoot":"","sources":["../../../src/lib/sheetsClient.ts"],"names":[],"mappings":";;AAQA,gDAcC;AAOD,gCAkBC;AA/CD,2CAAoC;AAKpC;;GAEG;AACI,KAAK,UAAU,kBAAkB,CACtC,IAAgB,EAChB,aAAqB;IAErB,MAAM,MAAM,GAAG,mBAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;IAElE,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;IAC7C,OAAO,SAAS;SACb,GAAG,CAAC,CAAC,CAAsE,EAAE,EAAE,CAAC,CAAC;QAChF,OAAO,EAAE,CAAC,CAAC,UAAU,EAAE,OAAO,IAAI,CAAC;QACnC,KAAK,EAAE,CAAC,CAAC,UAAU,EAAE,KAAK,IAAI,EAAE;KACjC,CAAC,CAAC;SACF,MAAM,CAAC,CAAC,CAAoB,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,UAAU,CAC9B,IAAgB,EAChB,aAAqB,EACrB,OAAgB;IAEhB,MAAM,MAAM,GAAG,mBAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAEtD,+EAA+E;IAC/E,MAAM,KAAK,GAAG,OAAO;QACnB,CAAC,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,aAAa;QAC/C,CAAC,CAAC,WAAW,CAAC;IAEhB,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC;QACpD,aAAa;QACb,KAAK;KACN,CAAC,CAAC;IAEH,OAAQ,QAAQ,CAAC,IAAI,CAAC,MAA2B,IAAI,EAAE,CAAC;AAC1D,CAAC"}

package/dist/cjs/lib/writer.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeTranslationFiles = writeTranslationFiles;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+/**
+ * Writes one JSON file per locale into `outputDir`.
+ * Creates the directory (and any parents) if it does not exist.
+ *
+ * @returns Metadata about each file that was written.
+ */
+async function writeTranslationFiles(translations, outputDir, indent = 2) {
+    const absoluteDir = (0, node_path_1.resolve)(process.cwd(), outputDir);
+    await (0, promises_1.mkdir)(absoluteDir, { recursive: true });
+    const outputs = [];
+    for (const [locale, translationObject] of Object.entries(translations)) {
+        // Skip entirely empty locale objects
+        if (Object.keys(translationObject).length === 0)
+            continue;
+        const filePath = (0, node_path_1.join)(absoluteDir, `${locale}.json`);
+        const content = JSON.stringify(translationObject, null, indent);
+        await (0, promises_1.writeFile)(filePath, content, "utf-8");
+        outputs.push({
+            locale,
+            path: filePath,
+            keyCount: Object.keys(translationObject).length,
+        });
+    }
+    // Sort output list by locale code for deterministic logging
+    outputs.sort((a, b) => a.locale.localeCompare(b.locale));
+    return outputs;
+}
+//# sourceMappingURL=writer.js.map

package/dist/cjs/lib/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../../src/lib/writer.ts"],"names":[],"mappings":";;AAUA,sDA8BC;AAxCD,+CAAoD;AACpD,yCAA0C;AAG1C;;;;;GAKG;AACI,KAAK,UAAU,qBAAqB,CACzC,YAA4B,EAC5B,SAAiB,EACjB,SAA0B,CAAC;IAE3B,MAAM,WAAW,GAAG,IAAA,mBAAO,EAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,CAAC,CAAC;IACtD,MAAM,IAAA,gBAAK,EAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE9C,MAAM,OAAO,GAAiB,EAAE,CAAC;IAEjC,KAAK,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QACvE,qCAAqC;QACrC,IAAI,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAE1D,MAAM,QAAQ,GAAG,IAAA,gBAAI,EAAC,WAAW,EAAE,GAAG,MAAM,OAAO,CAAC,CAAC;QACrD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,iBAAiB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAEhE,MAAM,IAAA,oBAAS,EAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAE5C,OAAO,CAAC,IAAI,CAAC;YACX,MAAM;YACN,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,MAAM;SAChD,CAAC,CAAC;IACL,CAAC;IAED,4DAA4D;IAC5D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAEzD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/cjs/types/index.js

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

package/dist/cjs/types/index.js.map

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

package/dist/esm/cli/index.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { extract } from "../index.js";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function parseIndent(value) {
+    if (value === "tab" || value === "\t")
+        return "\t";
+    const num = Number(value);
+    if (!Number.isNaN(num) && num >= 0 && num <= 8)
+        return num;
+    throw new Error(`Invalid indent value: "${value}". Use a number 0–8 or "tab".`);
+}
+function fatal(message) {
+    console.error(`\n  ✖  ${message}\n`);
+    process.exit(1);
+}
+// ─── CLI definition ───────────────────────────────────────────────────────────
+const program = new Command();
+program
+    .name("sheets-i18n")
+    .description("Generate i18n JSON files from a Google Spreadsheet or Drive folder.")
+    .version("1.0.0");
+// ── sheet command ─────────────────────────────────────────────────────────────
+program
+    .command("sheet")
+    .description("Extract from a single Google Spreadsheet")
+    .requiredOption("-s, --sheet-id <spreadsheetId>", "Google Spreadsheet ID (from the URL)")
+    .requiredOption("-k, --key <path>", "Path to the Service Account JSON key file", "./service-account.json")
+    .option("-o, --out <path>", "Output directory for the generated JSON files", "./i18n")
+    .option("-t, --tab-id <id>", "Numeric tab ID to extract (default: all tabs)")
+    .option("--start-column <n>", "Zero-based column index to start reading from", "0")
+    .option("--include-empty", "Include keys with empty values in the output", false)
+    .option("--indent <value>", 'JSON indentation: a number of spaces or "tab"', "2")
+    .option("--key-map <path>", "Path to a JSON file with custom locale key mappings")
+    .action(async (opts) => {
+    let localeKeyMap;
+    if (opts.keyMap) {
+        try {
+            const raw = await readFile(resolve(process.cwd(), opts.keyMap), "utf-8");
+            localeKeyMap = JSON.parse(raw);
+        }
+        catch {
+            fatal(`Could not read key map file: ${opts.keyMap}`);
+            return;
+        }
+    }
+    console.log("\n  ⏳  Extracting translations…\n");
+    try {
+        const result = await extract({
+            serviceAccountKey: opts.key,
+            source: {
+                mode: "sheet",
+                spreadsheetId: opts.sheetId,
+                tabId: opts.tabId !== undefined ? Number(opts.tabId) : undefined,
+                startColumn: Number(opts.startColumn),
+            },
+            outputDir: opts.out,
+            localeKeyMap,
+            includeEmpty: opts.includeEmpty,
+            indent: parseIndent(opts.indent),
+        });
+        console.log(`  ✔  Done in ${(result.durationMs / 1000).toFixed(2)}s\n`);
+        console.log(`  📂  ${resolve(process.cwd(), opts.out)}\n`);
+        for (const file of result.files) {
+            console.log(`      ${file.locale}.json  (${file.keyCount} top-level keys)`);
+        }
+        console.log();
+    }
+    catch (err) {
+        fatal(err instanceof Error ? err.message : String(err));
+    }
+});
+// ── folder command ────────────────────────────────────────────────────────────
+program
+    .command("folder")
+    .description("Extract from all spreadsheets inside a Google Drive folder")
+    .requiredOption("-f, --folder-id <folderId>", "Google Drive folder ID (from the URL)")
+    .requiredOption("-k, --key <path>", "Path to the Service Account JSON key file", "./service-account.json")
+    .option("-o, --out <path>", "Output directory for the generated JSON files", "./i18n")
+    .option("--include-empty", "Include keys with empty values in the output", false)
+    .option("--indent <value>", 'JSON indentation: a number of spaces or "tab"', "2")
+    .option("--key-map <path>", "Path to a JSON file with custom locale key mappings")
+    .action(async (opts) => {
+    let localeKeyMap;
+    if (opts.keyMap) {
+        try {
+            const raw = await readFile(resolve(process.cwd(), opts.keyMap), "utf-8");
+            localeKeyMap = JSON.parse(raw);
+        }
+        catch {
+            fatal(`Could not read key map file: ${opts.keyMap}`);
+            return;
+        }
+    }
+    console.log("\n  ⏳  Extracting translations…\n");
+    try {
+        const result = await extract({
+            serviceAccountKey: opts.key,
+            source: {
+                mode: "folder",
+                folderId: opts.folderId,
+            },
+            outputDir: opts.out,
+            localeKeyMap,
+            includeEmpty: opts.includeEmpty,
+            indent: parseIndent(opts.indent),
+        });
+        console.log(`  ✔  Done in ${(result.durationMs / 1000).toFixed(2)}s\n`);
+        console.log(`  📂  ${resolve(process.cwd(), opts.out)}\n`);
+        for (const file of result.files) {
+            console.log(`      ${file.locale}.json  (${file.keyCount} top-level keys)`);
+        }
+        console.log();
+    }
+    catch (err) {
+        fatal(err instanceof Error ? err.message : String(err));
+    }
+});
+// ─── Parse ────────────────────────────────────────────────────────────────────
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/esm/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,iFAAiF;AAEjF,SAAS,WAAW,CAAC,KAAa;IAChC,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnD,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC;IAC3D,MAAM,IAAI,KAAK,CAAC,0BAA0B,KAAK,+BAA+B,CAAC,CAAC;AAClF,CAAC;AAED,SAAS,KAAK,CAAC,OAAe;IAC5B,OAAO,CAAC,KAAK,CAAC,UAAU,OAAO,IAAI,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,iFAAiF;AAEjF,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,aAAa,CAAC;KACnB,WAAW,CACV,qEAAqE,CACtE;KACA,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,iFAAiF;AACjF,OAAO;KACJ,OAAO,CAAC,OAAO,CAAC;KAChB,WAAW,CAAC,0CAA0C,CAAC;KACvD,cAAc,CACb,gCAAgC,EAChC,sCAAsC,CACvC;KACA,cAAc,CACb,kBAAkB,EAClB,2CAA2C,EAC3C,wBAAwB,CACzB;KACA,MAAM,CACL,kBAAkB,EAClB,+CAA+C,EAC/C,QAAQ,CACT;KACA,MAAM,CACL,mBAAmB,EACnB,+CAA+C,CAChD;KACA,MAAM,CACL,oBAAoB,EACpB,+CAA+C,EAC/C,GAAG,CACJ;KACA,MAAM,CACL,iBAAiB,EACjB,8CAA8C,EAC9C,KAAK,CACN;KACA,MAAM,CACL,kBAAkB,EAClB,+CAA+C,EAC/C,GAAG,CACJ;KACA,MAAM,CACL,kBAAkB,EAClB,qDAAqD,CACtD;KACA,MAAM,CAAC,KAAK,EAAE,IASd,EAAE,EAAE;IACH,IAAI,YAAgD,CAAC;IAErD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;YACzE,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA2B,CAAC;QAC3D,CAAC;QAAC,MAAM,CAAC;YACP,KAAK,CAAC,gCAAgC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YACrD,OAAO;QACT,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;IAEjD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC;YAC3B,iBAAiB,EAAE,IAAI,CAAC,GAAG;YAC3B,MAAM,EAAE;gBACN,IAAI,EAAE,OAAO;gBACb,aAAa,EAAE,IAAI,CAAC,OAAO;gBAC3B,KAAK,EAAE,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;gBAChE,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC;aACtC;YACD,SAAS,EAAE,IAAI,CAAC,GAAG;YACnB,YAAY;YACZ,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC;SACjC,CAAC,CAAC;QAEH,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACxE,OAAO,CAAC,GAAG,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3D,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YAChC,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,MAAM,WAAW,IAAI,CAAC,QAAQ,kBAAkB,CAAC,CAAC;QAC9E,CAAC;QACD,OAAO,CAAC,GAAG,EAAE,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,iFAAiF;AACjF,OAAO;KACJ,OAAO,CAAC,QAAQ,CAAC;KACjB,WAAW,CAAC,4DAA4D,CAAC;KACzE,cAAc,CACb,4BAA4B,EAC5B,uCAAuC,CACxC;KACA,cAAc,CACb,kBAAkB,EAClB,2CAA2C,EAC3C,wBAAwB,CACzB;KACA,MAAM,CACL,kBAAkB,EAClB,+CAA+C,EAC/C,QAAQ,CACT;KACA,MAAM,CACL,iBAAiB,EACjB,8CAA8C,EAC9C,KAAK,CACN;KACA,MAAM,CACL,kBAAkB,EAClB,+CAA+C,EAC/C,GAAG,CACJ;KACA,MAAM,CACL,kBAAkB,EAClB,qDAAqD,CACtD;KACA,MAAM,CAAC,KAAK,EAAE,IAOd,EAAE,EAAE;IACH,IAAI,YAAgD,CAAC;IAErD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;YACzE,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA2B,CAAC;QAC3D,CAAC;QAAC,MAAM,CAAC;YACP,KAAK,CAAC,gCAAgC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YACrD,OAAO;QACT,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;IAEjD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC;YAC3B,iBAAiB,EAAE,IAAI,CAAC,GAAG;YAC3B,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,IAAI,CAAC,QAAQ;aACxB;YACD,SAAS,EAAE,IAAI,CAAC,GAAG;YACnB,YAAY;YACZ,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC;SACjC,CAAC,CAAC;QAEH,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACxE,OAAO,CAAC,GAAG,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3D,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YAChC,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,MAAM,WAAW,IAAI,CAAC,QAAQ,kBAAkB,CAAC,CAAC;QAC9E,CAAC;QACD,OAAO,CAAC,GAAG,EAAE,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,iFAAiF;AACjF,OAAO,CAAC,KAAK,EAAE,CAAC"}