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

package/dist-cli/run-provider.mjs

@@ -0,0 +1,2025 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { GoogleSpreadsheet } from "google-spreadsheet";
+import { GoogleAuth } from "google-auth-library";
+import https from "node:https";
+import http from "node:http";
+import { setTimeout } from "node:timers/promises";
+import fs$1 from "node:fs/promises";
+import { parse } from "csv-parse/sync";
+import crypto from "node:crypto";
+//#region src/providers/capabilities.ts
+/**
+* Baseline capability set where all capabilities are explicitly disabled (`false`).
+*/
+const EMPTY_PROVIDER_CAPABILITIES = {
+	readTables: false,
+	writeTables: false,
+	syncBack: false,
+	readAssets: false,
+	writeAssets: false,
+	autoTranslateFormula: false,
+	discoverByFolder: false,
+	assetSync: false,
+	publicReadNoAuth: false
+};
+/**
+* Mapping defining which capabilities are mandatory for each {@link ProviderOperation}.
+*/
+const OPERATION_CAPABILITY_REQUIREMENTS = {
+	"read-input": ["readTables"],
+	"write-output": ["writeTables"],
+	"sync-back": ["syncBack"],
+	"read-assets": ["readAssets"],
+	"write-assets": ["writeAssets"],
+	"discover-sources": ["discoverByFolder"],
+	"sync-assets": ["assetSync"],
+	"public-read": ["readTables", "publicReadNoAuth"]
+};
+/**
+* Builds a full {@link ProviderCapabilitySet}, defaulting every unspecified
+* capability to `false`. Provider factories use this so they only need to
+* name the capabilities they actually support.
+*/
+function createCapabilitySet(overrides = {}) {
+	return {
+		...EMPTY_PROVIDER_CAPABILITIES,
+		...overrides
+	};
+}
+/** Returns the subset of `required` that `capabilities` does not have set to `true`. */
+function missingCapabilities(capabilities, required) {
+	return required.filter((capability) => !capabilities[capability]);
+}
+/**
+* Throws a descriptive error naming `providerName`, `operation` (if given), and every
+* missing capability, unless `capabilities` already satisfies all of `required`.
+*/
+function assertRequiredCapabilities(providerName, capabilities, required, operation) {
+	const missing = missingCapabilities(capabilities, required);
+	if (missing.length === 0) return;
+	const operationPart = operation ? ` for operation "${operation}"` : "";
+	throw new Error(`Provider "${providerName}" is missing required capabilities${operationPart}: ${missing.join(", ")}`);
+}
+/**
+* Convenience wrapper around {@link assertRequiredCapabilities} that looks up the
+* required capabilities for a named {@link ProviderOperation} via
+* {@link OPERATION_CAPABILITY_REQUIREMENTS}. This is the gate every pipeline stage
+* (read/write/sync/asset-sync/discovery) runs through before it executes.
+*/
+function assertOperationCapabilities(providerName, capabilities, operation) {
+	assertRequiredCapabilities(providerName, capabilities, OPERATION_CAPABILITY_REQUIREMENTS[operation], operation);
+}
+//#endregion
+//#region src/utils/validateEnv.ts
+/**
+* Validates that Google service-account credentials are present.
+* Does NOT require GOOGLE_SPREADSHEET_ID — the caller may create one on first run.
+*
+* When `GOOGLE_APPLICATION_CREDENTIALS` is set (Workload Identity Federation / ADC),
+* `GOOGLE_CLIENT_EMAIL` and `GOOGLE_PRIVATE_KEY` are not required.
+*/
+function validateCredentials() {
+	if (process.env.GOOGLE_APPLICATION_CREDENTIALS) return {
+		GOOGLE_CLIENT_EMAIL: process.env.GOOGLE_CLIENT_EMAIL ?? "",
+		GOOGLE_PRIVATE_KEY: process.env.GOOGLE_PRIVATE_KEY ?? ""
+	};
+	const missing = ["GOOGLE_CLIENT_EMAIL", "GOOGLE_PRIVATE_KEY"].filter((v) => !process.env[v]);
+	if (missing.length > 0) throw new Error(`Missing required environment variables: ${missing.join(", ")}\n\nMake sure these are set in your .env file or environment.\nAlternatively, set GOOGLE_APPLICATION_CREDENTIALS for Workload Identity Federation.`);
+	return {
+		GOOGLE_CLIENT_EMAIL: process.env.GOOGLE_CLIENT_EMAIL,
+		GOOGLE_PRIVATE_KEY: process.env.GOOGLE_PRIVATE_KEY
+	};
+}
+//#endregion
+//#region src/utils/auth.ts
+/**
+* Normalizes a private key string from the many different ways secret-storage
+* systems (GitHub Secrets, CI env vars, secret managers) encode it.
+*
+* Handles all of the following formats so the caller doesn't need to care
+* whether the value came from a GitHub Secret, a plain env var, a `.env` file
+* or any other source:
+*
+* - Real newlines  →  left as-is
+* - Literal `\n` two-char sequences  →  converted to real newlines
+* - Surrounding double or single quotes added by some tools  →  stripped
+*   (leading/trailing whitespace outside the quotes is also stripped)
+* - Windows-style `\r\n` line endings  →  normalised to `\n`
+*/
+function normalizePrivateKey(key) {
+	let normalized = key;
+	const outer = key.trim();
+	if (outer.startsWith("\"") && outer.endsWith("\"") || outer.startsWith("'") && outer.endsWith("'")) normalized = outer.slice(1, -1);
+	normalized = normalized.replace(/\\n/g, "\n");
+	normalized = normalized.replace(/\r\n/g, "\n");
+	return normalized;
+}
+/**
+* Low-level factory: creates a `GoogleAuth` instance for a given set of scopes.
+*
+* - When `credentials` are supplied, uses them directly (service-account key mode).
+* - When `credentials` is omitted, the instance relies on Application Default
+*   Credentials, i.e. the file pointed to by `GOOGLE_APPLICATION_CREDENTIALS`
+*   (Workload Identity Federation, `gcloud auth application-default login`, etc.).
+*
+* @internal Shared by Drive utilities and `createAuthClient()`. Import
+*   `createAuthClient()` for the standard Sheets use-case.
+*/
+function buildGoogleAuth(scopes, credentials) {
+	if (credentials) return new GoogleAuth({
+		credentials,
+		scopes
+	});
+	return new GoogleAuth({ scopes });
+}
+/**
+* Creates and returns a GoogleAuth client for Google Sheets API.
+*
+* Supports two authentication modes (checked in order):
+*
+* 1. **Workload Identity Federation / Application Default Credentials (ADC)**:
+*    Set `GOOGLE_APPLICATION_CREDENTIALS` to the path of a credential JSON file
+*    (e.g. written by `google-github-actions/auth`). No service-account key needed.
+*
+* 2. **Service account key** (classic):
+*    Set `GOOGLE_CLIENT_EMAIL` and `GOOGLE_PRIVATE_KEY` environment variables.
+*
+* @returns GoogleAuth client usable with google-spreadsheet and other Google APIs
+*/
+function createAuthClient() {
+	if (process.env.GOOGLE_APPLICATION_CREDENTIALS) return buildGoogleAuth(["https://www.googleapis.com/auth/spreadsheets"]);
+	const { GOOGLE_CLIENT_EMAIL, GOOGLE_PRIVATE_KEY } = validateCredentials();
+	return buildGoogleAuth(["https://www.googleapis.com/auth/spreadsheets"], {
+		client_email: GOOGLE_CLIENT_EMAIL,
+		private_key: normalizePrivateKey(GOOGLE_PRIVATE_KEY)
+	});
+}
+//#endregion
+//#region src/utils/publicSheetReader.ts
+/**
+* Fetches the raw response body from a URL using the built-in http/https module.
+* Follows a single redirect if the server issues one (3xx).
+*/
+function fetchUrl(url) {
+	return new Promise((resolve, reject) => {
+		const req = (url.startsWith("https") ? https : http).get(url, (res) => {
+			if (res.statusCode !== void 0 && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+				fetchUrl(res.headers.location).then(resolve).catch(reject);
+				return;
+			}
+			if (res.statusCode !== void 0 && res.statusCode >= 400) {
+				reject(/* @__PURE__ */ new Error(`HTTP ${res.statusCode} while fetching ${url}`));
+				return;
+			}
+			let data = "";
+			res.on("data", (chunk) => {
+				data += chunk.toString();
+			});
+			res.on("end", () => resolve(data));
+			res.on("error", reject);
+		});
+		req.on("error", reject);
+		req.end();
+	});
+}
+/**
+* Strips the JSONP wrapper that the Google Visualization API adds and parses
+* the inner JSON object.
+*
+* Expected wrapper format:
+*   `/*O_o*\/\ngoogle.visualization.Query.setResponse({...});`
+*/
+function parseGvizResponse(raw) {
+	const match = raw.match(/google\.visualization\.Query\.setResponse\((\{[\s\S]*?\})\)/);
+	if (!match) throw new Error("Unexpected response format from Google Visualization API. Make sure the spreadsheet is shared as \"Anyone with link can view\".");
+	return JSON.parse(match[1]);
+}
+/**
+* Reads rows from a *publicly accessible* Google Spreadsheet sheet without
+* requiring any service-account credentials or API key.
+*
+* The spreadsheet must be shared with **"Anyone with link can view"** (or
+* broader). Works via Google's Visualization (gviz) query endpoint which
+* is available at no cost for public sheets.
+*
+* @param spreadsheetId - The Google Spreadsheet ID (from the URL)
+* @param sheetName     - The sheet tab name to fetch
+* @returns An array of row objects keyed by column header
+* @throws  If the sheet is not accessible or the response cannot be parsed
+*/
+async function readPublicSheet(spreadsheetId, sheetName) {
+	const url = `https://docs.google.com/spreadsheets/d/${encodeURIComponent(spreadsheetId)}/gviz/tq?tqx=out:json&headers=1&sheet=${encodeURIComponent(sheetName)}`;
+	let raw;
+	try {
+		raw = await fetchUrl(url);
+	} catch (err) {
+		throw new Error(`Failed to fetch public sheet "${sheetName}" from spreadsheet "${spreadsheetId}"`, { cause: err });
+	}
+	let data;
+	try {
+		data = parseGvizResponse(raw);
+	} catch (err) {
+		throw new Error(`Failed to parse response for sheet "${sheetName}" in spreadsheet "${spreadsheetId}"`, { cause: err });
+	}
+	if (data.status !== "ok") {
+		const message = data.errors?.[0]?.message ?? "Unknown error";
+		throw new Error(`Google Visualization API returned an error for sheet "${sheetName}": ${message}`);
+	}
+	if (!data.table) return [];
+	const { cols, rows } = data.table;
+	const headers = cols.map((col) => col.label || col.id);
+	return rows.filter((row) => row && row.c).map((row) => {
+		const obj = {};
+		for (let i = 0; i < headers.length; i++) {
+			const cell = row.c?.[i];
+			obj[headers[i]] = cell?.v != null ? String(cell.v) : "";
+		}
+		return obj;
+	});
+}
+//#endregion
+//#region src/utils/rateLimiter.ts
+const DEFAULT_RETRIES = 3;
+const DEFAULT_MAX_DELAY_MS = 3e4;
+/**
+* Returns true when the error looks like a Google Sheets API rate-limit or
+* transient server error (HTTP 429 or 503).
+*/
+function isRateLimitError(err) {
+	if (!err || typeof err !== "object") return false;
+	const e = err;
+	const response = e["response"];
+	const status = typeof e["status"] === "number" ? e["status"] : typeof response?.["status"] === "number" ? response["status"] : void 0;
+	return status === 429 || status === 503;
+}
+/**
+* Calls `fn` and, on a rate-limit error (HTTP 429 / 503), retries with
+* exponential back-off.  Any other error is re-thrown immediately.
+*
+* @param fn           - The async operation to execute (and potentially retry)
+* @param label        - Human-readable label used in warning logs
+* @param baseDelayMs  - Base back-off delay in milliseconds (default: 1 000)
+* @param retries      - Maximum number of retry attempts (default: 3)
+* @param maxDelayMs   - Back-off ceiling in milliseconds (default: 30 000)
+* @returns The resolved value of `fn`
+* @throws  The last error if all retries are exhausted, or any non-rate-limit error immediately
+*/
+async function withRetry(fn, label, baseDelayMs = 1e3, retries = DEFAULT_RETRIES, maxDelayMs = DEFAULT_MAX_DELAY_MS) {
+	for (let attempt = 0; attempt <= retries; attempt++) try {
+		return await fn();
+	} catch (err) {
+		if (!isRateLimitError(err) || attempt === retries) throw err;
+		const backoff = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
+		console.warn(`[rate-limit] ${label}: retry ${attempt + 1}/${retries} in ${backoff} ms`);
+		await setTimeout(backoff);
+	}
+	/* c8 ignore next */
+	throw new Error("withRetry: unreachable");
+}
+//#endregion
+//#region src/utils/localeNormalizer.ts
+/**
+* Locale normalization utilities for converting simple language codes to full locale codes
+* and maintaining mappings between normalized codes and original spreadsheet headers
+*/
+/**
+* Returns the language prefix of a locale code (the part before the first
+* `-` or `_` separator), lowercased.
+*
+* Examples:
+* - `'en-US'` → `'en'`
+* - `'zh_CN'` → `'zh'`
+* - `'de'`    → `'de'`
+*
+* Used for language-family matching when an exact locale code is not found.
+*/
+function getLanguagePrefix(locale) {
+	return locale.toLowerCase().split(/[-_]/)[0];
+}
+/**
+* Common language to country mappings for normalization
+* Maps language codes to their most common country variants
+*/
+const LANGUAGE_TO_COUNTRY_MAP = {
+	en: "en-GB",
+	de: "de-DE",
+	fr: "fr-FR",
+	es: "es-ES",
+	it: "it-IT",
+	pt: "pt-PT",
+	pl: "pl-PL",
+	ru: "ru-RU",
+	zh: "zh-CN",
+	ja: "ja-JP",
+	ko: "ko-KR",
+	ar: "ar-SA",
+	hi: "hi-IN",
+	th: "th-TH",
+	vi: "vi-VN",
+	tr: "tr-TR",
+	nl: "nl-NL",
+	sv: "sv-SE",
+	da: "da-DK",
+	no: "no-NO",
+	fi: "fi-FI",
+	cs: "cs-CZ",
+	sk: "sk-SK",
+	hu: "hu-HU",
+	ro: "ro-RO",
+	bg: "bg-BG",
+	hr: "hr-HR",
+	sl: "sl-SI",
+	et: "et-EE",
+	lv: "lv-LV",
+	lt: "lt-LT",
+	el: "el-GR",
+	he: "he-IL",
+	uk: "uk-UA",
+	be: "be-BY"
+};
+/**
+* Normalizes a language code to include country code if missing
+* @param locale The original locale code from spreadsheet header
+* @returns Normalized locale with country code
+*/
+function normalizeLocaleCode(locale) {
+	if (!locale || typeof locale !== "string") return "";
+	const normalized = locale.toLowerCase().trim();
+	if (normalized.includes("-") || normalized.includes("_")) return normalized;
+	const withCountry = LANGUAGE_TO_COUNTRY_MAP[normalized];
+	if (withCountry) return withCountry;
+	if (normalized.length === 2 && /^[a-z]{2}$/.test(normalized)) return `${normalized}-${normalized.toUpperCase()}`;
+	return normalized;
+}
+/**
+* Creates a mapping between normalized locale codes and their original spreadsheet headers
+* @param originalHeaders Array of original header names from spreadsheet
+* @param keyColumn The key column name to exclude
+* @returns Object with normalized locales and header mapping
+*/
+function createLocaleMapping(originalHeaders, keyColumn) {
+	const localeMapping = {};
+	const originalMapping = {};
+	const normalizedLocales = [];
+	for (const header of originalHeaders) {
+		const headerLower = header.toLowerCase();
+		if (headerLower === keyColumn.toLowerCase()) continue;
+		if (!/^[a-z]{2}([_-][a-z]{2})?([_-][a-z]+)?$/.test(headerLower)) continue;
+		const normalized = normalizeLocaleCode(headerLower);
+		localeMapping[normalized] = header;
+		originalMapping[headerLower] = normalized;
+		normalizedLocales.push(normalized);
+	}
+	return {
+		normalizedLocales: [...new Set(normalizedLocales)],
+		localeMapping,
+		originalMapping
+	};
+}
+/**
+* Finds the original header name for a given normalized locale.
+*
+* Lookup order (most-specific → most-lenient):
+* 1. Direct key match  (`'en-us'` → `'en-US'`)
+* 2. Lowercase key match (`'EN-US'` → key `'en-us'`)
+* 3. Case-insensitive key comparison
+* 4. Language-family prefix match – e.g. `'en'` or `'en-GB'` finds `'en-US'`
+*    when `'en-US'` is the only English variant present in the mapping.
+*
+* @param normalizedLocale The normalized locale code (e.g., `'en-GB'`, `'en'`)
+* @param localeMapping Mapping from normalized locales to original headers
+* @returns Original header name or undefined if not found
+*/
+function getOriginalHeaderForLocale(normalizedLocale, localeMapping) {
+	let result = localeMapping[normalizedLocale];
+	if (result) return result;
+	const lowercaseLocale = normalizedLocale.toLowerCase();
+	result = localeMapping[lowercaseLocale];
+	if (result) return result;
+	for (const [key, value] of Object.entries(localeMapping)) if (key.toLowerCase() === lowercaseLocale) return value;
+	const inputLangCode = getLanguagePrefix(normalizedLocale);
+	for (const [key, value] of Object.entries(localeMapping)) if (getLanguagePrefix(key) === inputLangCode) return value;
+}
+/**
+* Resolves a locale code to the closest matching locale in an available list
+* using a three-step fallback strategy:
+*
+* 1. **Exact match** — `'en-us'` → `'en-us'`
+* 2. **Lowercase match** — `'en-US'` → `'en-us'`
+* 3. **Language-family prefix** — `'en'` or `'en-GB'` → `'en-us'`
+*    when `'en-us'` is the only English variant in `availableLocales`
+*
+* Returns `undefined` when no matching locale is found.
+*
+* This is the same strategy used internally by `findLocalChanges()` when
+* mapping local `languageData.json` keys to spreadsheet locale columns.
+*
+* @param locale           - The locale code to resolve (e.g. `'en'`, `'en-GB'`).
+* @param availableLocales - Array of locale codes to search (e.g. from
+*   `Object.keys(translations)` or the `locales` array from `getSpreadSheetData`).
+* @returns The matched locale code from `availableLocales`, or `undefined`.
+*
+* @example
+* ```ts
+* import { resolveLocaleWithFallback } from '@el-j/google-sheet-translations';
+*
+* const locales = ['en-us', 'de-de', 'fr-fr'];
+* resolveLocaleWithFallback('en', locales);    // → 'en-us'
+* resolveLocaleWithFallback('en-GB', locales); // → 'en-us'
+* resolveLocaleWithFallback('de-DE', locales); // → 'de-de'
+* resolveLocaleWithFallback('ja', locales);    // → undefined
+* ```
+*/
+function resolveLocaleWithFallback(locale, availableLocales) {
+	if (availableLocales.includes(locale)) return locale;
+	const lower = locale.toLowerCase();
+	const lowerMatch = availableLocales.find((l) => l === lower);
+	if (lowerMatch) return lowerMatch;
+	const langCode = getLanguagePrefix(lower);
+	return availableLocales.find((l) => getLanguagePrefix(l) === langCode);
+}
+//#endregion
+//#region src/utils/spreadsheetFormulas.ts
+/**
+* Converts a 0-based column index to a spreadsheet column letter (A, B, ..., Z, AA, AB, ...)
+*
+* @param index - 0-based index of the column
+* @returns Spreadsheet column letter (e.g. 0 -> 'A', 26 -> 'AA')
+*/
+function columnIndexToLetter(index) {
+	let result = "";
+	let i = index;
+	do {
+		result = String.fromCharCode(65 + i % 26) + result;
+		i = Math.floor(i / 26) - 1;
+	} while (i >= 0);
+	return result;
+}
+/**
+* Determines the formula argument separator based on the spreadsheet's locale.
+*
+* Google Sheets uses `,` for English, CJK and a few other locales, but `;` for
+* the majority of European locales (German, French, Spanish, Italian, …).
+* The Google Sheets API (`valueInputOption: USER_ENTERED`) parses formulas
+* according to the spreadsheet's locale, so we must match the separator.
+*
+* @param doc - GoogleSpreadsheet document instance
+* @returns `","` or `";"` – the argument separator to use in generated formulas.
+*/
+function getFormulaSeparator(doc) {
+	try {
+		const locale = doc._rawProperties?.locale || "";
+		if (/^(en|ja|ko|zh|th|id|ms)/i.test(locale)) return ",";
+	} catch {}
+	return ";";
+}
+/**
+* Wraps a spreadsheet cell reference in a formula that extracts the
+* GOOGLETRANSLATE-compatible language code from a locale header cell.
+*
+* For most locales the ISO 639-1 prefix before the first `"-"` is extracted
+* (e.g. header `"tr-TR"` → `"tr"`, `"en-US"` → `"en"`).
+*
+* For Chinese variants (`zh-TW`, `zh-CN`) the full lowercased code is
+* preserved because GOOGLETRANSLATE distinguishes Simplified from Traditional
+* Chinese.
+*
+* Bare codes without a `"-"` are returned as-is (e.g. `"en"` → `"en"`).
+*
+* All inner function calls use the supplied `sep` so the generated fragment
+* is consistent with the spreadsheet's locale.
+*
+* @param cellRef - A spreadsheet cell reference string, e.g. `$B$1` or `C$1`
+* @param sep     - Formula argument separator (`","` or `";"`)
+* @returns Formula fragment string for language code extraction
+*/
+function langCodeFormula(cellRef, sep) {
+	const prefix = `LOWER(IFERROR(LEFT(${cellRef}${sep}FIND("-"${sep}${cellRef})-1)${sep}${cellRef}))`;
+	return `IF(LOWER(LEFT(${cellRef}${sep}3))="zh-"${sep}${`LOWER(${cellRef})`}${sep}${prefix})`;
+}
+//#endregion
+//#region src/utils/spreadsheetUpdater.ts
+/**
+* Updates the Google Spreadsheet with new keys from local data.
+*
+* 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 dynamically extracts the GOOGLETRANSLATE-compatible language code from the header
+*   cell at spreadsheet-evaluation time (e.g. header "tr-TR" → "tr") and also preserves Chinese
+*   variants (zh-TW, zh-CN) where the region is meaningful
+* - The formula format is:
+*   =GOOGLETRANSLATE(INDIRECT(srcCol&ROW()); langCodeFormula($srcCol$1); langCodeFormula(tgtCol$1))
+* - All formula separators are set to match the spreadsheet's locale (`;` or `,`)
+* - 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
+* (e.g. "ui") are bootstrapped on the first sync without requiring manual spreadsheet setup.
+*
+* 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 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 - 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
+*   columns are overwritten with GOOGLETRANSLATE formulas.  When false (default) only empty cells
+*   receive a formula.
+* @returns Promise that resolves when the update is complete
+*/
+async function updateSpreadsheetWithLocalChanges(doc, changes, waitSeconds, autoTranslate = false, localeMapping = {}, override = false) {
+	console.log("Updating spreadsheet with local changes...");
+	const baseDelayMs = waitSeconds * 1e3;
+	const sep = getFormulaSeparator(doc);
+	for (const sheetTitle of new Set(Object.values(changes).flatMap((locale) => Object.keys(locale)))) {
+		if (sheetTitle === "i18n") {
+			console.log(`Skipping reserved metadata sheet "${sheetTitle}" – its content is managed separately.`);
+			continue;
+		}
+		console.log(`Processing sheet: ${sheetTitle}`);
+		let sheet = doc.sheetsByTitle[sheetTitle];
+		if (!sheet) {
+			const localeHeaders = Object.values(localeMapping);
+			if (localeHeaders.length === 0) {
+				console.warn(`Sheet "${sheetTitle}" not found in the document, cannot update`);
+				continue;
+			}
+			console.log(`Sheet "${sheetTitle}" not found — creating it with ${localeHeaders.length} locale column(s).`);
+			sheet = await withRetry(() => doc.addSheet({
+				title: sheetTitle,
+				headerValues: ["key", ...localeHeaders]
+			}), `addSheet: ${sheetTitle}`, baseDelayMs);
+		}
+		if (!sheet) {
+			console.warn(`Sheet "${sheetTitle}" could not be found or created, skipping.`);
+			continue;
+		}
+		const rows = await withRetry(() => sheet.getRows(), `getRows: ${sheetTitle}`, baseDelayMs);
+		let headerRow;
+		let originalHeaders;
+		if (rows.length > 0) {
+			originalHeaders = Object.keys(rows[0].toObject());
+			headerRow = originalHeaders.map((h) => h.toLowerCase());
+		} else {
+			const localeHeaders = Object.values(localeMapping);
+			if (localeHeaders.length === 0) {
+				console.warn(`No rows found in sheet "${sheetTitle}", cannot update`);
+				continue;
+			}
+			originalHeaders = ["key", ...localeHeaders];
+			headerRow = originalHeaders.map((h) => h.toLowerCase());
+		}
+		const keyColumn = headerRow[0];
+		const locales = headerRow.filter((key) => key !== keyColumn);
+		const existingKeys = /* @__PURE__ */ new Map();
+		rows.forEach((row, index) => {
+			const rowData = row.toObject();
+			const keyField = Object.keys(rowData).find((k) => k.toLowerCase() === keyColumn);
+			if (keyField && rowData[keyField]) existingKeys.set(rowData[keyField].toString().toLowerCase(), index);
+		});
+		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];
+			for (const key of Object.keys(localeData)) {
+				const keyLower = key.toLowerCase();
+				if (!existingKeys.has(keyLower)) {
+					if (!newKeys.has(keyLower)) {
+						newKeys.set(keyLower, { [keyColumn]: key });
+						keyLocalesMap.set(keyLower, /* @__PURE__ */ new Map());
+					}
+					let localeHeader = getOriginalHeaderForLocale(locale, localeMapping);
+					if (!localeHeader) {
+						const localeLang = getLanguagePrefix(locale);
+						localeHeader = originalHeaders.find((h) => getLanguagePrefix(h) === localeLang);
+					}
+					if (localeHeader) {
+						const theKey = newKeys.get(keyLower);
+						if (!theKey) {
+							console.warn(`Key "${key}" not found in newKeys map, skipping...`);
+							continue;
+						}
+						const value = String(localeData[key]);
+						theKey[localeHeader] = value;
+						const localesForKey = keyLocalesMap.get(keyLower);
+						if (localesForKey) localesForKey.set(locale.toLowerCase(), localeHeader);
+					}
+				} else {
+					const rowIndex = existingKeys.get(keyLower);
+					const row = rows[rowIndex];
+					let localeHeader = getOriginalHeaderForLocale(locale, localeMapping);
+					if (!localeHeader) {
+						const localeLang = getLanguagePrefix(locale);
+						localeHeader = Object.keys(row.toObject()).find((h) => getLanguagePrefix(h) === localeLang);
+					}
+					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];
+									if (!existingValue || existingValue.toString().trim() === "" || override) {
+										const targetColumnLetter = columnIndexToLetter(targetHeaderIndex);
+										row.set(exactTargetHeader, `=GOOGLETRANSLATE(INDIRECT("${sourceColumnLetter}"&ROW())${sep}${langCodeFormula(`$${sourceColumnLetter}$1`, sep)}${sep}${langCodeFormula(`${targetColumnLetter}$1`, sep)})`);
+									}
+								}
+							}
+						}
+						try {
+							await withRetry(() => row.save(), `save row ${rowIndex} in ${sheetTitle}`, baseDelayMs);
+							if (baseDelayMs > 0) await setTimeout(baseDelayMs);
+						} catch (err) {
+							console.error(`Failed to save row for key "${keyLower}" in sheet "${sheetTitle}":`, err);
+						}
+					}
+				}
+			}
+		}
+		if (newKeys.size > 0) {
+			console.log(`Adding ${newKeys.size} new keys to sheet ${sheetTitle}...`);
+			if (autoTranslate) for (const [keyLower, rowData] of newKeys.entries()) {
+				const localesWithValues = keyLocalesMap.get(keyLower);
+				if (localesWithValues && localesWithValues.size > 0) {
+					const [, sourceHeader] = [...localesWithValues.entries()][0];
+					for (const localeHeader of locales) {
+						const localeLower = localeHeader.toLowerCase();
+						const rowDataKey = Object.keys(rowData).find((k) => k.toLowerCase() === localeLower);
+						if (localesWithValues.has(localeLower) || rowDataKey && rowData[rowDataKey]) continue;
+						const exactHeaderName = originalHeaders.find((h) => h.toLowerCase() === localeLower);
+						if (exactHeaderName) {
+							const sourceHeaderIndex = headerRow.indexOf(sourceHeader.toLowerCase());
+							const targetHeaderIndex = headerRow.indexOf(exactHeaderName.toLowerCase());
+							if (sourceHeaderIndex < 0 || targetHeaderIndex < 0) continue;
+							const sourceColumnLetter = columnIndexToLetter(sourceHeaderIndex);
+							const targetColumnLetter = columnIndexToLetter(targetHeaderIndex);
+							rowData[exactHeaderName] = `=GOOGLETRANSLATE(INDIRECT("${sourceColumnLetter}"&ROW())${sep}${langCodeFormula(`$${sourceColumnLetter}$1`, sep)}${sep}${langCodeFormula(`${targetColumnLetter}$1`, sep)})`;
+						}
+					}
+				}
+			}
+			const newRows = Array.from(newKeys.values());
+			const CHUNK_SIZE = 5;
+			for (let i = 0; i < newRows.length; i += CHUNK_SIZE) {
+				const chunk = newRows.slice(i, i + CHUNK_SIZE);
+				await withRetry(() => sheet.addRows(chunk), `addRows chunk ${Math.floor(i / CHUNK_SIZE) + 1} in ${sheetTitle}`, baseDelayMs);
+				if (baseDelayMs > 0 && i + CHUNK_SIZE < newRows.length) await setTimeout(baseDelayMs);
+			}
+		}
+	}
+	console.log("Finished updating spreadsheet with local changes.");
+}
+//#endregion
+//#region src/utils/dataConverter/findLocalChanges.ts
+/**
+* Compares local languageData.json with spreadsheet data to find new keys.
+*
+* A key is considered "new" when:
+* - No matching locale exists in `spreadsheetData` for that locale, OR
+* - The sheet or key is absent for the resolved locale.
+*
+* Locale matching is fuzzy: `'en'` and `'en-GB'` will both match against
+* an `'en-us'` entry in `spreadsheetData` (language-family resolution via
+* `resolveLocaleWithFallback`).
+*
+* @param localData - Data from local languageData.json file
+* @param spreadsheetData - Data fetched from the spreadsheet
+* @returns Object with new keys that are in localData but not in spreadsheetData
+*/
+function findLocalChanges(localData, spreadsheetData) {
+	const changes = {};
+	for (const locale of Object.keys(localData)) {
+		if (!localData[locale]) continue;
+		const resolvedLocale = resolveLocaleWithFallback(locale, Object.keys(spreadsheetData));
+		for (const sheet of Object.keys(localData[locale])) {
+			if (!localData[locale][sheet]) continue;
+			if (sheet === "i18n") continue;
+			for (const key of Object.keys(localData[locale][sheet])) if (!resolvedLocale || !spreadsheetData[resolvedLocale]?.[sheet] || !spreadsheetData[resolvedLocale][sheet][key]) {
+				if (!changes[locale]) changes[locale] = {};
+				if (!changes[locale][sheet]) changes[locale][sheet] = {};
+				changes[locale][sheet][key] = localData[locale][sheet][key];
+			}
+		}
+	}
+	return changes;
+}
+//#endregion
+//#region src/providers/google/providers.ts
+const INPUT_CAPABILITIES = createCapabilitySet({
+	readTables: true,
+	publicReadNoAuth: true,
+	discoverByFolder: true
+});
+const OUTPUT_CAPABILITIES = createCapabilitySet({
+	writeTables: true,
+	autoTranslateFormula: true
+});
+const SYNC_CAPABILITIES = createCapabilitySet({
+	syncBack: true,
+	writeTables: true,
+	autoTranslateFormula: true
+});
+function createDefaultDeps$4() {
+	return {
+		createAuthClient,
+		createSpreadsheetClient: (spreadsheetId, authClient) => new GoogleSpreadsheet(spreadsheetId, authClient),
+		readPublicSheet,
+		withRetry,
+		updateSpreadsheetWithLocalChanges,
+		findLocalChanges,
+		logger: console
+	};
+}
+function resolveSpreadsheetId(spreadsheetId) {
+	const resolved = spreadsheetId ?? process.env.GOOGLE_SPREADSHEET_ID;
+	if (!resolved) throw new Error("No spreadsheet ID provided. Set GOOGLE_SPREADSHEET_ID or pass spreadsheetId in provider options.");
+	return resolved;
+}
+function getWaitSeconds(waitSeconds) {
+	return waitSeconds ?? 1;
+}
+function countTranslationLeafKeys(data) {
+	return Object.values(data).flatMap((localeData) => Object.values(localeData)).reduce((total, sheetData) => total + Object.keys(sheetData).length, 0);
+}
+function hasAnyChanges(data) {
+	return Object.keys(data).length > 0 && Object.values(data).some((l) => Object.keys(l).length > 0);
+}
+/**
+* Creates a {@link TranslationInputProvider} backed by Google Sheets. When
+* `options.publicSheet` is true, reads via the no-auth public CSV export path
+* (`publicReadNoAuth` capability); otherwise authenticates via
+* {@link createAuthClient} and reads through the Google Sheets API, skipping
+* (and warning about) any requested table name that has no matching sheet.
+*/
+function createGoogleSheetsInputProvider(options = {}, depsOverrides = {}) {
+	const deps = {
+		...createDefaultDeps$4(),
+		...depsOverrides
+	};
+	return {
+		kind: "input",
+		providerId: options.providerId ?? "google-sheets",
+		displayName: options.displayName ?? "Google Sheets Input",
+		capabilities: INPUT_CAPABILITIES,
+		async readTables(request) {
+			const tableNames = (request.tableNames ?? []).filter(Boolean);
+			if (tableNames.length === 0) return { tables: [] };
+			const spreadsheetId = resolveSpreadsheetId(options.spreadsheetId);
+			const baseDelayMs = getWaitSeconds(options.waitSeconds) * 1e3;
+			if (options.publicSheet) return {
+				tables: await Promise.all(tableNames.map(async (tableName) => {
+					const rows = await deps.withRetry(() => deps.readPublicSheet(spreadsheetId, tableName), `readPublicSheet: ${tableName}`, baseDelayMs);
+					return {
+						tableId: `${spreadsheetId}:${tableName}`,
+						tableName,
+						rows,
+						metadata: { sourceMode: "public" }
+					};
+				})),
+				metadata: {
+					spreadsheetId,
+					sourceMode: "public"
+				}
+			};
+			const authClient = deps.createAuthClient();
+			const doc = deps.createSpreadsheetClient(spreadsheetId, authClient);
+			await deps.withRetry(() => doc.loadInfo(true), "loadInfo", baseDelayMs);
+			const tables = [];
+			for (const tableName of tableNames) {
+				const sheet = doc.sheetsByTitle[tableName];
+				if (!sheet) {
+					deps.logger.warn(`Sheet "${tableName}" not found in the document`);
+					continue;
+				}
+				const googleRows = await deps.withRetry(() => sheet.getRows({ limit: options.rowLimit ?? 100 }), `getRows: ${tableName}`, baseDelayMs);
+				tables.push({
+					tableId: `${spreadsheetId}:${tableName}`,
+					tableName,
+					rows: googleRows.map((row) => row.toObject()),
+					metadata: { sourceMode: "authenticated" }
+				});
+			}
+			return {
+				tables,
+				metadata: {
+					spreadsheetId,
+					sourceMode: "authenticated"
+				}
+			};
+		}
+	};
+}
+/**
+* Creates a {@link TranslationOutputProvider} that authenticates and writes the full
+* translation set to a Google Sheets spreadsheet via {@link updateSpreadsheetWithLocalChanges},
+* optionally auto-translating missing cells with a formula (`autoTranslate`) and
+* optionally overwriting existing non-empty cells (`override`).
+*/
+function createGoogleSheetsOutputProvider(options = {}, depsOverrides = {}) {
+	const deps = {
+		...createDefaultDeps$4(),
+		...depsOverrides
+	};
+	return {
+		kind: "output",
+		providerId: options.providerId ?? "google-sheets",
+		displayName: options.displayName ?? "Google Sheets Output",
+		capabilities: OUTPUT_CAPABILITIES,
+		async writeTranslations(payload) {
+			const spreadsheetId = resolveSpreadsheetId(options.spreadsheetId);
+			const authClient = deps.createAuthClient();
+			const doc = deps.createSpreadsheetClient(spreadsheetId, authClient);
+			await deps.withRetry(() => doc.loadInfo(true), "loadInfo", getWaitSeconds(options.waitSeconds) * 1e3);
+			await deps.updateSpreadsheetWithLocalChanges(doc, payload.translations, getWaitSeconds(options.waitSeconds), options.autoTranslate ?? false, options.localeMapping ?? payload.localeMapping ?? {}, options.override ?? false);
+			const updatedSheets = new Set(Object.values(payload.translations).flatMap((localeData) => Object.keys(localeData)));
+			return {
+				wroteFiles: [],
+				metadata: {
+					spreadsheetId,
+					updatedSheets: Array.from(updatedSheets),
+					estimatedUpdatedKeys: countTranslationLeafKeys(payload.translations)
+				}
+			};
+		}
+	};
+}
+/**
+* Creates a {@link TranslationSyncProvider} that computes local-only changes via
+* {@link findLocalChanges} (comparing `localTranslations` against `remoteTranslations`)
+* and, if any exist, writes just those changed keys back to the spreadsheet. Returns
+* early with `changedKeys: 0` when there is no local diff, avoiding an unnecessary
+* authenticated round-trip.
+*/
+function createGoogleSheetsSyncProvider(options = {}, depsOverrides = {}) {
+	const deps = {
+		...createDefaultDeps$4(),
+		...depsOverrides
+	};
+	return {
+		kind: "sync",
+		providerId: options.providerId ?? "google-sheets",
+		displayName: options.displayName ?? "Google Sheets Sync",
+		capabilities: SYNC_CAPABILITIES,
+		async syncTranslations(payload) {
+			const changes = deps.findLocalChanges(payload.localTranslations, payload.remoteTranslations);
+			if (!hasAnyChanges(changes)) return {
+				changedKeys: 0,
+				skippedKeys: 0,
+				metadata: { reason: "no-local-diff" }
+			};
+			const spreadsheetId = resolveSpreadsheetId(options.spreadsheetId);
+			const authClient = deps.createAuthClient();
+			const doc = deps.createSpreadsheetClient(spreadsheetId, authClient);
+			await deps.withRetry(() => doc.loadInfo(true), "loadInfo", getWaitSeconds(options.waitSeconds) * 1e3);
+			await deps.updateSpreadsheetWithLocalChanges(doc, changes, getWaitSeconds(options.waitSeconds), options.autoTranslate ?? false, options.localeMapping ?? {}, options.override ?? false);
+			return {
+				changedKeys: countTranslationLeafKeys(changes),
+				skippedKeys: 0,
+				metadata: { spreadsheetId }
+			};
+		}
+	};
+}
+//#endregion
+//#region src/providers/cryptpad/provider.ts
+const CRYPTPAD_CSV_INPUT_CAPABILITIES = createCapabilitySet({
+	readTables: true,
+	publicReadNoAuth: true
+});
+function createDefaultDeps$3() {
+	return {
+		async fetchCsv(url, signal) {
+			const response = await fetch(url, { signal });
+			if (!response.ok) throw new Error(`Failed to fetch CSV from "${url}" (HTTP ${response.status})`);
+			return response.text();
+		},
+		async readCsvFile(filePath) {
+			return fs$1.readFile(filePath, "utf8");
+		}
+	};
+}
+function sourceId(source) {
+	return source.tableId ?? source.filePath ?? source.url ?? source.tableName;
+}
+function parseCsvRows(csvText, delimiter) {
+	return parse(csvText, {
+		columns: true,
+		skip_empty_lines: true,
+		trim: true,
+		bom: true,
+		relax_column_count: true,
+		delimiter
+	}).map((record) => {
+		const row = {};
+		for (const [key, value] of Object.entries(record)) row[key] = value == null ? "" : String(value);
+		return row;
+	});
+}
+/**
+* Creates a read-only {@link TranslationInputProvider} that reads one or more CSV
+* sources (local files or public export URLs) as canonical tables. This is a CSV-only
+* MVP: it has no output/sync capability, so it is always paired with another provider
+* (e.g. `cryptpad-workspace`) for write-back. Public URLs require no authentication,
+* reflected in `publicReadNoAuth: true`.
+*/
+function createCryptPadCsvInputProvider(options, depsOverrides = {}) {
+	if (!options.sources || options.sources.length === 0) throw new Error("CryptPad CSV provider requires at least one source.");
+	const deps = {
+		...createDefaultDeps$3(),
+		...depsOverrides
+	};
+	return {
+		kind: "input",
+		providerId: options.providerId ?? "cryptpad-csv",
+		displayName: options.displayName ?? "CryptPad CSV Input",
+		capabilities: CRYPTPAD_CSV_INPUT_CAPABILITIES,
+		async readTables(request) {
+			const requested = new Set((request.tableNames ?? []).filter(Boolean));
+			const selectedSources = requested.size === 0 ? options.sources : options.sources.filter((source) => requested.has(source.tableName));
+			return {
+				tables: await Promise.all(selectedSources.map(async (source) => {
+					const csvText = source.url ? await deps.fetchCsv(source.url, request.signal) : source.filePath ? await deps.readCsvFile(source.filePath) : "";
+					if (!csvText) throw new Error(`Source "${source.tableName}" must define either url or filePath.`);
+					return {
+						tableId: sourceId(source),
+						tableName: source.tableName,
+						rows: parseCsvRows(csvText, options.delimiter),
+						sourcePath: source.url ?? source.filePath,
+						metadata: { sourceKind: source.url ? "url" : "file" }
+					};
+				})),
+				metadata: {
+					provider: "cryptpad-csv",
+					sourceCount: selectedSources.length
+				}
+			};
+		}
+	};
+}
+//#endregion
+//#region src/providers/syncEngine.ts
+function pathKey(locale, sheet, key) {
+	return `${locale}::${sheet}::${key}`;
+}
+function splitPath(key) {
+	const [locale, sheet, nestedKey] = key.split("::");
+	return {
+		locale,
+		sheet,
+		key: nestedKey
+	};
+}
+function flattenTranslations(translations) {
+	const result = /* @__PURE__ */ new Map();
+	for (const [locale, sheets] of Object.entries(translations)) for (const [sheet, entries] of Object.entries(sheets)) for (const [key, rawValue] of Object.entries(entries)) result.set(pathKey(locale, sheet, key), {
+		locale,
+		sheet,
+		key,
+		value: String(rawValue ?? "")
+	});
+	return result;
+}
+function getChangeType(beforeValue, afterValue) {
+	if (beforeValue === void 0 && afterValue !== void 0) return "insert";
+	if (beforeValue !== void 0 && afterValue === void 0) return "delete";
+	return "update";
+}
+function diffChanges(base, next) {
+	const keys = /* @__PURE__ */ new Set([...base.keys(), ...next.keys()]);
+	const changes = [];
+	for (const key of keys) {
+		const baseValue = base.get(key)?.value;
+		const nextValue = next.get(key)?.value;
+		if (baseValue === nextValue) continue;
+		const details = splitPath(key);
+		changes.push({
+			path: key,
+			locale: details.locale,
+			sheet: details.sheet,
+			key: details.key,
+			type: getChangeType(baseValue, nextValue),
+			before: baseValue,
+			after: nextValue
+		});
+	}
+	return changes.sort((a, b) => a.path.localeCompare(b.path));
+}
+function isConflict(baseValue, localValue, remoteValue) {
+	if (localValue === remoteValue) return;
+	if (baseValue === localValue || baseValue === remoteValue) return;
+	if (localValue === void 0 || remoteValue === void 0) return "delete-vs-update";
+	return "diverged-update";
+}
+function setValue(target, locale, sheet, key, value) {
+	if (value === void 0) {
+		if (!target[locale]?.[sheet]) return;
+		delete target[locale][sheet][key];
+		if (Object.keys(target[locale][sheet]).length === 0) delete target[locale][sheet];
+		if (Object.keys(target[locale]).length === 0) delete target[locale];
+		return;
+	}
+	if (!target[locale]) target[locale] = {};
+	if (!target[locale][sheet]) target[locale][sheet] = {};
+	target[locale][sheet][key] = value;
+}
+function cloneTranslations(input) {
+	return JSON.parse(JSON.stringify(input));
+}
+/**
+* Diffs `localTranslations` and `remoteTranslations` each against `baseTranslations`
+* (flattened to `locale::sheet::key` paths) and returns the resulting local changes,
+* remote changes, and any keys that changed on both sides to a genuinely different
+* value (conflicts). Does not merge anything — see {@link resolveSyncPlan} for that.
+*/
+function buildSyncPlan(input) {
+	const base = flattenTranslations(input.baseTranslations);
+	const local = flattenTranslations(input.localTranslations);
+	const remote = flattenTranslations(input.remoteTranslations);
+	const localChanges = diffChanges(base, local);
+	const remoteChanges = diffChanges(base, remote);
+	const localChanged = new Map(localChanges.map((change) => [change.path, change]));
+	const remoteChanged = new Map(remoteChanges.map((change) => [change.path, change]));
+	const overlap = new Set([...localChanged.keys()].filter((path) => remoteChanged.has(path)));
+	const conflicts = [];
+	for (const path of overlap) {
+		const details = splitPath(path);
+		const baseValue = base.get(path)?.value;
+		const localValue = local.get(path)?.value;
+		const remoteValue = remote.get(path)?.value;
+		const reason = isConflict(baseValue, localValue, remoteValue);
+		if (!reason) continue;
+		conflicts.push({
+			path,
+			locale: details.locale,
+			sheet: details.sheet,
+			key: details.key,
+			baseValue,
+			localValue,
+			remoteValue,
+			reason
+		});
+	}
+	return {
+		localChanges,
+		remoteChanges,
+		conflicts: conflicts.sort((a, b) => a.path.localeCompare(b.path))
+	};
+}
+/**
+* Runs {@link buildSyncPlan} and merges the result into a copy of `remoteTranslations`
+* according to `policy`:
+* - `remote-wins` — non-conflicting local changes apply; conflicting keys keep the remote value.
+* - `local-wins` — every local change applies, including over conflicts.
+* - `manual` — non-conflicting local changes apply; conflicts are left as-is and counted in `skippedConflicts` for human review.
+*/
+function resolveSyncPlan(input, policy) {
+	const plan = buildSyncPlan(input);
+	const merged = cloneTranslations(input.remoteTranslations);
+	const conflictMap = new Map(plan.conflicts.map((conflict) => [conflict.path, conflict]));
+	let appliedLocalChanges = 0;
+	for (const change of plan.localChanges) {
+		if (conflictMap.get(change.path)) {
+			if (policy === "remote-wins" || policy === "manual") continue;
+			setValue(merged, change.locale, change.sheet, change.key, change.after);
+			appliedLocalChanges++;
+			continue;
+		}
+		setValue(merged, change.locale, change.sheet, change.key, change.after);
+		appliedLocalChanges++;
+	}
+	if (policy === "local-wins") return {
+		policy,
+		mergedTranslations: merged,
+		appliedLocalChanges,
+		appliedRemoteChanges: 0,
+		skippedConflicts: 0
+	};
+	return {
+		policy,
+		mergedTranslations: merged,
+		appliedLocalChanges,
+		appliedRemoteChanges: 0,
+		skippedConflicts: policy === "manual" ? plan.conflicts.length : 0
+	};
+}
+//#endregion
+//#region src/providers/cryptpad/fullProvider.ts
+const CRYPTPAD_WORKSPACE_OUTPUT_CAPABILITIES = createCapabilitySet({ writeTables: true });
+const CRYPTPAD_WORKSPACE_SYNC_CAPABILITIES = createCapabilitySet({
+	syncBack: true,
+	writeTables: true
+});
+function clone(value) {
+	return JSON.parse(JSON.stringify(value));
+}
+function mergeTranslations$1(base, patch) {
+	const result = clone(base);
+	for (const [locale, sheets] of Object.entries(patch)) {
+		if (!result[locale]) result[locale] = {};
+		for (const [sheet, keys] of Object.entries(sheets)) {
+			if (!result[locale][sheet]) result[locale][sheet] = {};
+			for (const [key, value] of Object.entries(keys)) result[locale][sheet][key] = value;
+		}
+	}
+	return result;
+}
+function countChangedKeys(data) {
+	return Object.values(data).flatMap((sheets) => Object.values(sheets)).reduce((count, keys) => count + Object.keys(keys).length, 0);
+}
+function normalizeRevision(value) {
+	return Number.isFinite(value) ? Number(value) : 0;
+}
+function createDefaultDeps$2() {
+	return {
+		async readSnapshot(filePath) {
+			try {
+				const payload = await fs$1.readFile(filePath, "utf8");
+				const parsed = JSON.parse(payload);
+				return {
+					revision: normalizeRevision(parsed.revision),
+					translations: parsed.translations ?? {},
+					metadata: parsed.metadata
+				};
+			} catch (error) {
+				if (error.code === "ENOENT") return {
+					revision: 0,
+					translations: {}
+				};
+				throw error;
+			}
+		},
+		async writeSnapshot(filePath, snapshot) {
+			await fs$1.mkdir(path.dirname(filePath), { recursive: true });
+			await fs$1.writeFile(filePath, `${JSON.stringify(snapshot, null, 2)}\n`, "utf8");
+		}
+	};
+}
+function assertRevision(snapshot, expectedRevision) {
+	if (expectedRevision === void 0) return;
+	if (snapshot.revision !== expectedRevision) throw new Error(`CryptPad revision mismatch: expected ${expectedRevision}, received ${snapshot.revision}.`);
+}
+/**
+* Creates a {@link TranslationOutputProvider} that writes translations into a local
+* JSON snapshot file representing CryptPad workspace state. Each write reads the
+* current snapshot, checks `expectedRevision` (if set) for optimistic-concurrency
+* safety, deep-merges the new translations over the existing ones, and writes back
+* with the revision incremented by one.
+*/
+function createCryptPadWorkspaceOutputProvider(options, depsOverrides = {}) {
+	const deps = {
+		...createDefaultDeps$2(),
+		...depsOverrides
+	};
+	return {
+		kind: "output",
+		providerId: options.providerId ?? "cryptpad-workspace",
+		displayName: options.displayName ?? "CryptPad Workspace Output",
+		capabilities: CRYPTPAD_WORKSPACE_OUTPUT_CAPABILITIES,
+		async writeTranslations(payload) {
+			const snapshot = await deps.readSnapshot(options.filePath, options.authToken);
+			assertRevision(snapshot, options.expectedRevision);
+			const merged = mergeTranslations$1(snapshot.translations, payload.translations);
+			const nextRevision = snapshot.revision + 1;
+			await deps.writeSnapshot(options.filePath, {
+				revision: nextRevision,
+				translations: merged,
+				metadata: {
+					...snapshot.metadata,
+					lastWriteProvider: "cryptpad-workspace-output"
+				}
+			}, options.authToken);
+			return {
+				wroteFiles: [options.filePath],
+				metadata: {
+					revision: nextRevision,
+					changedKeys: countChangedKeys(payload.translations)
+				}
+			};
+		}
+	};
+}
+function buildSyncInput(payload) {
+	return {
+		baseTranslations: payload.metadata?.baseTranslations ?? payload.remoteTranslations,
+		localTranslations: payload.localTranslations,
+		remoteTranslations: payload.remoteTranslations
+	};
+}
+/**
+* Creates a {@link TranslationSyncProvider} that reconciles local translation changes
+* against the CryptPad workspace snapshot using {@link resolveSyncPlan} (three-way
+* diff against `payload.metadata.baseTranslations`, falling back to the remote
+* snapshot as base) and the configured `conflictPolicy`. Like the output provider,
+* it checks `expectedRevision` before writing and increments the revision on write.
+*/
+function createCryptPadWorkspaceSyncProvider(options, depsOverrides = {}) {
+	const deps = {
+		...createDefaultDeps$2(),
+		...depsOverrides
+	};
+	return {
+		kind: "sync",
+		providerId: options.providerId ?? "cryptpad-workspace",
+		displayName: options.displayName ?? "CryptPad Workspace Sync",
+		capabilities: CRYPTPAD_WORKSPACE_SYNC_CAPABILITIES,
+		async syncTranslations(payload) {
+			const snapshot = await deps.readSnapshot(options.filePath, options.authToken);
+			assertRevision(snapshot, options.expectedRevision ?? (Number.isFinite(payload.metadata?.expectedRevision) ? Number(payload.metadata?.expectedRevision) : void 0));
+			const resolution = resolveSyncPlan(buildSyncInput(payload), options.conflictPolicy ?? "manual");
+			const nextRevision = snapshot.revision + 1;
+			await deps.writeSnapshot(options.filePath, {
+				revision: nextRevision,
+				translations: resolution.mergedTranslations,
+				metadata: {
+					...snapshot.metadata,
+					lastSyncProvider: "cryptpad-workspace-sync",
+					policy: resolution.policy
+				}
+			}, options.authToken);
+			return {
+				changedKeys: resolution.appliedLocalChanges,
+				skippedKeys: resolution.skippedConflicts,
+				metadata: {
+					revision: nextRevision,
+					policy: resolution.policy
+				}
+			};
+		}
+	};
+}
+//#endregion
+//#region src/providers/cryptpad/assetProvider.ts
+const CRYPTPAD_ASSET_SYNC_CAPABILITIES = createCapabilitySet({
+	assetSync: true,
+	discoverByFolder: true
+});
+function toSha256(content) {
+	return crypto.createHash("sha256").update(content).digest("hex");
+}
+/**
+* Guards against path traversal: returns false if `relativePath` would resolve
+* to a location outside `targetDirectory` (e.g. via `../` segments).
+*/
+function isSafePath(targetDirectory, relativePath) {
+	const resolvedRoot = path.resolve(targetDirectory);
+	const resolvedTarget = path.resolve(targetDirectory, relativePath);
+	return resolvedTarget === resolvedRoot || resolvedTarget.startsWith(`${resolvedRoot}${path.sep}`);
+}
+async function walkFiles(directory) {
+	if (!fs.existsSync(directory)) return [];
+	const entries = await fs$1.readdir(directory, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries) {
+		const fullPath = path.join(directory, entry.name);
+		if (entry.isDirectory()) {
+			files.push(...await walkFiles(fullPath));
+			continue;
+		}
+		files.push(fullPath);
+	}
+	return files;
+}
+function createDefaultDeps$1() {
+	return {
+		async readManifest(manifestPath) {
+			const content = await fs$1.readFile(manifestPath, "utf8");
+			const parsed = JSON.parse(content);
+			if (!Array.isArray(parsed)) throw new Error("CryptPad asset manifest must be a JSON array.");
+			return parsed;
+		},
+		async readAssetBuffer(asset, signal) {
+			if (asset.sourcePath) return fs$1.readFile(asset.sourcePath);
+			if (asset.sourceUrl) {
+				const response = await fetch(asset.sourceUrl, { signal });
+				if (!response.ok) throw new Error(`Failed to fetch asset from ${asset.sourceUrl} (HTTP ${response.status})`);
+				return Buffer.from(await response.arrayBuffer());
+			}
+			throw new Error(`Asset "${asset.assetId}" must define sourcePath or sourceUrl.`);
+		},
+		async fileExists(filePath) {
+			try {
+				await fs$1.access(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		readFile: (filePath) => fs$1.readFile(filePath),
+		async writeFile(filePath, content) {
+			await fs$1.mkdir(path.dirname(filePath), { recursive: true });
+			await fs$1.writeFile(filePath, content);
+		},
+		listFiles: walkFiles,
+		deleteFile: (filePath) => fs$1.unlink(filePath)
+	};
+}
+/**
+* Creates an {@link AssetSyncProvider} that syncs binary/static assets described by a
+* JSON manifest (`manifestPath`) into a local target directory. For each manifest
+* entry it downloads a missing file, overwrites a file whose SHA-256 hash differs,
+* or skips a file that is already up to date; entries sharing the same declared
+* `hash` reuse one fetched buffer. When {@link AssetSyncRequest.deleteMissing} is
+* set, local files under the target directory that are not named by the manifest
+* are removed. All target paths are checked with {@link isSafePath} to reject
+* manifest entries that would write outside the target directory.
+*/
+function createCryptPadAssetSyncProvider(options, depsOverrides = {}) {
+	const deps = {
+		...createDefaultDeps$1(),
+		...depsOverrides
+	};
+	return {
+		kind: "asset-sync",
+		providerId: options.providerId ?? "cryptpad-assets",
+		displayName: options.displayName ?? "CryptPad Asset Sync",
+		capabilities: CRYPTPAD_ASSET_SYNC_CAPABILITIES,
+		async syncAssets(request) {
+			const manifest = await deps.readManifest(options.manifestPath);
+			const downloaded = [];
+			const updated = [];
+			const skipped = [];
+			const deleted = [];
+			const desiredTargets = /* @__PURE__ */ new Set();
+			const hashCache = /* @__PURE__ */ new Map();
+			for (const asset of manifest) {
+				if (!isSafePath(request.targetDirectory, asset.relativePath)) throw new Error(`Unsafe asset path blocked: ${asset.relativePath}`);
+				const targetPath = path.resolve(request.targetDirectory, asset.relativePath);
+				desiredTargets.add(targetPath);
+				let content;
+				if (asset.hash && hashCache.has(asset.hash)) content = hashCache.get(asset.hash);
+				else {
+					content = await deps.readAssetBuffer(asset, request.signal);
+					const hash = asset.hash ?? toSha256(content);
+					hashCache.set(hash, content);
+				}
+				if (await deps.fileExists(targetPath)) {
+					if (toSha256(await deps.readFile(targetPath)) === toSha256(content)) {
+						skipped.push(asset.relativePath);
+						continue;
+					}
+					await deps.writeFile(targetPath, content);
+					updated.push(asset.relativePath);
+					continue;
+				}
+				await deps.writeFile(targetPath, content);
+				downloaded.push(asset.relativePath);
+			}
+			if (request.deleteMissing) {
+				const existingFiles = await deps.listFiles(request.targetDirectory);
+				for (const existingFile of existingFiles) {
+					const resolved = path.resolve(existingFile);
+					if (!desiredTargets.has(resolved)) {
+						await deps.deleteFile(resolved);
+						deleted.push(path.relative(request.targetDirectory, resolved));
+					}
+				}
+			}
+			return {
+				manifestCount: manifest.length,
+				downloaded,
+				updated,
+				deleted,
+				skipped
+			};
+		}
+	};
+}
+//#endregion
+//#region src/core/rowTransformer.ts
+/**
+* Pure transformation core: converts canonical rows into TranslationData for one sheet.
+*/
+function transformRowsToSheetData(rows, sheetTitle, deps) {
+	const logger = deps.logger ?? console;
+	const result = {
+		translations: {},
+		locales: [],
+		localeMapping: {},
+		originalMapping: {},
+		success: false
+	};
+	try {
+		if (!rows || rows.length === 0) {
+			logger.warn(`No rows found in sheet "${sheetTitle}"`);
+			return result;
+		}
+		const headerRow = Object.keys(rows[0]).map((key) => key.toLowerCase());
+		logger.log(`Header row for sheet "${sheetTitle}":`, headerRow);
+		const keyColumn = headerRow[0];
+		if (deps.filterValidLocales(headerRow, keyColumn).length === 0) {
+			logger.warn(`No valid locale columns found in sheet "${sheetTitle}"`);
+			return result;
+		}
+		const originalHeaders = Object.keys(rows[0]);
+		const { normalizedLocales, localeMapping, originalMapping } = deps.createLocaleMapping(originalHeaders, keyColumn);
+		result.localeMapping = localeMapping;
+		result.originalMapping = originalMapping;
+		for (const normalizedLocale of normalizedLocales) {
+			const originalHeader = localeMapping[normalizedLocale];
+			if (!originalHeader) continue;
+			const nonEmptyLanguageCells = rows.map((row) => {
+				const keyField = Object.keys(row).find((k) => k.toLowerCase() === keyColumn);
+				if (!keyField || !row[keyField] || !row[originalHeader]) return {};
+				const rowLocal = {};
+				rowLocal[row[keyField].toString().toLowerCase()] = row[originalHeader];
+				return rowLocal;
+			}).filter((cell) => Object.keys(cell).length > 0);
+			const prepareObj = {};
+			prepareObj[sheetTitle] = nonEmptyLanguageCells.reduce((acc, cell) => Object.assign(acc, cell), {});
+			if (result.translations[normalizedLocale]) result.translations[normalizedLocale] = {
+				...result.translations[normalizedLocale],
+				...prepareObj
+			};
+			else result.translations[normalizedLocale] = { ...prepareObj };
+		}
+		result.locales = normalizedLocales;
+		result.success = true;
+	} catch (error) {
+		logger.error(`Error processing sheet "${sheetTitle}":`, error);
+	}
+	return result;
+}
+//#endregion
+//#region src/utils/localeFilter.ts
+/**
+* Locale validation utilities
+*/
+const COMMON_LOCALE_PATTERNS = [
+	/^[a-z]{2}$/,
+	/^[a-z]{2}-[a-z]{2}$/,
+	/^[a-z]{2}_[a-z]{2}$/,
+	/^[a-z]{2}-[a-z]{2}-[a-z]+$/
+];
+const NON_LOCALE_KEYWORDS = [
+	"key",
+	"keys",
+	"id",
+	"identifier",
+	"name",
+	"title",
+	"label",
+	"description",
+	"comment",
+	"note",
+	"context",
+	"category",
+	"type",
+	"status",
+	"updated",
+	"created",
+	"modified",
+	"version",
+	"source",
+	"i18n",
+	"translation",
+	"namespace",
+	"section"
+];
+/**
+* Determines if a string represents a valid locale identifier
+* @param value The string to test
+* @returns true if the string appears to be a locale identifier
+*/
+function isValidLocale(value) {
+	if (!value || typeof value !== "string") return false;
+	const normalized = value.toLowerCase().trim();
+	if (NON_LOCALE_KEYWORDS.includes(normalized)) return false;
+	return COMMON_LOCALE_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+/**
+* Filters header row to only include valid locale columns, excluding the key column
+* @param headerRow Array of column names from the sheet header
+* @param keyColumn The name of the key column to exclude
+* @returns Array of valid locale identifiers
+*/
+function filterValidLocales(headerRow, keyColumn) {
+	return headerRow.filter((column) => column.toLowerCase() !== keyColumn.toLowerCase()).filter((column) => isValidLocale(column)).map((locale) => locale.toLowerCase());
+}
+//#endregion
+//#region src/providers/orchestrator.ts
+function createDefaultDeps() {
+	return {
+		transformRows: (rows, sheetTitle) => transformRowsToSheetData(rows, sheetTitle, {
+			filterValidLocales,
+			createLocaleMapping,
+			logger: console
+		}),
+		logger: console
+	};
+}
+function mergeTranslations(target, next) {
+	for (const [locale, sheets] of Object.entries(next)) {
+		if (!target[locale]) target[locale] = {};
+		for (const [sheetName, keys] of Object.entries(sheets)) {
+			if (!target[locale][sheetName]) target[locale][sheetName] = {};
+			target[locale][sheetName] = {
+				...target[locale][sheetName],
+				...keys
+			};
+		}
+	}
+}
+/**
+* Runs the full provider-driven translation pipeline: read tables from the input
+* provider, transform rows into canonical {@link TranslationData}, optionally write
+* to an output provider, optionally sync local changes back, and optionally sync
+* assets via an asset-sync provider. Each optional stage is gated by a capability
+* check on the corresponding provider so unsupported operations fail fast instead
+* of silently doing partial work.
+*/
+async function runProviderPipeline(options, depsOverrides = {}) {
+	const deps = {
+		...createDefaultDeps(),
+		...depsOverrides
+	};
+	assertOperationCapabilities(options.inputProvider.providerId, options.inputProvider.capabilities, "read-input");
+	const inputResult = await options.inputProvider.readTables({
+		tableNames: options.tableNames,
+		signal: options.signal
+	});
+	const mergedTranslations = {};
+	const localeSet = /* @__PURE__ */ new Set();
+	const localeMapping = {};
+	const originalLocaleMapping = {};
+	for (const table of inputResult.tables) {
+		const processed = deps.transformRows(table.rows, table.tableName);
+		if (!processed.success) {
+			deps.logger.warn(`Skipping table "${table.tableName}" because transformation returned unsuccessful result.`);
+			continue;
+		}
+		mergeTranslations(mergedTranslations, processed.translations);
+		for (const locale of processed.locales) localeSet.add(locale);
+		for (const [normalized, original] of Object.entries(processed.localeMapping)) if (!localeMapping[normalized]) localeMapping[normalized] = original;
+		for (const [original, normalized] of Object.entries(processed.originalMapping)) if (!originalLocaleMapping[original]) originalLocaleMapping[original] = normalized;
+	}
+	let outputResult;
+	if (options.outputProvider) {
+		assertOperationCapabilities(options.outputProvider.providerId, options.outputProvider.capabilities, "write-output");
+		outputResult = await options.outputProvider.writeTranslations({
+			translations: mergedTranslations,
+			locales: Array.from(localeSet),
+			localeMapping,
+			originalLocaleMapping,
+			metadata: inputResult.metadata
+		});
+	}
+	let syncResult;
+	if (options.syncProvider && options.localTranslationsForSync) {
+		assertOperationCapabilities(options.syncProvider.providerId, options.syncProvider.capabilities, "sync-back");
+		syncResult = await options.syncProvider.syncTranslations({
+			localTranslations: options.localTranslationsForSync,
+			remoteTranslations: mergedTranslations,
+			metadata: inputResult.metadata
+		});
+	}
+	let assetSyncResult;
+	if (options.assetSyncProvider && options.assetSync) {
+		assertOperationCapabilities(options.assetSyncProvider.providerId, options.assetSyncProvider.capabilities, "sync-assets");
+		assetSyncResult = await options.assetSyncProvider.syncAssets({
+			targetDirectory: options.assetSync.targetDirectory,
+			deleteMissing: options.assetSync.deleteMissing,
+			signal: options.signal
+		});
+	}
+	return {
+		translations: mergedTranslations,
+		locales: Array.from(localeSet),
+		localeMapping,
+		originalLocaleMapping,
+		inputTableCount: inputResult.tables.length,
+		outputResult,
+		syncResult,
+		assetSyncResult,
+		metadata: inputResult.metadata
+	};
+}
+//#endregion
+//#region src/providers/config.ts
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* Validates the shape of an untrusted runtime config value (typically parsed from JSON)
+* before it is trusted as a {@link ProviderRuntimeConfig}. Collects every error found
+* rather than failing on the first one, so a config file can be fixed in one pass.
+*/
+function validateProviderRuntimeConfig(config) {
+	const errors = [];
+	if (!isObject(config)) return {
+		valid: false,
+		errors: ["Provider config must be an object."]
+	};
+	const input = config.input;
+	if (!isObject(input)) errors.push("Provider config must include an \"input\" provider object.");
+	else if (typeof input.provider !== "string" || input.provider.trim().length === 0) errors.push("Input provider must define a non-empty \"provider\" string.");
+	const output = config.output;
+	if (output !== void 0) {
+		if (!isObject(output)) errors.push("Output provider must be an object when provided.");
+		else if (typeof output.provider !== "string" || output.provider.trim().length === 0) errors.push("Output provider must define a non-empty \"provider\" string.");
+	}
+	const sync = config.sync;
+	if (sync !== void 0) {
+		if (!isObject(sync)) errors.push("Sync provider must be an object when provided.");
+		else if (typeof sync.provider !== "string" || sync.provider.trim().length === 0) errors.push("Sync provider must define a non-empty \"provider\" string.");
+	}
+	const assetSync = config.assetSync;
+	if (assetSync !== void 0) {
+		if (!isObject(assetSync)) errors.push("Asset sync provider must be an object when provided.");
+		else if (typeof assetSync.provider !== "string" || assetSync.provider.trim().length === 0) errors.push("Asset sync provider must define a non-empty \"provider\" string.");
+	}
+	if (isObject(input) && typeof input.provider === "string" && input.provider === "cryptpad-csv" && isObject(sync) && typeof sync.provider === "string" && sync.provider !== "cryptpad-workspace") errors.push("Invalid provider combination: \"cryptpad-csv\" only supports sync mode via \"cryptpad-workspace\" (or use another sync-capable provider).");
+	return {
+		valid: errors.length === 0,
+		errors
+	};
+}
+/**
+* Validates `config` and returns it typed as {@link ProviderRuntimeConfig}, or throws
+* with all collected validation errors joined into a single message. Use this at
+* process boundaries (CLI, Action inputs) where a throw-on-invalid contract is wanted.
+*/
+function assertValidProviderRuntimeConfig(config) {
+	const validation = validateProviderRuntimeConfig(config);
+	if (!validation.valid) throw new Error(`Invalid provider configuration: ${validation.errors.join(" | ")}`);
+	return config;
+}
+//#endregion
+//#region src/providers/runtime.ts
+function asRecord(value) {
+	if (!value || typeof value !== "object") return {};
+	return value;
+}
+function createInputProvider(providerId, options) {
+	switch (providerId) {
+		case "google-sheets": return createGoogleSheetsInputProvider(options);
+		case "cryptpad-csv": {
+			const sources = options.sources;
+			if (!Array.isArray(sources)) throw new Error("cryptpad-csv input provider requires an array \"sources\" option.");
+			return createCryptPadCsvInputProvider({
+				sources,
+				delimiter: typeof options.delimiter === "string" ? options.delimiter : void 0,
+				providerId: typeof options.providerId === "string" ? options.providerId : void 0,
+				displayName: typeof options.displayName === "string" ? options.displayName : void 0
+			});
+		}
+		default: throw new Error(`Unsupported input provider: "${providerId}"`);
+	}
+}
+function createOutputProvider(providerId, options) {
+	switch (providerId) {
+		case "google-sheets": return createGoogleSheetsOutputProvider(options);
+		case "cryptpad-workspace":
+			if (typeof options.filePath !== "string" || options.filePath.trim().length === 0) throw new Error("cryptpad-workspace output provider requires a non-empty \"filePath\" option.");
+			return createCryptPadWorkspaceOutputProvider({
+				filePath: options.filePath,
+				authToken: typeof options.authToken === "string" ? options.authToken : void 0,
+				expectedRevision: typeof options.expectedRevision === "number" ? options.expectedRevision : void 0,
+				providerId: typeof options.providerId === "string" ? options.providerId : void 0,
+				displayName: typeof options.displayName === "string" ? options.displayName : void 0
+			});
+		default: throw new Error(`Unsupported output provider: "${providerId}"`);
+	}
+}
+function createSyncProvider(providerId, options) {
+	switch (providerId) {
+		case "google-sheets": return createGoogleSheetsSyncProvider(options);
+		case "cryptpad-workspace":
+			if (typeof options.filePath !== "string" || options.filePath.trim().length === 0) throw new Error("cryptpad-workspace sync provider requires a non-empty \"filePath\" option.");
+			return createCryptPadWorkspaceSyncProvider({
+				filePath: options.filePath,
+				authToken: typeof options.authToken === "string" ? options.authToken : void 0,
+				expectedRevision: typeof options.expectedRevision === "number" ? options.expectedRevision : void 0,
+				conflictPolicy: options.conflictPolicy === "remote-wins" || options.conflictPolicy === "local-wins" || options.conflictPolicy === "manual" ? options.conflictPolicy : void 0,
+				providerId: typeof options.providerId === "string" ? options.providerId : void 0,
+				displayName: typeof options.displayName === "string" ? options.displayName : void 0
+			});
+		default: throw new Error(`Unsupported sync provider: "${providerId}"`);
+	}
+}
+function createAssetSyncProvider(providerId, options) {
+	switch (providerId) {
+		case "cryptpad-assets":
+			if (typeof options.manifestPath !== "string" || options.manifestPath.trim().length === 0) throw new Error("cryptpad-assets sync provider requires a non-empty \"manifestPath\" option.");
+			return createCryptPadAssetSyncProvider({
+				manifestPath: options.manifestPath,
+				providerId: typeof options.providerId === "string" ? options.providerId : void 0,
+				displayName: typeof options.displayName === "string" ? options.displayName : void 0
+			});
+		default: throw new Error(`Unsupported asset sync provider: "${providerId}"`);
+	}
+}
+/**
+* Builds a {@link ProviderRuntimeSelection} by resolving each configured provider slot
+* (`input`, `output`, `sync`, `assetSync`) to a concrete provider instance via its factory.
+* Throws if a slot names a provider ID with no matching factory, or if a provider's
+* required options are missing.
+*/
+function createProvidersFromRuntimeConfig(config) {
+	return {
+		inputProvider: createInputProvider(config.input.provider, asRecord(config.input.options)),
+		outputProvider: config.output ? createOutputProvider(config.output.provider, asRecord(config.output.options)) : void 0,
+		syncProvider: config.sync ? createSyncProvider(config.sync.provider, asRecord(config.sync.options)) : void 0,
+		assetSyncProvider: config.assetSync ? createAssetSyncProvider(config.assetSync.provider, asRecord(config.assetSync.options)) : void 0
+	};
+}
+//#endregion
+//#region src/utils/dataConverter/convertToDataJsonFormat.ts
+/**
+* Converts the translation object to the expected languageData.json format
+* @param translationObj - The translation object with locale->sheet->key->value structure
+* @param locales - Array of locale identifiers
+* @returns Converted data in the format expected for languageData.json
+*/
+function convertToDataJsonFormat(translationObj, locales) {
+	const result = [];
+	console.log("Converting translation object to languageData.json format...");
+	const allSheets = /* @__PURE__ */ new Set();
+	for (const locale of Object.keys(translationObj)) if (translationObj[locale]) for (const sheet of Object.keys(translationObj[locale])) allSheets.add(sheet);
+	console.log(`Found ${allSheets.size} sheets across all locales`);
+	for (const sheetTitle of allSheets) {
+		const projectData = {};
+		projectData[sheetTitle] = {};
+		for (const locale of locales) if (translationObj?.[locale]?.[sheetTitle]) {
+			const translations = translationObj[locale][sheetTitle];
+			projectData[sheetTitle][locale] = { ...translations };
+			console.log(`Found ${Object.keys(translations).length} keys for locale ${locale} in sheet ${sheetTitle}`);
+		}
+		if (Object.keys(projectData[sheetTitle]).length > 0) result.push(projectData);
+	}
+	console.log(`Created ${result.length} sheet entries for languageData.json`);
+	return result;
+}
+//#endregion
+//#region src/utils/fileWriter.ts
+/**
+* Writes locale files to the translations directory
+* @param translations Translation data organized by locale
+* @param locales Array of locale identifiers
+* @param translationsOutputDir Directory to write translation files to
+*/
+function writeTranslationFiles(translations, locales, translationsOutputDir) {
+	if (!fs.existsSync(translationsOutputDir)) try {
+		fs.mkdirSync(translationsOutputDir, { recursive: true });
+	} catch (err) {
+		throw new Error(`Failed to create translations directory "${translationsOutputDir}"`, { cause: err });
+	}
+	for (const locale of locales) {
+		if (!translations[locale] || Object.keys(translations[locale]).length === 0) {
+			console.warn(`No translations found for locale "${locale}"`);
+			continue;
+		}
+		const safeName = locale.toLowerCase().replace(/[^a-z0-9_-]/g, "_");
+		if (safeName !== locale.toLowerCase()) console.warn(`Locale "${locale}" contained unsafe characters; sanitised to "${safeName}"`);
+		try {
+			fs.writeFileSync(path.join(translationsOutputDir, `${safeName}.json`), JSON.stringify(translations[locale], null, 2), "utf8");
+			console.log(`Successfully wrote translations for ${locale}`);
+		} catch (err) {
+			console.error(`Failed to write translation file for locale "${locale}" at "${path.join(translationsOutputDir, `${safeName}.json`)}":`, err);
+		}
+	}
+}
+/**
+* Writes the locales.ts file containing the array of available locales and header mapping
+* @param locales Array of normalized locale identifiers (filtered to only include valid locales)
+* @param localeMapping Mapping from normalized locales to original spreadsheet headers
+* @param localesOutputPath Path to write the locales.ts file
+*/
+function writeLocalesFile(locales, localeMapping, localesOutputPath) {
+	const localesOutputDir = path.dirname(localesOutputPath);
+	if (!fs.existsSync(localesOutputDir)) try {
+		fs.mkdirSync(localesOutputDir, { recursive: true });
+	} catch (err) {
+		throw new Error(`Failed to create directory "${localesOutputDir}"`, { cause: err });
+	}
+	const validLocales = locales.filter((locale) => locale && locale.trim().length > 0);
+	const content = `/**
+ * This file is auto-generated from the Google Spreadsheet package.
+ * It contains the list of available locales and their mappings to original spreadsheet headers.
+ * Do not edit this file manually, it will be overwritten by the package.
+ */
+
+ export const locales = ${JSON.stringify(validLocales)};
+
+/**
+ * Mapping from normalized locale codes to original spreadsheet headers
+ * Used for syncing changes back to the spreadsheet
+ */
+export const localeHeaderMapping = ${JSON.stringify(localeMapping, null, 2)};
+
+export default locales;
+`;
+	try {
+		fs.writeFileSync(localesOutputPath, content, "utf8");
+	} catch (err) {
+		throw new Error(`Failed to write locales file at "${localesOutputPath}"`, { cause: err });
+	}
+	console.log(`Successfully wrote locales file with ${validLocales.length} locales:`, validLocales);
+	console.log("Header mapping includes:", Object.keys(localeMapping).length, "mappings");
+}
+/**
+* Writes the languageData.json file containing all translation data
+* @param translations Translation data organized by locale
+* @param locales Array of locale identifiers
+* @param dataJsonPath Path to write the languageData.json file
+*/
+function writeLanguageDataFile(translations, locales, dataJsonPath) {
+	const dataJsonDir = path.dirname(dataJsonPath);
+	if (!fs.existsSync(dataJsonDir)) try {
+		fs.mkdirSync(dataJsonDir, { recursive: true });
+	} catch (err) {
+		throw new Error(`Failed to create directory "${dataJsonDir}"`, { cause: err });
+	}
+	const dataJsonContent = convertToDataJsonFormat(translations, locales);
+	try {
+		fs.writeFileSync(dataJsonPath, JSON.stringify(dataJsonContent, null, 2), "utf8");
+	} catch (err) {
+		throw new Error(`Failed to write language data file at "${dataJsonPath}"`, { cause: err });
+	}
+	console.log("Successfully updated languageData.json with fresh spreadsheet data");
+}
+//#endregion
+//#region src/utils/dataConverter/convertFromDataJsonFormat.ts
+/**
+* Type-guard: checks that a value has the shape of sheet data
+* (an object mapping locale → translation record)
+*/
+function isSheetData(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+* Converts languageData.json format back to the translation object structure
+* @param dataJson - Data in the languageData.json format
+* @returns Converted data in the TranslationData format
+*/
+function convertFromDataJsonFormat(dataJson) {
+	const result = {};
+	for (const projectData of dataJson) for (const sheetTitle of Object.keys(projectData)) {
+		const raw = projectData[sheetTitle];
+		if (!isSheetData(raw)) {
+			console.warn(`Skipping malformed entry for sheet "${sheetTitle}"`);
+			continue;
+		}
+		for (const locale of Object.keys(raw)) {
+			if (!result[locale]) result[locale] = {};
+			if (!result[locale][sheetTitle]) result[locale][sheetTitle] = {};
+			const localeData = raw[locale];
+			if (typeof localeData !== "object" || localeData === null) continue;
+			for (const key of Object.keys(localeData)) result[locale][sheetTitle][key] = localeData[key];
+		}
+	}
+	return result;
+}
+//#endregion
+//#region src/utils/readDataJson.ts
+/**
+* Reads and parses the languageData.json file
+* @param dataJsonPath - Path to languageData.json
+* @returns Parsed languageData.json contents, or null if file doesn't exist or is invalid
+*/
+function readDataJson(dataJsonPath) {
+	try {
+		if (!fs.existsSync(dataJsonPath)) return null;
+		const dataJsonContent = fs.readFileSync(dataJsonPath, "utf8");
+		return convertFromDataJsonFormat(JSON.parse(dataJsonContent));
+	} catch (error) {
+		console.warn("Error reading or parsing languageData.json:", error);
+		return null;
+	}
+}
+//#endregion
+//#region src/setup/providerCli.ts
+/**
+* `gst-run-provider` CLI entrypoint. Reads a JSON {@link ProviderRuntimeConfig} from
+* `--config`, resolves it to concrete providers, runs the full pipeline (input →
+* transform → output → sync → optional asset sync), and writes the resulting
+* translation files to disk.
+*/
+function parseArgs(argv) {
+	const result = {};
+	for (const arg of argv.slice(2)) {
+		const match = arg.match(/^--([^=]+)(?:=(.*))?$/);
+		if (match) result[match[1]] = match[2] ?? "true";
+	}
+	return result;
+}
+function printHelp() {
+	console.log(`
+ gst-run-provider - Run translation sync with v3 provider runtime config
+
+ USAGE
+   npx -p @el-j/google-sheet-translations gst-run-provider --config=provider.config.json [options]
+
+ OPTIONS
+   --config=PATH                 Path to provider runtime config JSON (required)
+   --sheet-titles=CSV            Comma-separated table names (default: i18n)
+   --translations-output-dir=DIR Output dir for locale json files (default: translations)
+   --locales-output-path=PATH    Output path for locales.ts (default: src/i18n/locales.ts)
+   --data-json-path=PATH         Output path for languageData.json (default: src/lib/languageData.json)
+   --asset-target-dir=DIR        Run asset sync (requires "assetSync" in config) and write assets here
+   --asset-delete-missing        Delete local assets not present in the asset manifest
+   --help                        Show this help
+
+ EXAMPLE
+   gst-run-provider \
+     --config=provider.config.json \
+     --sheet-titles=home,about,pricing \
+     --asset-target-dir=public/assets
+`);
+}
+async function main() {
+	const args = parseArgs(process.argv);
+	if (args.help || args.h) {
+		printHelp();
+		return;
+	}
+	const configPath = args.config;
+	if (!configPath) {
+		console.error("Missing required argument: --config=provider.config.json");
+		process.exit(1);
+	}
+	const cwd = process.cwd();
+	const absConfigPath = path.resolve(cwd, configPath);
+	const rawConfig = fs.readFileSync(absConfigPath, "utf8");
+	const config = assertValidProviderRuntimeConfig(JSON.parse(rawConfig));
+	const sheetTitles = (args["sheet-titles"] ?? "i18n").split(",").map((s) => s.trim()).filter(Boolean);
+	const translationsOutputDir = path.resolve(cwd, args["translations-output-dir"] ?? "translations");
+	const localesOutputPath = path.resolve(cwd, args["locales-output-path"] ?? "src/i18n/locales.ts");
+	const dataJsonPath = path.resolve(cwd, args["data-json-path"] ?? "src/lib/languageData.json");
+	const assetTargetDirArg = args["asset-target-dir"];
+	const configAssetTargetDir = typeof config.assetSync?.options?.targetDirectory === "string" && config.assetSync.options.targetDirectory.trim().length > 0 ? config.assetSync.options.targetDirectory.trim() : void 0;
+	const effectiveAssetTargetDir = assetTargetDirArg || configAssetTargetDir;
+	const effectiveAssetDeleteMissing = assetTargetDirArg ? args["asset-delete-missing"] === "true" : Boolean(config.assetSync?.options?.deleteMissing);
+	const assetSync = effectiveAssetTargetDir ? {
+		targetDirectory: path.resolve(cwd, effectiveAssetTargetDir),
+		deleteMissing: effectiveAssetDeleteMissing
+	} : void 0;
+	const providers = createProvidersFromRuntimeConfig(config);
+	const localDataForSync = readDataJson(dataJsonPath) ?? void 0;
+	const result = await runProviderPipeline({
+		inputProvider: providers.inputProvider,
+		outputProvider: providers.outputProvider,
+		syncProvider: providers.syncProvider,
+		assetSyncProvider: providers.assetSyncProvider,
+		assetSync,
+		tableNames: sheetTitles,
+		localTranslationsForSync: localDataForSync
+	});
+	writeTranslationFiles(result.translations, result.locales, translationsOutputDir);
+	writeLocalesFile(result.locales, result.localeMapping, localesOutputPath);
+	if (result.locales.length > 0) writeLanguageDataFile(result.translations, result.locales, dataJsonPath);
+	console.log(`Provider pipeline completed with ${result.locales.length} locale(s).`);
+	if (result.assetSyncResult) {
+		const { manifestCount, downloaded, updated, deleted, skipped } = result.assetSyncResult;
+		console.log(`Asset sync completed: ${manifestCount} manifest entr${manifestCount === 1 ? "y" : "ies"}, ${downloaded.length} downloaded, ${updated.length} updated, ${deleted.length} deleted, ${skipped.length} skipped.`);
+	}
+}
+main().catch((err) => {
+	const message = err instanceof Error ? err.message : String(err);
+	console.error(message);
+	process.exit(1);
+});
+//#endregion
+export {};