@rowsncolumns/utils 9.2.43 → 9.3.0

package/dist/cjs/formula-locale.js

@@ -0,0 +1,804 @@
+"use strict";
+var e_1, _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localizeFunctionDescriptions = exports.localizeFunctionDescription = exports.localizeFunctionSyntax = exports.canonicalizeCellInput = exports.localizeCellInput = exports.canonicalizeFormula = exports.localizeFormula = exports.translateFormula = exports.canonicalizeErrorValue = exports.localizeErrorValue = exports.canonicalizeFunctionName = exports.localizeFunctionName = exports.getFormulaLocaleTags = exports.unregisterFormulaLocale = exports.registerFormulaLocale = exports.getFormulaLocale = exports.CANONICAL_FORMULA_LOCALE = exports.CANONICAL_ERROR_VALUES = exports.FORMULA_LOCALE_DATA_SOURCES = exports.FORMULA_LOCALE_DATA = void 0;
+var tslib_1 = require("tslib");
+var formula_1 = require("./formula");
+var formula_locale_data_generated_1 = require("./formula-locale/formula-locale-data.generated");
+var formula_locale_data_generated_2 = require("./formula-locale/formula-locale-data.generated");
+Object.defineProperty(exports, "FORMULA_LOCALE_DATA", { enumerable: true, get: function () { return formula_locale_data_generated_2.FORMULA_LOCALE_DATA; } });
+Object.defineProperty(exports, "FORMULA_LOCALE_DATA_SOURCES", { enumerable: true, get: function () { return formula_locale_data_generated_2.FORMULA_LOCALE_DATA_SOURCES; } });
+var CANONICAL_TAG = "en";
+/** Excel error values, in their canonical (English) spelling. */
+exports.CANONICAL_ERROR_VALUES = [
+    "#NULL!",
+    "#DIV/0!",
+    "#VALUE!",
+    "#REF!",
+    "#NAME?",
+    "#NUM!",
+    "#N/A",
+    "#GETTING_DATA",
+    "#SPILL!",
+    "#CALC!",
+    "#FIELD!",
+    "#CONNECT!",
+    "#BLOCKED!",
+    "#UNKNOWN!",
+];
+/**
+ * Case fold for dictionary keys. `toUpperCase` alone leaves Turkish `İ` (dotted capital I) distinct
+ * from the `I` a lowercase `i` uppercases to, so `filtre(` would never find `FİLTRE`; folding both to
+ * `I` makes typed lowercase names resolve in every locale.
+ */
+var fold = function (text) { return text.toUpperCase().replace(/İ/g, "I"); };
+var normalizeTag = function (tag) { return tag.trim().replace(/_/g, "-").toLowerCase(); };
+/** Built-in table keyed by normalized tag. */
+var builtIn = new Map();
+try {
+    for (var _b = tslib_1.__values(Object.entries(formula_locale_data_generated_1.FORMULA_LOCALE_DATA)), _c = _b.next(); !_c.done; _c = _b.next()) {
+        var _d = tslib_1.__read(_c.value, 2), tag = _d[0], entry = _d[1];
+        builtIn.set(normalizeTag(tag), entry);
+    }
+}
+catch (e_1_1) { e_1 = { error: e_1_1 }; }
+finally {
+    try {
+        if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+    }
+    finally { if (e_1) throw e_1.error; }
+}
+var registered = new Map();
+var resolvedByTag = new Map();
+var resolvedByDefinition = new WeakMap();
+var isFormulaLocale = function (value) {
+    return typeof value === "object" &&
+        value !== null &&
+        value.functions instanceof Map &&
+        value.canonicalFunctions instanceof Map;
+};
+var buildLocale = function (id, name, syntax, dictionaries) {
+    var e_2, _a, e_3, _b;
+    var functions = new Map();
+    var canonicalFunctions = new Map();
+    try {
+        for (var _c = tslib_1.__values(dictionaries.functions), _d = _c.next(); !_d.done; _d = _c.next()) {
+            var _e = tslib_1.__read(_d.value, 2), canonical = _e[0], localized = _e[1];
+            var key = fold(canonical);
+            // An identity entry records "English name in this language" and needs no map entry. A name that
+            // differs only in its dotted İ (tr `ASİN`) IS kept as the display form; its reverse entry is a
+            // harmless self-map.
+            if (localized === canonical)
+                continue;
+            functions.set(key, localized);
+            canonicalFunctions.set(fold(localized), key);
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    var errors = new Map();
+    var canonicalErrors = new Map();
+    try {
+        for (var _f = tslib_1.__values(dictionaries.errors), _g = _f.next(); !_g.done; _g = _f.next()) {
+            var _h = tslib_1.__read(_g.value, 2), canonical = _h[0], localized = _h[1];
+            var key = fold(canonical);
+            if (fold(localized) === key)
+                continue;
+            errors.set(key, localized);
+            canonicalErrors.set(fold(localized), key);
+        }
+    }
+    catch (e_3_1) { e_3 = { error: e_3_1 }; }
+    finally {
+        try {
+            if (_g && !_g.done && (_b = _f.return)) _b.call(_f);
+        }
+        finally { if (e_3) throw e_3.error; }
+    }
+    var isCanonical = syntax.decimalSeparator === "." &&
+        syntax.argumentSeparator === "," &&
+        syntax.arrayColumnSeparator === "," &&
+        syntax.arrayRowSeparator === ";" &&
+        functions.size === 0 &&
+        errors.size === 0;
+    return Object.freeze({
+        id: id,
+        name: name,
+        decimalSeparator: syntax.decimalSeparator,
+        argumentSeparator: syntax.argumentSeparator,
+        arrayColumnSeparator: syntax.arrayColumnSeparator,
+        arrayRowSeparator: syntax.arrayRowSeparator,
+        unionOperator: syntax.argumentSeparator,
+        functions: functions,
+        canonicalFunctions: canonicalFunctions,
+        errors: errors,
+        canonicalErrors: canonicalErrors,
+        isCanonical: isCanonical,
+    });
+};
+/** The canonical dialect every formula is stored and evaluated in. */
+exports.CANONICAL_FORMULA_LOCALE = buildLocale(CANONICAL_TAG, builtIn.get(CANONICAL_TAG).name, tslib_1.__assign({}, builtIn.get(CANONICAL_TAG).syntax), { functions: new Map(), errors: new Map() });
+var applyDictionaryPatch = function (target, patch) {
+    var e_4, _a;
+    if (!patch)
+        return;
+    try {
+        for (var _b = tslib_1.__values(Object.entries(patch)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var _d = tslib_1.__read(_c.value, 2), canonical = _d[0], localized = _d[1];
+            if (localized === null || localized === undefined) {
+                target.delete(canonical);
+            }
+            else {
+                target.set(canonical, localized);
+            }
+        }
+    }
+    catch (e_4_1) { e_4 = { error: e_4_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_4) throw e_4.error; }
+    }
+};
+/** Resolve a normalized tag to its syntax + dictionaries, following `extends` chains. `depth` guards
+ * against a registration cycle (`a` extends `b` extends `a`). */
+var resolveTag = function (tag, depth) {
+    var e_5, _a, e_6, _b;
+    var _c, _d, _e, _f, _g, _h, _j;
+    if (depth === void 0) { depth = 0; }
+    if (depth > 8) {
+        throw new Error("Formula locale \"".concat(tag, "\" has a circular \"extends\" chain"));
+    }
+    var definition = registered.get(tag);
+    if (definition) {
+        var base_1 = resolveTag(definition.extends ? normalizeTag(definition.extends) : builtIn.has(tag) ? "".concat(tag, "\0builtin") : CANONICAL_TAG, depth + 1);
+        applyDictionaryPatch(base_1.dictionaries.functions, definition.functions);
+        applyDictionaryPatch(base_1.dictionaries.errors, definition.errors);
+        return {
+            name: (_c = definition.name) !== null && _c !== void 0 ? _c : base_1.name,
+            syntax: {
+                decimalSeparator: (_d = definition.decimalSeparator) !== null && _d !== void 0 ? _d : base_1.syntax.decimalSeparator,
+                argumentSeparator: (_e = definition.argumentSeparator) !== null && _e !== void 0 ? _e : base_1.syntax.argumentSeparator,
+                arrayColumnSeparator: (_f = definition.arrayColumnSeparator) !== null && _f !== void 0 ? _f : base_1.syntax.arrayColumnSeparator,
+                arrayRowSeparator: (_g = definition.arrayRowSeparator) !== null && _g !== void 0 ? _g : base_1.syntax.arrayRowSeparator,
+            },
+            dictionaries: base_1.dictionaries,
+        };
+    }
+    // A registration that overrides a built-in tag layers on that built-in's own data.
+    var builtInTag = tag.endsWith("builtin") ? tag.slice(0, -"builtin".length) : tag;
+    var entry = builtIn.get(builtInTag);
+    if (!entry) {
+        // Unknown tag: canonical syntax, no translations (callers resolve language fallbacks before this).
+        var en = builtIn.get(CANONICAL_TAG);
+        return {
+            name: en.name,
+            syntax: tslib_1.__assign({}, en.syntax),
+            dictionaries: { functions: new Map(), errors: new Map() },
+        };
+    }
+    var base = entry.extends
+        ? resolveTag(normalizeTag(entry.extends), depth + 1)
+        : { dictionaries: { functions: new Map(), errors: new Map() } };
+    var dictionaries = base.dictionaries;
+    try {
+        for (var _k = tslib_1.__values(Object.entries((_h = entry.functions) !== null && _h !== void 0 ? _h : {})), _l = _k.next(); !_l.done; _l = _k.next()) {
+            var _m = tslib_1.__read(_l.value, 2), canonical = _m[0], localized = _m[1];
+            dictionaries.functions.set(canonical, localized);
+        }
+    }
+    catch (e_5_1) { e_5 = { error: e_5_1 }; }
+    finally {
+        try {
+            if (_l && !_l.done && (_a = _k.return)) _a.call(_k);
+        }
+        finally { if (e_5) throw e_5.error; }
+    }
+    try {
+        for (var _o = tslib_1.__values(Object.entries((_j = entry.errors) !== null && _j !== void 0 ? _j : {})), _p = _o.next(); !_p.done; _p = _o.next()) {
+            var _q = tslib_1.__read(_p.value, 2), canonical = _q[0], localized = _q[1];
+            dictionaries.errors.set(canonical, localized);
+        }
+    }
+    catch (e_6_1) { e_6 = { error: e_6_1 }; }
+    finally {
+        try {
+            if (_p && !_p.done && (_b = _o.return)) _b.call(_o);
+        }
+        finally { if (e_6) throw e_6.error; }
+    }
+    return { name: entry.name, syntax: tslib_1.__assign({}, entry.syntax), dictionaries: dictionaries };
+};
+/** The tag (registered or built-in) that serves `tag`: exact match, then its language, then `en`. */
+var findServingTag = function (tag) {
+    var normalized = normalizeTag(tag);
+    if (!normalized)
+        return CANONICAL_TAG;
+    if (registered.has(normalized) || builtIn.has(normalized))
+        return normalized;
+    var language = normalized.split("-")[0];
+    if (registered.has(language) || builtIn.has(language))
+        return language;
+    return CANONICAL_TAG;
+};
+/**
+ * Resolve a locale for formula syntax. Accepts a BCP-47 tag (`"ru-RU"` → the `ru` table, `"de-AT"` →
+ * `de`, `"de-CH"` → the Swiss row; unknown languages → canonical English), an already-resolved
+ * {@link FormulaLocale} (returned as-is), or an inline {@link FormulaLocaleDefinition} (resolved once
+ * per object). Resolution is memoized.
+ */
+var getFormulaLocale = function (locale) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    if (locale === undefined || locale === null) {
+        return (0, exports.getFormulaLocale)(CANONICAL_TAG);
+    }
+    if (isFormulaLocale(locale)) {
+        return locale;
+    }
+    if (typeof locale === "object") {
+        var cached_1 = resolvedByDefinition.get(locale);
+        if (cached_1)
+            return cached_1;
+        var baseTag = locale.extends ? findServingTag(locale.extends) : CANONICAL_TAG;
+        var base = resolveTag(baseTag);
+        applyDictionaryPatch(base.dictionaries.functions, locale.functions);
+        applyDictionaryPatch(base.dictionaries.errors, locale.errors);
+        var built_1 = buildLocale((_a = locale.id) !== null && _a !== void 0 ? _a : baseTag, (_b = locale.name) !== null && _b !== void 0 ? _b : base.name, {
+            decimalSeparator: (_c = locale.decimalSeparator) !== null && _c !== void 0 ? _c : base.syntax.decimalSeparator,
+            argumentSeparator: (_d = locale.argumentSeparator) !== null && _d !== void 0 ? _d : base.syntax.argumentSeparator,
+            arrayColumnSeparator: (_e = locale.arrayColumnSeparator) !== null && _e !== void 0 ? _e : base.syntax.arrayColumnSeparator,
+            arrayRowSeparator: (_f = locale.arrayRowSeparator) !== null && _f !== void 0 ? _f : base.syntax.arrayRowSeparator,
+        }, base.dictionaries);
+        resolvedByDefinition.set(locale, built_1);
+        return built_1;
+    }
+    var servingTag = findServingTag(locale);
+    if (servingTag === CANONICAL_TAG && !registered.has(CANONICAL_TAG)) {
+        return exports.CANONICAL_FORMULA_LOCALE;
+    }
+    var cached = resolvedByTag.get(servingTag);
+    if (cached)
+        return cached;
+    var resolved = resolveTag(servingTag);
+    var built = buildLocale((_h = (_g = registered.get(servingTag)) === null || _g === void 0 ? void 0 : _g.id) !== null && _h !== void 0 ? _h : servingTag, resolved.name, resolved.syntax, resolved.dictionaries);
+    resolvedByTag.set(servingTag, built);
+    return built;
+};
+exports.getFormulaLocale = getFormulaLocale;
+/**
+ * Add a formula locale or override a built-in one for the whole application: `registerFormulaLocale
+ * ("de", { functions: { SUM: "SUMMEX" } })` layers onto the German table, `registerFormulaLocale("xx",
+ * { extends: "fr", argumentSeparator: "," })` derives a new language. Later registrations for the
+ * same tag replace earlier ones. Resolved locales are re-derived lazily.
+ */
+var registerFormulaLocale = function (tag, definition) {
+    var normalized = normalizeTag(tag);
+    if (!normalized) {
+        throw new Error("registerFormulaLocale: a non-empty tag is required");
+    }
+    registered.set(normalized, definition);
+    resolvedByTag.clear();
+};
+exports.registerFormulaLocale = registerFormulaLocale;
+/** Remove an application registration (built-in tables are never removed). */
+var unregisterFormulaLocale = function (tag) {
+    registered.delete(normalizeTag(tag));
+    resolvedByTag.clear();
+};
+exports.unregisterFormulaLocale = unregisterFormulaLocale;
+/** Every tag with a formula-syntax table: the built-in languages plus application registrations. */
+var getFormulaLocaleTags = function () {
+    return tslib_1.__spreadArray([], tslib_1.__read(new Set(tslib_1.__spreadArray(tslib_1.__spreadArray([], tslib_1.__read(Object.keys(formula_locale_data_generated_1.FORMULA_LOCALE_DATA)), false), tslib_1.__read(registered.keys()), false))), false).sort();
+};
+exports.getFormulaLocaleTags = getFormulaLocaleTags;
+// ── Names and error values ───────────────────────────────────────────────────────────────────────
+/** Localized spelling of a canonical function name (`SUM` → `СУММ`); names without a translation
+ * are returned unchanged. */
+var localizeFunctionName = function (name, locale) {
+    var _a;
+    var l = (0, exports.getFormulaLocale)(locale);
+    if (l.isCanonical)
+        return name;
+    return (_a = l.functions.get(fold(name))) !== null && _a !== void 0 ? _a : name;
+};
+exports.localizeFunctionName = localizeFunctionName;
+/** Canonical (English, uppercase) spelling of a localized function name (`СУММ` → `SUM`); names
+ * without a translation are returned unchanged, so English names are accepted in every locale. */
+var canonicalizeFunctionName = function (name, locale) {
+    var _a;
+    var l = (0, exports.getFormulaLocale)(locale);
+    if (l.isCanonical)
+        return name;
+    return (_a = l.canonicalFunctions.get(fold(name))) !== null && _a !== void 0 ? _a : name;
+};
+exports.canonicalizeFunctionName = canonicalizeFunctionName;
+/** Localized spelling of a canonical error value (`#VALUE!` → `#ЗНАЧ!`); other text passes through. */
+var localizeErrorValue = function (value, locale) {
+    var _a;
+    if (typeof value !== "string" || value.charCodeAt(0) !== 35 /* # */)
+        return value;
+    var l = (0, exports.getFormulaLocale)(locale);
+    if (l.isCanonical)
+        return value;
+    return (_a = l.errors.get(fold(value))) !== null && _a !== void 0 ? _a : value;
+};
+exports.localizeErrorValue = localizeErrorValue;
+/** Canonical spelling of a localized error value (`#ЗНАЧ!` → `#VALUE!`); other text passes through. */
+var canonicalizeErrorValue = function (value, locale) {
+    var _a;
+    if (typeof value !== "string" || value.charCodeAt(0) !== 35 /* # */)
+        return value;
+    var l = (0, exports.getFormulaLocale)(locale);
+    if (l.isCanonical)
+        return value;
+    return (_a = l.canonicalErrors.get(fold(value))) !== null && _a !== void 0 ? _a : value;
+};
+exports.canonicalizeErrorValue = canonicalizeErrorValue;
+var CH_QUOTE = 34; // "
+var CH_HASH = 35; // #
+var CH_APOSTROPHE = 39; // '
+var CH_OPEN_PAREN = 40; // (
+var CH_PLUS = 43; // +
+var CH_MINUS = 45; // -
+var CH_DOT = 46; // .
+var CH_0 = 48;
+var CH_9 = 57;
+var CH_UPPER_E = 69;
+var CH_OPEN_BRACKET = 91; // [
+var CH_CLOSE_BRACKET = 93; // ]
+var CH_UNDERSCORE = 95; // _
+var CH_LOWER_E = 101;
+var CH_OPEN_BRACE = 123; // {
+var CH_CLOSE_BRACE = 125; // }
+var isDigit = function (code) { return code >= CH_0 && code <= CH_9; };
+var isAsciiLetter = function (code) {
+    return (code >= 65 && code <= 90) || (code >= 97 && code <= 122);
+};
+/** Identifier start: ASCII letter, `_`, or any non-ASCII letter (Cyrillic/accented names, sheet names). */
+var isIdentifierStart = function (code) {
+    return isAsciiLetter(code) || code === CH_UNDERSCORE || code >= 0xc0;
+};
+/** Identifier continuation additionally admits digits and `.` (`T.TEST`, `A1.prop`, `Sheet1`). */
+var isIdentifierPart = function (code) {
+    return isIdentifierStart(code) || isDigit(code) || code === CH_DOT;
+};
+var TRUE_KEY = "TRUE";
+var FALSE_KEY = "FALSE";
+/** Error literals a locale may spell: the canonical set plus its own localized spellings, longest
+ * first so `#N/A` never wins over `#NAME?`-style prefixes of another spelling. */
+var errorLiteralsCache = new WeakMap();
+var errorLiteralsOf = function (locale) {
+    var literals = errorLiteralsCache.get(locale);
+    if (!literals) {
+        literals = tslib_1.__spreadArray([], tslib_1.__read(new Set(tslib_1.__spreadArray(tslib_1.__spreadArray([], tslib_1.__read(exports.CANONICAL_ERROR_VALUES), false), tslib_1.__read(locale.errors.values()), false))), false).sort(function (a, b) { return b.length - a.length; });
+        errorLiteralsCache.set(locale, literals);
+    }
+    return literals;
+};
+var startsWithFolded = function (text, index, literal) {
+    return text.length - index >= literal.length &&
+        fold(text.slice(index, index + literal.length)) === fold(literal);
+};
+var translateName = function (name, from, to, functionNameCase) {
+    var _a;
+    var key = fold(name);
+    // Localized (from) spelling → canonical key; a name the source locale doesn't translate is taken
+    // as its own canonical spelling (so English names are accepted in every locale).
+    var canonical = from.isCanonical ? key : (_a = from.canonicalFunctions.get(key)) !== null && _a !== void 0 ? _a : key;
+    var localized = to.isCanonical ? undefined : to.functions.get(canonical);
+    if (localized !== undefined)
+        return localized;
+    // Translated to English, or spelled with characters that only fold to the canonical name (tr
+    // `ASİN` → `ASIN`): emit the canonical spelling. Otherwise keep the typed case unless asked not to.
+    if (canonical !== key || name.toUpperCase() !== key)
+        return canonical;
+    return functionNameCase === "upper" ? canonical : name;
+};
+/**
+ * Rewrite formula text from one locale's syntax to another's. This is the single scanner behind
+ * {@link localizeFormula} (canonical → locale) and {@link canonicalizeFormula} (locale → canonical);
+ * see the module comment for what is and is not rewritten.
+ */
+var translateFormula = function (text, from, to, options) {
+    var e_7, _a;
+    var _b, _c;
+    if (options === void 0) { options = {}; }
+    var source = (0, exports.getFormulaLocale)(from);
+    var target = (0, exports.getFormulaLocale)(to);
+    var _d = options.functionNameCase, functionNameCase = _d === void 0 ? "preserve" : _d, _e = options.trackOffsets, trackOffsets = _e === void 0 ? false : _e;
+    var length = text.length;
+    // Segments: [sourceFrom, sourceTo, outputFrom, outputTo] flattened. Only recorded when offsets
+    // are wanted; verbatim runs are coalesced.
+    var segments = [];
+    var out = "";
+    var verbatimStart = -1;
+    var verbatimOut = 0;
+    var flushVerbatim = function (end) {
+        if (verbatimStart === -1)
+            return;
+        if (trackOffsets)
+            segments.push(verbatimStart, end, verbatimOut, verbatimOut + (end - verbatimStart));
+        verbatimStart = -1;
+    };
+    var copy = function (from, to) {
+        if (from >= to)
+            return;
+        if (verbatimStart === -1) {
+            verbatimStart = from;
+            verbatimOut = out.length;
+        }
+        out += text.slice(from, to);
+    };
+    var emit = function (from, to, replacement) {
+        if (replacement === text.slice(from, to)) {
+            copy(from, to);
+            return;
+        }
+        flushVerbatim(from);
+        if (trackOffsets)
+            segments.push(from, to, out.length, out.length + replacement.length);
+        out += replacement;
+    };
+    var sourceDecimal = source.decimalSeparator;
+    var sourceDecimalCode = sourceDecimal.charCodeAt(0);
+    var targetDecimal = target.decimalSeparator;
+    var sourceErrorLiterals = errorLiteralsOf(source);
+    var braceDepth = 0;
+    var i = 0;
+    /** Whether the previous significant character continues an identifier/number (so a decimal mark
+     * right after it cannot start a new number literal). */
+    var previousWasWordChar = false;
+    while (i < length) {
+        var code = text.charCodeAt(i);
+        // "…" string literal (with "" escapes): verbatim.
+        if (code === CH_QUOTE) {
+            var j = i + 1;
+            while (j < length) {
+                if (text.charCodeAt(j) === CH_QUOTE) {
+                    if (text.charCodeAt(j + 1) === CH_QUOTE) {
+                        j += 2;
+                        continue;
+                    }
+                    j++;
+                    break;
+                }
+                j++;
+            }
+            copy(i, j);
+            i = j;
+            previousWasWordChar = false;
+            continue;
+        }
+        // '…' quoted sheet / workbook name (with '' escapes): verbatim.
+        if (code === CH_APOSTROPHE) {
+            var j = i + 1;
+            while (j < length) {
+                if (text.charCodeAt(j) === CH_APOSTROPHE) {
+                    if (text.charCodeAt(j + 1) === CH_APOSTROPHE) {
+                        j += 2;
+                        continue;
+                    }
+                    j++;
+                    break;
+                }
+                j++;
+            }
+            copy(i, j);
+            i = j;
+            previousWasWordChar = true; // 'Sheet 1'!A1 — the `!` and reference follow as one word
+            continue;
+        }
+        // [ … ] structured-reference item / R1C1 offset. Column names, special items (`#Headers`) and
+        // `'X` escapes are kept as typed; the ONE thing Excel localizes here is the list separator
+        // between items directly inside the outer bracket (`Table1[[#Headers],[Qty]]` → `;` locales),
+        // which is unambiguous because a column name containing a separator must sit in its own inner
+        // brackets.
+        if (code === CH_OPEN_BRACKET) {
+            var depth = 0;
+            var j = i;
+            while (j < length) {
+                var c = text.charCodeAt(j);
+                if (c === CH_APOSTROPHE && j + 1 < length) {
+                    j += 2; // escaped character inside a column specifier
+                    continue;
+                }
+                if (c === CH_OPEN_BRACKET)
+                    depth++;
+                else if (c === CH_CLOSE_BRACKET) {
+                    depth--;
+                    if (depth === 0) {
+                        j++;
+                        break;
+                    }
+                }
+                else if (depth === 1 && text[j] === source.argumentSeparator) {
+                    copy(i, j);
+                    emit(j, j + 1, target.argumentSeparator);
+                    i = j + 1;
+                }
+                j++;
+            }
+            copy(i, j);
+            i = j;
+            previousWasWordChar = true;
+            continue;
+        }
+        if (code === CH_OPEN_BRACE) {
+            braceDepth++;
+            copy(i, i + 1);
+            i++;
+            previousWasWordChar = false;
+            continue;
+        }
+        if (code === CH_CLOSE_BRACE) {
+            if (braceDepth > 0)
+                braceDepth--;
+            copy(i, i + 1);
+            i++;
+            previousWasWordChar = true;
+            continue;
+        }
+        // #VALUE! / #ЗНАЧ! … error values.
+        if (code === CH_HASH) {
+            var matched = void 0;
+            try {
+                for (var sourceErrorLiterals_1 = (e_7 = void 0, tslib_1.__values(sourceErrorLiterals)), sourceErrorLiterals_1_1 = sourceErrorLiterals_1.next(); !sourceErrorLiterals_1_1.done; sourceErrorLiterals_1_1 = sourceErrorLiterals_1.next()) {
+                    var literal = sourceErrorLiterals_1_1.value;
+                    if (startsWithFolded(text, i, literal)) {
+                        matched = literal;
+                        break;
+                    }
+                }
+            }
+            catch (e_7_1) { e_7 = { error: e_7_1 }; }
+            finally {
+                try {
+                    if (sourceErrorLiterals_1_1 && !sourceErrorLiterals_1_1.done && (_a = sourceErrorLiterals_1.return)) _a.call(sourceErrorLiterals_1);
+                }
+                finally { if (e_7) throw e_7.error; }
+            }
+            if (matched) {
+                var canonical = (_b = source.canonicalErrors.get(fold(matched))) !== null && _b !== void 0 ? _b : fold(matched);
+                var localized = (_c = target.errors.get(canonical)) !== null && _c !== void 0 ? _c : canonical;
+                emit(i, i + matched.length, localized);
+                i += matched.length;
+                previousWasWordChar = true;
+                continue;
+            }
+            copy(i, i + 1);
+            i++;
+            previousWasWordChar = false;
+            continue;
+        }
+        // Number literal: digits [decimal digits*] [E[+-]digits], or a bare `.5` after a non-word char.
+        var startsNumber = isDigit(code) ||
+            (code === sourceDecimalCode && !previousWasWordChar && isDigit(text.charCodeAt(i + 1)));
+        if (startsNumber) {
+            var j = i;
+            var sawDecimal = false;
+            while (j < length) {
+                var c = text.charCodeAt(j);
+                if (isDigit(c)) {
+                    j++;
+                    continue;
+                }
+                if (!sawDecimal && c === sourceDecimalCode && (j > i || isDigit(text.charCodeAt(j + 1)))) {
+                    // A decimal mark is part of the literal when digits precede it (`1.` is Excel's 1) or
+                    // follow it (`.5`).
+                    sawDecimal = true;
+                    j++;
+                    continue;
+                }
+                break;
+            }
+            // Exponent — only when something numeric follows the E.
+            if (j < length) {
+                var c = text.charCodeAt(j);
+                if (c === CH_UPPER_E || c === CH_LOWER_E) {
+                    var k = j + 1;
+                    var sign = text.charCodeAt(k);
+                    if (sign === CH_PLUS || sign === CH_MINUS)
+                        k++;
+                    if (isDigit(text.charCodeAt(k))) {
+                        while (k < length && isDigit(text.charCodeAt(k)))
+                            k++;
+                        j = k;
+                    }
+                }
+            }
+            var literal = text.slice(i, j);
+            emit(i, j, sawDecimal && sourceDecimal !== targetDecimal ? literal.split(sourceDecimal).join(targetDecimal) : literal);
+            i = j;
+            previousWasWordChar = true;
+            continue;
+        }
+        // Identifier: function name (when followed by `(`), TRUE/FALSE, or a reference/name (verbatim).
+        if (isIdentifierStart(code)) {
+            var j = i + 1;
+            // `.` is an identifier character (`T.TEST`, `A1.prop`) — except inside an array constant of a
+            // locale whose column separator IS `.` (`{1.FALSCH.2}` in de), where it separates items.
+            while (j < length && isIdentifierPart(text.charCodeAt(j))) {
+                if (braceDepth > 0 &&
+                    (text[j] === source.arrayColumnSeparator || text[j] === source.arrayRowSeparator)) {
+                    break;
+                }
+                j++;
+            }
+            var word = text.slice(i, j);
+            if (text.charCodeAt(j) === CH_OPEN_PAREN) {
+                emit(i, j, translateName(word, source, target, functionNameCase));
+            }
+            else {
+                var key = fold(word);
+                var canonicalBoolean = key === TRUE_KEY || key === FALSE_KEY
+                    ? key
+                    : source.canonicalFunctions.get(key);
+                if (canonicalBoolean === TRUE_KEY || canonicalBoolean === FALSE_KEY) {
+                    var localized = target.functions.get(canonicalBoolean);
+                    emit(i, j, localized !== null && localized !== void 0 ? localized : (canonicalBoolean === key && functionNameCase !== "upper" ? word : canonicalBoolean));
+                }
+                else {
+                    copy(i, j);
+                }
+            }
+            i = j;
+            previousWasWordChar = true;
+            continue;
+        }
+        // Separators.
+        var ch = text[i];
+        if (braceDepth > 0) {
+            if (ch === source.arrayColumnSeparator) {
+                emit(i, i + 1, target.arrayColumnSeparator);
+                i++;
+                previousWasWordChar = false;
+                continue;
+            }
+            if (ch === source.arrayRowSeparator) {
+                emit(i, i + 1, target.arrayRowSeparator);
+                i++;
+                previousWasWordChar = false;
+                continue;
+            }
+        }
+        else if (ch === source.argumentSeparator) {
+            emit(i, i + 1, target.argumentSeparator);
+            i++;
+            previousWasWordChar = false;
+            continue;
+        }
+        copy(i, i + 1);
+        i++;
+        // `$`/`!` keep a reference word going (`$A$1`, `Sheet1!A1`); anything else ends it.
+        previousWasWordChar = code === 36 /* $ */ || code === 33 /* ! */;
+    }
+    flushVerbatim(length);
+    var result = { text: out };
+    if (trackOffsets) {
+        var toOutput = new Int32Array(length + 1);
+        var toSource = new Int32Array(out.length + 1);
+        for (var s = 0; s < segments.length; s += 4) {
+            var sFrom = segments[s];
+            var sTo = segments[s + 1];
+            var oFrom = segments[s + 2];
+            var oTo = segments[s + 3];
+            if (sTo - sFrom === oTo - oFrom) {
+                for (var k = 0; k < sTo - sFrom; k++) {
+                    toOutput[sFrom + k] = oFrom + k;
+                    toSource[oFrom + k] = sFrom + k;
+                }
+            }
+            else {
+                for (var k = sFrom; k < sTo; k++)
+                    toOutput[k] = oFrom;
+                for (var k = oFrom; k < oTo; k++)
+                    toSource[k] = sFrom;
+            }
+        }
+        toOutput[length] = out.length;
+        toSource[out.length] = length;
+        result.toOutput = toOutput;
+        result.toSource = toSource;
+    }
+    return result;
+};
+exports.translateFormula = translateFormula;
+/**
+ * Canonical (stored) formula text → the locale's display syntax: `=SUM(1.5,A1)` → `=СУММ(1,5;A1)`
+ * (ru), `=SUMME(1,5;A1)` (de). Identity for the canonical locale.
+ */
+var localizeFormula = function (formula, locale, options) {
+    var target = (0, exports.getFormulaLocale)(locale);
+    if (target.isCanonical && !(options === null || options === void 0 ? void 0 : options.trackOffsets) && (options === null || options === void 0 ? void 0 : options.functionNameCase) !== "upper") {
+        return formula;
+    }
+    return (0, exports.translateFormula)(formula, exports.CANONICAL_FORMULA_LOCALE, target, options).text;
+};
+exports.localizeFormula = localizeFormula;
+/**
+ * Text typed in the locale's syntax → canonical formula text for storage and evaluation:
+ * `=СУММ(1,5;A1)` → `=SUM(1.5,A1)`. Exact inverse of {@link localizeFormula} on canonical input;
+ * lenient on mixed input (an English name or `,` argument separator typed in a `;` locale is
+ * accepted as long as it is unambiguous).
+ */
+var canonicalizeFormula = function (formula, locale, options) {
+    var source = (0, exports.getFormulaLocale)(locale);
+    if (source.isCanonical && !(options === null || options === void 0 ? void 0 : options.trackOffsets) && (options === null || options === void 0 ? void 0 : options.functionNameCase) !== "upper") {
+        return formula;
+    }
+    return (0, exports.translateFormula)(formula, source, exports.CANONICAL_FORMULA_LOCALE, options).text;
+};
+exports.canonicalizeFormula = canonicalizeFormula;
+// ── Cell entries ─────────────────────────────────────────────────────────────────────────────────
+/**
+ * What the editor / formula bar SHOWS for a stored cell entry: a formula in the locale's syntax, a
+ * typed error value in the locale's spelling, any other text unchanged (`1,5` typed in de-DE is a
+ * number literal the datatype parser already reads with the locale's separators).
+ */
+var localizeCellInput = function (text, locale) {
+    return (0, formula_1.isAFormula)(text) ? (0, exports.localizeFormula)(text, locale) : (0, exports.localizeErrorValue)(text, locale);
+};
+exports.localizeCellInput = localizeCellInput;
+/** Inverse of {@link localizeCellInput}: what the editor COMMITS — canonical formula text / error value. */
+var canonicalizeCellInput = function (text, locale) {
+    return (0, formula_1.isAFormula)(text) ? (0, exports.canonicalizeFormula)(text, locale) : (0, exports.canonicalizeErrorValue)(text, locale);
+};
+exports.canonicalizeCellInput = canonicalizeCellInput;
+// ── Function catalog (autocomplete + argument hints) ─────────────────────────────────────────────
+/**
+ * Localize a function's documented syntax (`SUM(value1, [value2, ...])` → `СУММ(value1; [value2;
+ * ...])`): the leading name through the dictionary, every `,` outside double quotes through the
+ * argument separator. The square brackets here mark OPTIONAL arguments (not structured references),
+ * so — unlike {@link localizeFormula} — the separators inside them are localized too.
+ */
+var localizeFunctionSyntax = function (syntax, locale) {
+    var e_8, _a;
+    var l = (0, exports.getFormulaLocale)(locale);
+    if (l.isCanonical)
+        return syntax;
+    var open = syntax.indexOf("(");
+    var name = open === -1 ? syntax : syntax.slice(0, open);
+    var rest = open === -1 ? "" : syntax.slice(open);
+    var out = "";
+    var inString = false;
+    try {
+        for (var rest_1 = tslib_1.__values(rest), rest_1_1 = rest_1.next(); !rest_1_1.done; rest_1_1 = rest_1.next()) {
+            var ch = rest_1_1.value;
+            if (ch === '"')
+                inString = !inString;
+            out += !inString && ch === "," ? l.argumentSeparator : ch;
+        }
+    }
+    catch (e_8_1) { e_8 = { error: e_8_1 }; }
+    finally {
+        try {
+            if (rest_1_1 && !rest_1_1.done && (_a = rest_1.return)) _a.call(rest_1);
+        }
+        finally { if (e_8) throw e_8.error; }
+    }
+    return (0, exports.localizeFunctionName)(name.trim(), l) + name.slice(name.trim().length) + out;
+};
+exports.localizeFunctionSyntax = localizeFunctionSyntax;
+/** A {@link CalculatorFunction} with its name, syntax, example and usage lines localized. */
+var localizeFunctionDescription = function (fn, locale) {
+    var _a;
+    var l = (0, exports.getFormulaLocale)(locale);
+    if (l.isCanonical)
+        return fn;
+    return tslib_1.__assign(tslib_1.__assign({}, fn), { title: (0, exports.localizeFunctionName)(fn.title, l), syntax: (0, exports.localizeFunctionSyntax)(fn.syntax, l), example: fn.example === undefined ? fn.example : (0, exports.localizeFormula)(fn.example, l), usage: (_a = fn.usage) === null || _a === void 0 ? void 0 : _a.map(function (usage) { return (0, exports.localizeFormula)(usage, l); }) });
+};
+exports.localizeFunctionDescription = localizeFunctionDescription;
+/** {@link localizeFunctionDescription} over a catalog; the same array instance for the canonical locale. */
+var localizeFunctionDescriptions = function (functions, locale) {
+    var l = (0, exports.getFormulaLocale)(locale);
+    if (!functions || l.isCanonical)
+        return functions;
+    return functions.map(function (fn) { return (0, exports.localizeFunctionDescription)(fn, l); });
+};
+exports.localizeFunctionDescriptions = localizeFunctionDescriptions;