@widgetic/design-system 0.5.15 → 0.5.17

package/dist/i18n/audit/messageCalls.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Finds where the code asks the catalog for a message: `$t('upload.cancel')`, `$t('key', { name })`,
+ * `messageForVisitor(error, $t, 'key')`, `{ messageKey: 'key', messageValues: { limit } }`. A test then checks that each
+ * key is in the catalog and that the values given are the values the message asks for (a value that is never given shows
+ * up in the page as a bare `{name}`).
+ *
+ * It reads the syntax tree, like `visibleText.ts`. A `.ts` file is read as the body of a module script, which Svelte's
+ * parser reads with the same TypeScript support.
+ */
+export interface MessageCall {
+    file: string;
+    line: number;
+    /** The key, when it is a plain string; the part before the `${...}` when it is built (`filterName.${filter}`). */
+    key: string;
+    /** True when the key is built from a value (`filterName.${filter}`): only the start of it is known. */
+    keyIsPrefix: boolean;
+    /** The names of the values handed over, or `null` when they are not written out as an object (`$t('key', values)`). */
+    valueNames: string[] | null;
+    /** Which call it is, for the failure message. */
+    via: string;
+}
+/** A function that looks a message up: which of its arguments is the key, and which holds the values (`null` when none does). */
+export interface MessageLookup {
+    key: number;
+    values: number | null;
+}
+/** The functions every package uses to look a message up. */
+export declare const DEFAULT_LOOKUPS: Readonly<Record<string, MessageLookup>>;
+export interface MessageCallOptions {
+    /** More functions that look a message up (`messageForVisitor: { key: 2, values: null }`). Added to the defaults. */
+    lookups?: Readonly<Record<string, MessageLookup>>;
+}
+/** Every message the code in one file asks for. */
+export declare function findMessageCalls(file: string, source: string, options?: MessageCallOptions): MessageCall[];

package/dist/i18n/audit/messageCalls.js

@@ -0,0 +1,89 @@
+import { lineOf, parseFile, walkTree } from "./syntaxTree.js";
+/** The functions every package uses to look a message up. */
+export const DEFAULT_LOOKUPS = {
+    $t: { key: 0, values: 1 },
+    t: { key: 0, values: 1 },
+    translate: { key: 0, values: 1 },
+    translateEnglish: { key: 0, values: 1 }
+};
+/** The name of a function called by its own name (`t`); an empty text for a method call or anything else. */
+function plainCalleeName(call) {
+    const callee = call.callee;
+    if (!callee)
+        return '';
+    if (callee.type === 'Identifier')
+        return callee.name;
+    return '';
+}
+/** The key written at a node: a string, or the fixed start of a template literal. `null` for anything else. */
+function keyOf(node) {
+    if (!node)
+        return null;
+    if (node.type === 'Literal' && typeof node.value === 'string')
+        return { key: node.value, keyIsPrefix: false };
+    if (node.type === 'TemplateLiteral') {
+        const start = node.quasis[0]?.value?.cooked ?? '';
+        return node.expressions.length === 0 ? { key: start, keyIsPrefix: false } : { key: start, keyIsPrefix: true };
+    }
+    return null;
+}
+/** The property names of an object written out in the code, or null when the node is anything else. */
+function propertyNamesOf(node) {
+    if (!node || node.type !== 'ObjectExpression')
+        return null;
+    const names = [];
+    for (const property of node.properties) {
+        // A spread (`{ ...values }`) or a computed name (`{ [name]: 1 }`) hides names: give up on this call rather than guess.
+        if (property.type !== 'Property' || property.computed)
+            return null;
+        const name = property.key?.name ?? property.key?.value;
+        if (typeof name !== 'string')
+            return null;
+        names.push(name);
+    }
+    return names;
+}
+/** Every message the code in one file asks for. */
+export function findMessageCalls(file, source, options = {}) {
+    const lookups = { ...DEFAULT_LOOKUPS, ...(options.lookups ?? {}) };
+    const { tree, text, lineShift } = parseFile(file, source);
+    const calls = [];
+    for (const { node, parents } of walkTree(tree)) {
+        if (node.type === 'CallExpression') {
+            const name = plainCalleeName(node);
+            // An own-property check: a function called `constructor` or `toString` is not a lookup.
+            const lookup = Object.prototype.hasOwnProperty.call(lookups, name) ? lookups[name] : undefined;
+            if (lookup === undefined)
+                continue;
+            const key = keyOf(node.arguments?.[lookup.key]);
+            if (key === null)
+                continue;
+            const valuesNode = lookup.values === null ? undefined : node.arguments?.[lookup.values];
+            calls.push({
+                file,
+                line: lineOf(text, node.start ?? 0) - lineShift,
+                ...key,
+                valueNames: lookup.values === null ? [] : valuesNode === undefined ? [] : propertyNamesOf(valuesNode),
+                via: `${name}()`
+            });
+        }
+        else if (node.type === 'Property' && (node.key?.name === 'messageKey' || node.key?.value === 'messageKey')) {
+            const key = keyOf(node.value);
+            if (key === null)
+                continue;
+            // The values sit next to the key, in the same object: `{ messageKey: 'key', messageValues: { limit } }`.
+            const parent = parents[parents.length - 1];
+            const valuesProperty = parent?.type === 'ObjectExpression'
+                ? parent.properties.find((sibling) => sibling.type === 'Property' && (sibling.key?.name === 'messageValues' || sibling.key?.value === 'messageValues'))
+                : undefined;
+            calls.push({
+                file,
+                line: lineOf(text, node.start ?? 0) - lineShift,
+                ...key,
+                valueNames: valuesProperty === undefined ? [] : propertyNamesOf(valuesProperty.value),
+                via: 'messageKey'
+            });
+        }
+    }
+    return calls;
+}

package/dist/i18n/audit/syntaxTree.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What the audits of the words of a package share: reading a file into Svelte's syntax tree, walking it, and listing
+ * the files of a folder. Test and build tooling only: it reads the source of a package, so a page never loads it.
+ */
+export type SyntaxNode = any;
+/** A file read into a syntax tree. */
+export interface ParsedFile {
+    /** The tree of the Svelte file (a `.ts` file is read as the body of a module script, which has the same TypeScript support). */
+    tree: SyntaxNode;
+    /** The text the tree was made from: the file itself, or the file inside the module script that wraps it. */
+    text: string;
+    /** How many lines lower than in the file the text puts the code: 1 for a `.ts` file (the wrapper), 0 for a Svelte file. */
+    lineShift: number;
+}
+/** Reads a Svelte file, or a `.ts` file (as the body of a module script), into Svelte's modern syntax tree. */
+export declare function parseFile(file: string, source: string): ParsedFile;
+/** The line (from 1) of a character offset in a text. */
+export declare function lineOf(source: string, offset: number): number;
+/** Every node of a tree, with the nodes above it (the closest last). Fields that hold positions or types, not code, are skipped. */
+export declare function walkTree(node: SyntaxNode, parents?: SyntaxNode[]): Generator<{
+    node: SyntaxNode;
+    parents: SyntaxNode[];
+}>;
+/** The name of the function a call node calls: `t`, or `toast.error` for a member call; an empty text for anything else. */
+export declare function calleeName(call: SyntaxNode): string;
+/** The text of a string or template literal, with `{}` where a value goes; null for any other node. */
+export declare function literalText(node: SyntaxNode): string | null;
+/** Every file under `folder` whose name `wanted` accepts, as sorted paths. */
+export declare function listFiles(folder: string, wanted: (name: string) => boolean): string[];
+/** Every Svelte file under `folder`, as paths. */
+export declare function listSvelteFiles(folder: string): string[];
+/** Every Svelte and TypeScript file under `folder` (declaration files left out), as paths. */
+export declare function listSourceFiles(folder: string): string[];

package/dist/i18n/audit/syntaxTree.js

@@ -0,0 +1,90 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from 'svelte/compiler';
+/** Reads a Svelte file, or a `.ts` file (as the body of a module script), into Svelte's modern syntax tree. */
+export function parseFile(file, source) {
+    const isSvelte = file.endsWith('.svelte');
+    // A `.ts` file is read inside a script, so a closing script tag in one of its strings (the code of an embed has one)
+    // would end the script early (Svelte ends a script at `</script>`, with spaces allowed before the `>`). `<\/script` is
+    // the same text inside a string or a template, and no line moves.
+    const text = isSvelte ? source : `<script lang="ts" module>\n${source.replace(/<\/script/g, '<\\/script')}\n</script>`;
+    return { tree: parse(text, { modern: true, filename: file }), text, lineShift: isSvelte ? 0 : 1 };
+}
+/** The line (from 1) of a character offset in a text. */
+export function lineOf(source, offset) {
+    let line = 1;
+    for (let index = 0; index < offset && index < source.length; index += 1) {
+        if (source.charCodeAt(index) === 10)
+            line += 1;
+    }
+    return line;
+}
+/** Fields that hold positions, or the types of TypeScript: neither is code that runs, so no word a visitor reads is in them. */
+const SKIPPED_FIELDS = new Set([
+    'loc',
+    'start',
+    'end',
+    'type',
+    'metadata',
+    'parent',
+    'typeAnnotation',
+    'typeArguments'
+]);
+/** Every node of a tree, with the nodes above it (the closest last). Fields that hold positions or types, not code, are skipped. */
+export function* walkTree(node, parents = []) {
+    if (!node || typeof node !== 'object')
+        return;
+    if (Array.isArray(node)) {
+        for (const child of node)
+            yield* walkTree(child, parents);
+        return;
+    }
+    if (typeof node.type === 'string')
+        yield { node, parents };
+    for (const key of Object.keys(node)) {
+        if (SKIPPED_FIELDS.has(key))
+            continue;
+        const value = node[key];
+        if (value && typeof value === 'object')
+            yield* walkTree(value, typeof node.type === 'string' ? [...parents, node] : parents);
+    }
+}
+/** The name of the function a call node calls: `t`, or `toast.error` for a member call; an empty text for anything else. */
+export function calleeName(call) {
+    const callee = call.callee;
+    if (!callee)
+        return '';
+    if (callee.type === 'Identifier')
+        return callee.name;
+    if (callee.type === 'MemberExpression')
+        return `${calleeName({ callee: callee.object })}.${callee.property?.name ?? ''}`;
+    return '';
+}
+/** The text of a string or template literal, with `{}` where a value goes; null for any other node. */
+export function literalText(node) {
+    if (node.type === 'Literal' && typeof node.value === 'string')
+        return node.value;
+    if (node.type === 'TemplateLiteral')
+        return node.quasis.map((quasi) => quasi.value.cooked).join('{}');
+    return null;
+}
+/** Every file under `folder` whose name `wanted` accepts, as sorted paths. */
+export function listFiles(folder, wanted) {
+    const files = [];
+    for (const entry of fs.readdirSync(folder, { withFileTypes: true })) {
+        const full = path.join(folder, entry.name);
+        if (entry.isDirectory())
+            files.push(...listFiles(full, wanted));
+        else if (wanted(entry.name))
+            files.push(full);
+    }
+    return files.sort();
+}
+/** Every Svelte file under `folder`, as paths. */
+export function listSvelteFiles(folder) {
+    return listFiles(folder, (name) => name.endsWith('.svelte'));
+}
+/** Every Svelte and TypeScript file under `folder` (declaration files left out), as paths. */
+export function listSourceFiles(folder) {
+    return listFiles(folder, (name) => (name.endsWith('.svelte') || name.endsWith('.ts')) && !name.endsWith('.d.ts'));
+}

package/dist/i18n/audit/visibleText.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Finds the English a visitor can read in the Svelte files (and the TypeScript files) of a package, so a test can insist
+ * that all of it comes from the message catalog. It reads the syntax tree (never a regular expression over the text), so
+ * it sees what Svelte sees:
+ *
+ *  - text between tags that contains a letter,
+ *  - the text-like attributes (`title`, `aria-label`, `alt`, `placeholder`, and the props a design-system component
+ *    shows: `label`, `message`, `description`, `confirmLabel`, `cancelLabel` ...) when they are a literal or hold a literal,
+ *  - string literals inside a `{...}` in the template,
+ *  - the strings handed to `showToast(...)` / `toast.*(...)`, or to a property called `description`, `title`,
+ *    `message`, `text` or `label` of such a call or of an object assigned in the script, or a variable whose name ends in
+ *    `Label`, `Message`, `Title`, `Description` or `Text`,
+ *  - the strings given as VALUES to a message lookup (`t('x.y', { name: item.name || 'Item' })`): they go into the
+ *    sentence, so a word written there is a word of the sentence that no catalog can say in another language.
+ *
+ * A package adds the names it uses for words (`emptyText`, `previewError` ...) with the options.
+ */
+export interface VisibleText {
+    file: string;
+    line: number;
+    kind: 'text' | 'attribute' | 'expression' | 'script';
+    /** The attribute, property or call the text sits in. */
+    where: string;
+    text: string;
+}
+/** Attributes (of an element or of a component) whose value a visitor reads or hears. */
+export declare const DEFAULT_TEXT_ATTRIBUTES: readonly string[];
+/** Property names that hold a sentence when they are written in a script. */
+export declare const DEFAULT_TEXT_PROPERTIES: readonly string[];
+/** The functions that look a message up, with the position of the argument that is the key (code, not words). */
+export declare const DEFAULT_MESSAGE_LOOKUPS: Readonly<Record<string, number>>;
+/** A variable with a name like this holds words (`const emptyText = '...'`, `let message = '...'`). */
+export declare const DEFAULT_TEXT_VARIABLE_PATTERN: RegExp;
+/** What a package can add to what the scan looks for. Everything is added to the defaults above; nothing replaces them. */
+export interface VisibleTextOptions {
+    /** More attribute names whose value a visitor reads (the props of the package's own components that show words). */
+    textAttributes?: readonly string[];
+    /** More property names that hold a sentence in a script (`previewError`, `hint` ...). */
+    textProperties?: readonly string[];
+    /** Replaces the pattern of the names of variables that hold words. */
+    textVariablePattern?: RegExp;
+    /** Functions whose strings are words a visitor reads (a function that returns the sentence of a failure). */
+    textFunctions?: readonly string[];
+    /** More functions that look a message up, with the position of the key in their arguments (`{ messageForVisitor: 2 }`). */
+    messageLookups?: Readonly<Record<string, number>>;
+    /**
+     * The keys of the package's catalog. A string that is exactly one of them is the NAME of a message, not words: a table
+     * of keys written as `{ text: 'chat.contextType.text' }` (a property that holds words when it holds a sentence) is read
+     * by the code that looks the message up. A string that is not a key of the catalog is read as usual.
+     */
+    messageKeys?: Iterable<string>;
+}
+/**
+ * The visible English in one file: a Svelte file (its markup and its scripts) or a `.ts` file (its code, as a script).
+ * Lines are the lines of the file.
+ */
+export declare function findVisibleText(file: string, source: string, options?: VisibleTextOptions): VisibleText[];

package/dist/i18n/audit/visibleText.js

@@ -0,0 +1,252 @@
+import { calleeName, lineOf, literalText, parseFile, walkTree } from "./syntaxTree.js";
+/** Attributes (of an element or of a component) whose value a visitor reads or hears. */
+export const DEFAULT_TEXT_ATTRIBUTES = [
+    'title',
+    'aria-label',
+    'aria-description',
+    'aria-valuetext',
+    'alt',
+    'placeholder',
+    'label',
+    'message',
+    'description',
+    'confirmLabel',
+    'cancelLabel',
+    'closeLabel',
+    'text',
+    'heading',
+    'tooltip',
+    'caption'
+];
+/** Property names that hold a sentence when they are written in a script. */
+export const DEFAULT_TEXT_PROPERTIES = ['text', 'label', 'title', 'message', 'description', 'placeholder', 'errorMessage'];
+/** The functions that look a message up, with the position of the argument that is the key (code, not words). */
+export const DEFAULT_MESSAGE_LOOKUPS = { $t: 0, t: 0, translate: 0, translateEnglish: 0 };
+/** A variable with a name like this holds words (`const emptyText = '...'`, `let message = '...'`). */
+export const DEFAULT_TEXT_VARIABLE_PATTERN = /^(label|message|title|description|text)$|(Label|Message|Title|Description|Text)$/;
+function settingsOf(options) {
+    return {
+        textAttributes: new Set([...DEFAULT_TEXT_ATTRIBUTES, ...(options.textAttributes ?? [])]),
+        textProperties: new Set([...DEFAULT_TEXT_PROPERTIES, ...(options.textProperties ?? [])]),
+        textVariablePattern: options.textVariablePattern ?? DEFAULT_TEXT_VARIABLE_PATTERN,
+        textFunctions: new Set(options.textFunctions ?? []),
+        messageLookups: { ...DEFAULT_MESSAGE_LOOKUPS, ...(options.messageLookups ?? {}) },
+        messageKeys: new Set(options.messageKeys ?? [])
+    };
+}
+const HAS_LETTER = /\p{L}/u;
+/** True for a literal that is only compared (`status === 'failed'`) or used as a key (`map['key']`): code, not words. */
+function isOnlyCompared(parents) {
+    const parent = parents[parents.length - 1];
+    if (!parent)
+        return false;
+    if (parent.type === 'BinaryExpression' && ['==', '===', '!=', '!=='].includes(parent.operator))
+        return true;
+    if (parent.type === 'MemberExpression' && parent.computed)
+        return true;
+    if (parent.type === 'SwitchCase')
+        return true;
+    return false;
+}
+/** True for the key in `$t('upload.cancel')` or in `messageForVisitor(error, $t, 'upload.unknownError')`. */
+function isMessageKey(node, parents, settings) {
+    const parent = parents[parents.length - 1];
+    if (parent?.type !== 'CallExpression')
+        return false;
+    const keyPosition = settings.messageLookups[calleeName(parent)];
+    return keyPosition !== undefined && parent.arguments?.[keyPosition] === node;
+}
+/**
+ * The call that looks a message up when the literal is one of the values it is given, not its key:
+ * `t('editor.preview.frameTitleNamed', { name: widget?.name || 'Widget' })`. A value goes into the sentence, so a word
+ * written there is a word of the sentence that no catalog can say in another language. The search stops at a function (a
+ * string inside a callback is not what the sentence is made of).
+ */
+function lookupGivenTheValue(literal, parents, settings) {
+    let inner = literal;
+    for (let depth = parents.length - 1; depth >= 0; depth -= 1) {
+        const ancestor = parents[depth];
+        if (/Function/.test(ancestor.type))
+            return null;
+        if (ancestor.type === 'CallExpression') {
+            const keyPosition = settings.messageLookups[calleeName(ancestor)];
+            if (keyPosition !== undefined && (ancestor.arguments?.indexOf(inner) ?? -1) > keyPosition)
+                return ancestor;
+        }
+        inner = ancestor;
+    }
+    return null;
+}
+/** The kinds of expression a string passes through on its way out of a function: `return ok ? 'Done' : 'Failed'`. */
+const PASSES_A_STRING_ON = new Set([
+    'ConditionalExpression',
+    'LogicalExpression',
+    'TemplateLiteral',
+    'TSAsExpression',
+    'TSNonNullExpression',
+    'TSSatisfiesExpression'
+]);
+/** The function a string literal is returned from (with the node that holds that function), when the literal is part of what it returns. */
+function functionReturning(literal, parents) {
+    let inner = literal;
+    for (let depth = parents.length - 1; depth >= 0; depth -= 1) {
+        const ancestor = parents[depth];
+        if (PASSES_A_STRING_ON.has(ancestor.type) || (ancestor.type === 'BinaryExpression' && ancestor.operator === '+')) {
+            inner = ancestor;
+            continue;
+        }
+        if (ancestor.type === 'ArrowFunctionExpression' && ancestor.body === inner)
+            return { fn: ancestor, container: parents[depth - 1] };
+        if (ancestor.type !== 'ReturnStatement')
+            return null;
+        for (let up = depth - 1; up >= 0; up -= 1) {
+            if (/Function/.test(parents[up].type))
+                return { fn: parents[up], container: parents[up - 1] };
+        }
+        return null;
+    }
+    return null;
+}
+/** The name a function goes by: its own, or the variable, property or method it is written into. */
+function nameOfFunction(fn, container) {
+    if (fn.id?.name)
+        return fn.id.name;
+    if (container?.type === 'VariableDeclarator' && container.init === fn)
+        return container.id?.name;
+    if ((container?.type === 'Property' || container?.type === 'MethodDefinition' || container?.type === 'PropertyDefinition') && container.value === fn) {
+        return container.key?.name ?? container.key?.value;
+    }
+    return undefined;
+}
+const TOAST_CALL = /^(showToast|toast(\.\w+)?)$/;
+/** The kinds of toast: the first argument of `showToast`, which picks the colour and not a sentence. */
+const TOAST_KINDS = new Set(['success', 'error', 'warning', 'info', 'message', 'loading']);
+function clean(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+function scanScript(file, source, lineShift, program, settings, found) {
+    for (const { node, parents } of walkTree(program)) {
+        const text = literalText(node);
+        if (text === null || !HAS_LETTER.test(text) || isOnlyCompared(parents) || isMessageKey(node, parents, settings) || settings.messageKeys.has(text))
+            continue;
+        const parent = parents[parents.length - 1];
+        const lookup = lookupGivenTheValue(node, parents, settings);
+        let where = lookup ? `${calleeName(lookup)}() value` : '';
+        for (let depth = parents.length - 1; where === '' && depth >= 0; depth -= 1) {
+            const ancestor = parents[depth];
+            if (ancestor.type === 'CallExpression' && TOAST_CALL.test(calleeName(ancestor))) {
+                // `showToast('error', ...)`: the kind of toast is not a sentence (`toast.error('...')` has no kind to give).
+                if (calleeName(ancestor) === 'showToast' && ancestor.arguments?.[0] === node && TOAST_KINDS.has(text))
+                    break;
+                where = `${calleeName(ancestor)}()`;
+                break;
+            }
+            if (ancestor.type === 'Property' && ancestor.key) {
+                // A property that is not one of the text properties (`position`, `id`, `value`, `className` ...) is not a sentence.
+                const propertyName = ancestor.key.name ?? ancestor.key.value;
+                if (settings.textProperties.has(propertyName))
+                    where = `${propertyName}:`;
+                break;
+            }
+            if (ancestor.type === 'VariableDeclarator' && settings.textVariablePattern.test(ancestor.id?.name ?? '')) {
+                where = `${ancestor.id.name} =`;
+                break;
+            }
+            if (ancestor.type === 'AssignmentExpression' && settings.textVariablePattern.test(ancestor.left?.name ?? '')) {
+                where = `${ancestor.left.name} =`;
+                break;
+            }
+            // A statement or a function ends the search: the literal is not what is being shown.
+            if (/Statement$|Function|Declaration$/.test(ancestor.type) && ancestor.type !== 'VariableDeclarator')
+                break;
+        }
+        if (where === '' && settings.textFunctions.size > 0) {
+            // A function the package says returns words: the strings it returns are read by a visitor.
+            const returning = functionReturning(node, parents);
+            const name = returning ? nameOfFunction(returning.fn, returning.container) : undefined;
+            if (name !== undefined && settings.textFunctions.has(name))
+                where = `${name}()`;
+        }
+        if (where === '' || parent?.type === 'ImportDeclaration')
+            continue;
+        found.push({ file, line: lineOf(source, node.start ?? 0) - lineShift, kind: 'script', where, text: clean(text) });
+    }
+}
+function scanTemplate(file, source, lineShift, node, settings, found) {
+    if (!node || typeof node !== 'object')
+        return;
+    if (Array.isArray(node)) {
+        for (const child of node)
+            scanTemplate(file, source, lineShift, child, settings, found);
+        return;
+    }
+    // A <style> or <script> inside the markup holds code, not words.
+    if ((node.type === 'RegularElement' || node.type === 'SvelteElement') && (node.name === 'style' || node.name === 'script'))
+        return;
+    switch (node.type) {
+        case 'Text': {
+            const data = node.data ?? '';
+            if (HAS_LETTER.test(data))
+                found.push({ file, line: lineOf(source, node.start ?? 0) - lineShift, kind: 'text', where: '', text: clean(data) });
+            return;
+        }
+        case 'ExpressionTag':
+        case 'RenderTag':
+        case 'ConstTag':
+        case 'HtmlTag': {
+            // `{@const x = 'words'}` keeps its code in `declaration`, the other tags in `expression`
+            for (const { node: inner, parents } of walkTree(node.expression ?? node.declaration)) {
+                const text = literalText(inner);
+                if (text !== null && HAS_LETTER.test(text) && !isOnlyCompared(parents) && !isMessageKey(inner, parents, settings) && !settings.messageKeys.has(text)) {
+                    found.push({ file, line: lineOf(source, node.start ?? 0) - lineShift, kind: 'expression', where: '{…}', text: clean(text) });
+                }
+            }
+            return;
+        }
+        case 'Attribute': {
+            if (!settings.textAttributes.has(node.name))
+                return;
+            const parts = Array.isArray(node.value) ? node.value : [node.value];
+            for (const part of parts) {
+                if (!part || part === true)
+                    continue;
+                if (part.type === 'Text' && HAS_LETTER.test(part.data)) {
+                    found.push({ file, line: lineOf(source, node.start ?? 0) - lineShift, kind: 'attribute', where: node.name, text: clean(part.data) });
+                }
+                else if (part.type === 'ExpressionTag') {
+                    for (const { node: inner, parents } of walkTree(part.expression)) {
+                        const text = literalText(inner);
+                        if (text !== null && HAS_LETTER.test(text) && !isOnlyCompared(parents) && !isMessageKey(inner, parents, settings) && !settings.messageKeys.has(text)) {
+                            found.push({ file, line: lineOf(source, node.start ?? 0) - lineShift, kind: 'attribute', where: node.name, text: clean(text) });
+                        }
+                    }
+                }
+            }
+            return;
+        }
+        default:
+            break;
+    }
+    for (const key of Object.keys(node)) {
+        if (['type', 'start', 'end', 'metadata', 'name_loc', 'loc', 'parent', 'expression'].includes(key))
+            continue;
+        const value = node[key];
+        if (value && typeof value === 'object')
+            scanTemplate(file, source, lineShift, value, settings, found);
+    }
+}
+/**
+ * The visible English in one file: a Svelte file (its markup and its scripts) or a `.ts` file (its code, as a script).
+ * Lines are the lines of the file.
+ */
+export function findVisibleText(file, source, options = {}) {
+    const settings = settingsOf(options);
+    const found = [];
+    const { tree, text, lineShift } = parseFile(file, source);
+    scanTemplate(file, text, lineShift, tree.fragment, settings, found);
+    if (tree.instance?.content)
+        scanScript(file, text, lineShift, tree.instance.content, settings, found);
+    if (tree.module?.content)
+        scanScript(file, text, lineShift, tree.module.content, settings, found);
+    return found;
+}

package/dist/i18n/createI18n.d.ts

@@ -0,0 +1,63 @@
+import { type Readable } from 'svelte/store';
+import { type MessageOverrides, type MessageValues } from './translator.ts';
+/** The function a screen calls to get its words: `t('upload.clear')`, `t('toast.deleted', { name })`. */
+export type Translate<Key extends string = string> = (key: Key, values?: MessageValues) => string;
+/**
+ * What the parts of a package need to speak the page's language, shared with them through Svelte's component context.
+ *
+ * Both are stores, so a screen that is already open changes its words when the page sets the language again.
+ */
+export interface I18nContext<Key extends string = string> {
+    /** Turns a key into text. */
+    t: Readable<Translate<Key>>;
+    /** The language tag in use ("en" unless the page asked for another one that this browser knows). */
+    locale: Readable<string>;
+}
+/** What the page chose. Both are optional; a missing language is English. */
+export interface I18nSettings {
+    /** A BCP 47 tag ("de", "pt-BR"): sets the plural rules and how numbers, dates and lists are written. */
+    locale?: string | null;
+    /** The page's own words: any of the catalog's keys. A key it leaves out keeps the English text. */
+    messages?: MessageOverrides | null;
+}
+/** What {@link I18n.provideI18n} gives back to the component that called it. */
+export interface I18nHandle<Key extends string = string> extends I18nContext<Key> {
+    /** Changes the language the parts below speak. Cheap to call on every change of the props. */
+    update(settings: I18nSettings): void;
+}
+/**
+ * The two functions of Svelte that the context is made of. They only work while a component is being created, so a test
+ * hands in stand-ins; the packages use the real ones by leaving this out.
+ */
+export interface SvelteContextApi {
+    getContext<Value>(key: unknown): Value | undefined;
+    setContext<Value>(key: unknown, value: Value): Value;
+}
+export interface I18nOptions<Key extends string> {
+    /** The English messages of the package: every key its screens ask for. */
+    catalog: Readonly<Record<Key, string>>;
+    /** The package's name in the console: `FileBrowser` makes `[FileBrowser] There is no message called "x".` */
+    label: string;
+    /** Stand-ins for Svelte's `getContext` and `setContext`; tests only. */
+    contextApi?: SvelteContextApi;
+}
+/** What {@link createI18n} makes: the three things a package's code uses. */
+export interface I18n<Key extends string = string> {
+    /**
+     * Called by the root component of a package while it is created, so everything inside it speaks the page's language.
+     * The context belongs to one root component, so two of them on a page can speak two languages.
+     */
+    provideI18n(initial: I18nSettings): I18nHandle<Key>;
+    /** Called by a part of the package while it is created. Never throws; outside a root component it speaks English. */
+    useI18n(): I18nContext<Key>;
+    /** The English `t`, for code that has no component around it (a helper called without a translator). */
+    translateEnglish: Translate<Key>;
+}
+/**
+ * Makes the words of one package: the context its root component provides, the hook its parts use, and the English
+ * translator for code with no component around it.
+ *
+ * Every package makes its own (its catalog, its console label, its own context key), so the File Browser inside the
+ * editor and the editor around it can each have their own words, and each is told only about its own messages.
+ */
+export declare function createI18n<Key extends string>(options: I18nOptions<Key>): I18n<Key>;