@adminiumjs/i18n 0.1.2 → 0.2.2-rc.0

package/dist/validate-message.js

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Write-time validation for admin-authored messages
+ * (23-runtime-translations.md §6.3).
+ *
+ * This is the ONLY thing standing between an admin's typing and every user's
+ * screen, because once a message comes from the meta store the build-time
+ * gates cannot see it (23 §10). It runs in the browser (live editor feedback)
+ * and on the server (the real boundary) from this one module, so the two can
+ * never disagree about what is acceptable.
+ *
+ * It parses with `IntlMessageFormat(...).getAst()` — the exact mechanism both
+ * `IcuFormat` and the parity gate use — rather than a second parser that
+ * could accept what the renderer rejects.
+ *
+ * The rules are deliberately STRICTER than the compiled-bundle parity gate on
+ * one axis: argument TYPE must match the source, not just argument name. That
+ * is not pedantry, it is the fix for a real hazard — 48 call sites in this
+ * repo do their own `.replace('{count}', …)` on the `t()` result and pass no
+ * ICU args at all. For those keys, `format()` throws on the missing variable,
+ * the raw string is returned, and the literal `{count}` token is what the
+ * `.replace` finds. An override that turned `{count}` into `{count, number}`
+ * would pass every name-based check and then render raw ICU to users. Types
+ * matching means it cannot.
+ */
+import { IntlMessageFormat } from 'intl-messageformat';
+import { intlTagForLocale, pluralCategoriesForLocale } from './locales.js';
+function walk(nodes, shape) {
+    for (const node of nodes) {
+        if (node.type >= 1 && node.type <= 6 && typeof node.value === 'string') {
+            shape.args.set(node.value, node.type);
+        }
+        if ((node.type === 5 || node.type === 6) && node.options !== undefined) {
+            if (node.type === 6 && typeof node.value === 'string') {
+                shape.plurals.set(node.value, Object.keys(node.options).sort());
+            }
+            for (const option of Object.values(node.options))
+                walk(option.value, shape);
+        }
+        if (node.children !== undefined)
+            walk(node.children, shape);
+    }
+}
+/** Parse + extract, keeping the parser's reason so the admin gets a real message. */
+function shapeOf(message, intlTag) {
+    const shape = { args: new Map(), plurals: new Map() };
+    try {
+        const ast = new IntlMessageFormat(message, intlTag, undefined, {
+            ignoreTag: true,
+        }).getAst();
+        walk(ast, shape);
+    }
+    catch (error) {
+        return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+    return { ok: true, shape };
+}
+/**
+ * The parser rejects some things before the shape checks below can run — most
+ * importantly a plural or select with no `other` branch, which it reports as
+ * `MISSING_OTHER_CLAUSE`. Translating its machine reason into an admin-facing
+ * sentence matters: "this is not valid ICU" tells someone editing German copy
+ * nothing about which branch they forgot.
+ */
+function explainParseFailure(reason) {
+    if (reason.includes('MISSING_OTHER_CLAUSE')) {
+        return {
+            code: 'PLURAL_MISSING_OTHER',
+            message: 'Every plural and select needs an "other" branch — it is the fallback used when no other case matches.',
+        };
+    }
+    if (reason.includes('CLOSING_BRACE') || reason.includes('EXPECT_ARGUMENT')) {
+        return {
+            code: 'ICU_SYNTAX',
+            message: 'Unbalanced braces — every { needs a matching }.',
+        };
+    }
+    return {
+        code: 'ICU_SYNTAX',
+        message: `This is not valid ICU MessageFormat (${reason}).`,
+    };
+}
+const ARG_TYPE_NAMES = {
+    1: 'plain',
+    2: 'number',
+    3: 'date',
+    4: 'time',
+    5: 'select',
+    6: 'plural',
+};
+function typeName(type) {
+    return type === undefined ? 'absent' : (ARG_TYPE_NAMES[type] ?? `type ${String(type)}`);
+}
+/**
+ * Validate one admin-authored override against its en-US source.
+ * Collects every failure rather than stopping at the first, so the editor can
+ * show an admin all of what is wrong in one pass.
+ */
+export function validateMessage(opts) {
+    const { candidate, source, locale } = opts;
+    const errors = [];
+    // An empty override is the third state, not a malformed message.
+    if (candidate === '') {
+        return opts.allowEmpty === true
+            ? { ok: true }
+            : { ok: false, errors: [{ code: 'ICU_SYNTAX', message: 'This message may not be blank.' }] };
+    }
+    const intlTag = intlTagForLocale(locale);
+    const parsed = shapeOf(candidate, intlTag);
+    if (!parsed.ok)
+        return { ok: false, errors: [explainParseFailure(parsed.reason)] };
+    const candidateShape = parsed.shape;
+    // The source is en-US by definition; parse it under en-US so a locale with
+    // unusual plural rules cannot make a perfectly good source look invalid.
+    const parsedSource = shapeOf(source, 'en-US');
+    // A broken SOURCE is a repo bug, not an admin's fault — accept the override
+    // rather than blocking an admin on something they cannot fix.
+    if (!parsedSource.ok)
+        return { ok: true };
+    const sourceShape = parsedSource.shape;
+    const sourceArgs = [...sourceShape.args.keys()].sort();
+    const candidateArgs = [...candidateShape.args.keys()].sort();
+    const missing = sourceArgs.filter((a) => !candidateShape.args.has(a));
+    const extra = candidateArgs.filter((a) => !sourceShape.args.has(a));
+    if (missing.length > 0 || extra.length > 0) {
+        const parts = [];
+        if (missing.length > 0)
+            parts.push(`missing {${missing.join('}, {')}}`);
+        if (extra.length > 0)
+            parts.push(`unexpected {${extra.join('}, {')}}`);
+        errors.push({
+            code: 'ARG_MISMATCH',
+            message: `Placeholders must match the English source exactly — ${parts.join('; ')}.`,
+        });
+    }
+    // Argument TYPE parity — the literal-token guard (see the file header).
+    for (const [name, sourceType] of sourceShape.args) {
+        const candidateType = candidateShape.args.get(name);
+        if (candidateType !== undefined && candidateType !== sourceType) {
+            errors.push({
+                code: 'ARG_TYPE_MISMATCH',
+                message: `{${name}} must stay a ${typeName(sourceType)} placeholder — it was changed to ${typeName(candidateType)}.`,
+            });
+        }
+    }
+    // Plural parity is BIDIRECTIONAL, matching the compiled parity gate: an
+    // override may neither drop a plural the source has nor invent one it does
+    // not, because the call site's arguments are fixed by the source.
+    const sourcePlurals = [...sourceShape.plurals.keys()].sort();
+    const candidatePlurals = [...candidateShape.plurals.keys()].sort();
+    if (sourcePlurals.join(',') !== candidatePlurals.join(',')) {
+        errors.push({
+            code: 'PLURAL_MISMATCH',
+            message: sourcePlurals.length === 0
+                ? `The English source has no plural, so this override may not add one (${candidatePlurals.join(', ')}).`
+                : `Plural placeholders must match the English source exactly (expected ${sourcePlurals.join(', ') || 'none'}).`,
+        });
+    }
+    // Every selector must be a category this locale actually has, and `other`
+    // is mandatory — it is the branch ICU falls back to.
+    const categories = new Set(pluralCategoriesForLocale(locale));
+    for (const [name, selectors] of candidateShape.plurals) {
+        const unknown = selectors.filter((s) => !categories.has(s) && !s.startsWith('=') && s !== 'other');
+        if (unknown.length > 0) {
+            errors.push({
+                code: 'PLURAL_CATEGORY',
+                message: `{${name}} uses plural categories this language does not have: ${unknown.join(', ')}. Available: ${[...categories].join(', ')}.`,
+            });
+        }
+        if (!selectors.includes('other')) {
+            errors.push({
+                code: 'PLURAL_MISSING_OTHER',
+                message: `{${name}} must include an "other" branch — it is the fallback every language needs.`,
+            });
+        }
+    }
+    return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+//# sourceMappingURL=validate-message.js.map

package/dist/validate-message.js.map

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