@zerolith/i18n 0.0.0-stage → 0.1.0-alpha.10

package/src/compile.ts

@@ -0,0 +1,1066 @@
+/**
+ * The message compiler: MessageFormat 2 catalogs in, one module per locale
+ * out, with a plain function per message whose arguments are typed from
+ * the placeholders. Formatting and plural selection call `Intl` in the
+ * generated module, so no message runtime is shipped. The subset
+ * implemented is the one catalogs use: text and placeholders, quoted and
+ * unquoted literals, `.input` and `.local` declarations, `.match` with
+ * numeric and string selectors, and the default functions `:string`,
+ * `:number`, `:integer`, `:percent`, `:currency`, `:offset`, `:date`,
+ * `:time`, and `:datetime`. Markup is accepted and formats to nothing.
+ */
+
+/** A catalog: message key to MessageFormat 2 source. */
+export type Catalog = Readonly<Record<string, string>>;
+
+/** Options for `compileMessages`. */
+export interface CompileOptions
+{
+    /** `ts` emits TypeScript (the default); `js` emits JavaScript with JSDoc types for buildless projects. */
+    language?: "ts" | "js";
+    /** Named in the generated header. */
+    source?: string;
+}
+
+/** The result of compiling one catalog. */
+export interface CompiledCatalog
+{
+    /** The generated module's source, TypeScript or JavaScript as the `language` option chose; the `zerolith-i18n` CLI writes it to `<locale>.ts` or `<locale>.js`. */
+    code: string;
+    /** The message keys as function names, in source order. */
+    names: string[];
+}
+
+type ArgumentType = "number" | "date" | "string";
+
+interface Literal
+{
+    kind: "literal";
+    value: string;
+}
+
+interface Variable
+{
+    kind: "variable";
+    name: string;
+}
+
+interface Expression
+{
+    operand: Literal | Variable | undefined;
+    fn: string | undefined;
+    options: Record<string, Literal | Variable>;
+}
+
+type Part = string | Expression;
+
+interface Variant
+{
+    keys: string[];
+    pattern: Part[];
+}
+
+interface Message
+{
+    declarations: Map<string, { expression: Expression; local: boolean }>;
+    pattern: Part[] | undefined;
+    selectors: Expression[];
+    variants: Variant[];
+}
+
+class Parser
+{
+    private index = 0;
+    private readonly text: string;
+    private readonly key: string;
+
+    constructor(text: string, key: string)
+    {
+        this.text = text;
+        this.key = key;
+    }
+
+    private fail(message: string): never
+    {
+        throw new Error(`zerolith/i18n: message "${this.key}": ${message} at offset ${this.index}`);
+    }
+
+    private peek(offset = 0): string
+    {
+        return this.text.charAt(this.index + offset);
+    }
+
+    private skipSpace(): void
+    {
+        while (/[ \t\r\n　]/.test(this.peek()))
+        {
+            this.index++;
+        }
+    }
+
+    private expect(token: string): void
+    {
+        if (!this.text.startsWith(token, this.index))
+        {
+            this.fail(`expected ${JSON.stringify(token)}`);
+        }
+        this.index += token.length;
+    }
+
+    private name(): string
+    {
+        const match = /^[A-Za-z_][A-Za-z0-9_.-]*/.exec(this.text.slice(this.index));
+        if (match === null)
+        {
+            this.fail("expected a name");
+        }
+        this.index += match[0].length;
+        return match[0];
+    }
+
+    private literal(): Literal
+    {
+        if (this.peek() === "|")
+        {
+            this.index++;
+            let value = "";
+            while (this.index < this.text.length && this.peek() !== "|")
+            {
+                if (this.peek() === "\\")
+                {
+                    value += this.peek(1);
+                    this.index += 2;
+                }
+                else
+                {
+                    value += this.peek();
+                    this.index++;
+                }
+            }
+            this.expect("|");
+            return { kind: "literal", value };
+        }
+        const match = /^[A-Za-z0-9_.+:@%-]+/.exec(this.text.slice(this.index));
+        if (match === null)
+        {
+            this.fail("expected a literal");
+        }
+        this.index += match[0].length;
+        return { kind: "literal", value: match[0] };
+    }
+
+    private variable(): Variable
+    {
+        this.expect("$");
+        return { kind: "variable", name: this.name() };
+    }
+
+    /** Parses the inside of `{ ... }` after the opening brace. */
+    private expression(): Expression | undefined
+    {
+        this.skipSpace();
+        if (this.peek() === "#" || this.peek() === "/")
+        {
+            while (this.index < this.text.length && this.peek() !== "}")
+            {
+                this.index++;
+            }
+            this.expect("}");
+            return undefined;
+        }
+        let operand: Literal | Variable | undefined;
+        if (this.peek() === "$")
+        {
+            operand = this.variable();
+        }
+        else if (this.peek() !== ":")
+        {
+            operand = this.literal();
+        }
+        this.skipSpace();
+        let fn: string | undefined;
+        const options: Record<string, Literal | Variable> = {};
+        if (this.peek() === ":")
+        {
+            this.index++;
+            fn = this.name();
+            this.skipSpace();
+            while (this.peek() !== "}" && this.peek() !== "@" && this.index < this.text.length)
+            {
+                const option = this.name();
+                this.skipSpace();
+                this.expect("=");
+                this.skipSpace();
+                options[option] = this.peek() === "$" ? this.variable() : this.literal();
+                this.skipSpace();
+            }
+        }
+        while (this.peek() === "@")
+        {
+            this.index++;
+            this.name();
+            this.skipSpace();
+            if (this.peek() === "=")
+            {
+                this.index++;
+                this.skipSpace();
+                if (this.peek() === "$")
+                {
+                    this.variable();
+                }
+                else
+                {
+                    this.literal();
+                }
+                this.skipSpace();
+            }
+        }
+        this.expect("}");
+        if (operand === undefined && fn === undefined)
+        {
+            this.fail("an expression needs an operand or a function");
+        }
+        return { operand, fn, options };
+    }
+
+    /** Parses pattern text up to `end` (`}}` for quoted patterns, the end of input for simple ones). */
+    private pattern(quoted: boolean): Part[]
+    {
+        const parts: Part[] = [];
+        let text = "";
+        while (this.index < this.text.length)
+        {
+            const char = this.peek();
+            if (quoted && char === "}" && this.peek(1) === "}")
+            {
+                break;
+            }
+            if (char === "\\")
+            {
+                const next = this.peek(1);
+                if (next !== "{" && next !== "}" && next !== "\\" && next !== "|")
+                {
+                    this.fail("only \\{ \\} \\\\ and \\| can be escaped");
+                }
+                text += next;
+                this.index += 2;
+            }
+            else if (char === "{")
+            {
+                if (text !== "")
+                {
+                    parts.push(text);
+                    text = "";
+                }
+                this.index++;
+                const expression = this.expression();
+                if (expression !== undefined)
+                {
+                    parts.push(expression);
+                }
+            }
+            else if (char === "}")
+            {
+                this.fail("a lone } must be escaped as \\}");
+            }
+            else
+            {
+                text += char;
+                this.index++;
+            }
+        }
+        if (text !== "")
+        {
+            parts.push(text);
+        }
+        return parts;
+    }
+
+    private quotedPattern(): Part[]
+    {
+        this.expect("{{");
+        const parts = this.pattern(true);
+        this.expect("}}");
+        return parts;
+    }
+
+    parse(): Message
+    {
+        const message: Message = { declarations: new Map(), pattern: undefined, selectors: [], variants: [] };
+        const trimmed = this.text.trimStart();
+        if (!trimmed.startsWith(".") && !trimmed.startsWith("{{"))
+        {
+            message.pattern = this.pattern(false);
+            return message;
+        }
+        this.skipSpace();
+        while (this.text.startsWith(".input", this.index) || this.text.startsWith(".local", this.index))
+        {
+            const local = this.text.startsWith(".local", this.index);
+            this.index += 6;
+            this.skipSpace();
+            let name: string;
+            if (local)
+            {
+                name = this.variable().name;
+                this.skipSpace();
+                this.expect("=");
+                this.skipSpace();
+            }
+            else
+            {
+                name = "";
+            }
+            this.expect("{");
+            const expression = this.expression();
+            if (expression === undefined)
+            {
+                this.fail("a declaration cannot be markup");
+            }
+            if (!local)
+            {
+                if (expression.operand?.kind !== "variable")
+                {
+                    this.fail(".input needs a variable operand");
+                }
+                name = expression.operand.name;
+            }
+            if (message.declarations.has(name))
+            {
+                this.fail(`$${name} is declared twice`);
+            }
+            message.declarations.set(name, { expression, local });
+            this.skipSpace();
+        }
+        if (this.text.startsWith(".match", this.index))
+        {
+            this.index += 6;
+            this.skipSpace();
+            while (this.peek() === "$" || this.peek() === "{")
+            {
+                if (this.peek() === "{")
+                {
+                    this.index++;
+                    const expression = this.expression();
+                    if (expression === undefined)
+                    {
+                        this.fail("a selector cannot be markup");
+                    }
+                    message.selectors.push(expression);
+                }
+                else
+                {
+                    message.selectors.push({ operand: this.variable(), fn: undefined, options: {} });
+                }
+                this.skipSpace();
+            }
+            if (message.selectors.length === 0)
+            {
+                this.fail(".match needs at least one selector");
+            }
+            while (this.index < this.text.length)
+            {
+                const keys: string[] = [];
+                while (this.peek() !== "{")
+                {
+                    if (this.peek() === "*")
+                    {
+                        this.index++;
+                        keys.push("*");
+                    }
+                    else
+                    {
+                        keys.push(this.literal().value);
+                    }
+                    this.skipSpace();
+                }
+                if (keys.length !== message.selectors.length)
+                {
+                    this.fail(`a variant needs ${message.selectors.length} key(s), found ${keys.length}`);
+                }
+                message.variants.push({ keys, pattern: this.quotedPattern() });
+                this.skipSpace();
+            }
+            if (!message.variants.some((variant) => variant.keys.every((key) => key === "*")))
+            {
+                this.fail("a matcher needs a variant whose keys are all *");
+            }
+            return message;
+        }
+        message.pattern = this.quotedPattern();
+        this.skipSpace();
+        if (this.index < this.text.length)
+        {
+            this.fail("unexpected text after the pattern");
+        }
+        return message;
+    }
+}
+
+const NUMBER_FUNCTIONS = new Set(["number", "integer", "percent", "currency", "offset"]);
+const DATE_FUNCTIONS = new Set(["date", "time", "datetime"]);
+const NUMBER_OPTIONS: Record<string, string> = {
+    minimumFractionDigits: "minimumFractionDigits",
+    maximumFractionDigits: "maximumFractionDigits",
+    minimumIntegerDigits: "minimumIntegerDigits",
+    minimumSignificantDigits: "minimumSignificantDigits",
+    maximumSignificantDigits: "maximumSignificantDigits",
+    signDisplay: "signDisplay",
+    trailingZeroDisplay: "trailingZeroDisplay",
+    roundingMode: "roundingMode",
+    roundingIncrement: "roundingIncrement",
+    roundingPriority: "roundingPriority",
+    currencyDisplay: "currencyDisplay",
+    currencySign: "currencySign",
+    numberingSystem: "numberingSystem"
+};
+
+/** Names a module cannot bind; a message named so is exported under its name from a binding of its own. */
+const RESERVED: ReadonlySet<string> = new Set(["arguments", "await", "break", "case", "catch", "class", "const", "continue", "debugger", "default", "delete", "do", "else", "enum", "eval", "export", "extends", "false", "finally", "for", "function", "if", "implements", "import", "in", "instanceof", "interface", "let", "new", "null", "package", "private", "protected", "public", "return", "static", "super", "switch", "this", "throw", "true", "try", "typeof", "var", "void", "while", "with", "yield"]);
+
+/** Characters an HTML parser reads inside an inline script, and the line separators older engines refused in string literals. */
+const SCRIPT_UNSAFE = new RegExp(`[<>${String.fromCodePoint(0x2028, 0x2029)}]`, "g");
+
+/** The line breaks of a message's source, each starting a new line of its doc comment. */
+const SOURCE_LINES = /\r\n|[\n\r\u2028\u2029]/;
+
+/**
+ * A value written as JavaScript source: its JSON, with `<`, `>`, U+2028, and
+ * U+2029 escaped, so generated code stays inert even when a page inlines
+ * it in a script element.
+ */
+function jsLiteral(value: unknown): string
+{
+    return JSON.stringify(value).replace(SCRIPT_UNSAFE, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+
+/** Text for a `//` comment, kept on one line and with `<` written as `&lt;`, so it can end neither the comment nor an inline script. */
+function commentText(text: string): string
+{
+    return text.split(SOURCE_LINES).join(" ").replaceAll("<", "&lt;");
+}
+
+/** An argument or local name JavaScript can write as it is; MessageFormat also allows `-` and `.`, as in `$first-name`. */
+const PLAIN_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** A property name as code: as it is when plain, quoted otherwise. */
+function property(name: string): string
+{
+    return PLAIN_NAME.test(name) ? name : jsLiteral(name);
+}
+
+function identifier(key: string): string
+{
+    const words = key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).filter((word) => word !== "");
+    const name = words.map((word, index) => (index === 0 ? word.charAt(0).toLowerCase() + word.slice(1) : word.charAt(0).toUpperCase() + word.slice(1))).join("");
+    return /^[0-9]/.test(name) ? `_${name}` : name === "" ? "_" : name;
+}
+
+class Emitter
+{
+    readonly arguments: Map<string, ArgumentType> = new Map();
+    readonly locals: Map<string, string> = new Map();
+    readonly prelude: string[] = [];
+    private readonly key: string;
+    private readonly message: Message;
+    private readonly formatters: Map<string, string>;
+    private readonly used: Set<Helper>;
+    private reads = 0;
+
+    constructor(key: string, message: Message, formatters: Map<string, string>, used: Set<Helper>)
+    {
+        this.key = key;
+        this.message = message;
+        this.formatters = formatters;
+        this.used = used;
+    }
+
+    /** The module-level binding of a formatter whose options are known at compile time, created on first use and shared by every message that creates it the same way. */
+    private shared(create: string): string
+    {
+        this.used.add("once");
+        let binding = this.formatters.get(create);
+        if (binding === undefined)
+        {
+            binding = `$f${this.formatters.size}`;
+            this.formatters.set(create, binding);
+        }
+        return binding;
+    }
+
+    private fail(text: string): never
+    {
+        throw new Error(`zerolith/i18n: message "${this.key}": ${text}`);
+    }
+
+    private argument(name: string, type: ArgumentType): string
+    {
+        this.reads++;
+        const local = this.locals.get(name);
+        if (local !== undefined)
+        {
+            return local;
+        }
+        const existing = this.arguments.get(name);
+        if (existing === undefined || existing === "string")
+        {
+            this.arguments.set(name, type);
+        }
+        else if (existing !== type && type !== "string")
+        {
+            this.fail(`$${name} is used both as ${existing} and as ${type}`);
+        }
+        return PLAIN_NAME.test(name) ? `args.${name}` : `args[${jsLiteral(name)}]`;
+    }
+
+    private optionValue(value: Literal | Variable | undefined): string | undefined
+    {
+        if (value === undefined)
+        {
+            return undefined;
+        }
+        return value.kind === "literal" ? jsLiteral(value.value) : `String(${this.argument(value.name, "string")})`;
+    }
+
+    private numberOptions(expression: Expression): string
+    {
+        const entries: string[] = [];
+        const fn = expression.fn ?? "number";
+        if (fn === "integer")
+        {
+            entries.push("maximumFractionDigits: 0");
+        }
+        else if (fn === "percent")
+        {
+            entries.push("style: \"percent\"");
+        }
+        else if (fn === "currency")
+        {
+            const currency = this.optionValue(expression.options["currency"]);
+            if (currency === undefined)
+            {
+                this.fail(":currency needs a currency option");
+            }
+            entries.push("style: \"currency\"", `currency: ${currency}`);
+        }
+        for (const [option, value] of Object.entries(expression.options))
+        {
+            const mapped = NUMBER_OPTIONS[option];
+            if (mapped !== undefined)
+            {
+                const literal = value.kind === "literal" ? value.value : undefined;
+                const numeric = literal !== undefined && /^[0-9]+$/.test(literal) ? literal : undefined;
+                entries.push(`${mapped}: ${numeric ?? this.optionValue(value) ?? "undefined"}`);
+            }
+            else if (option === "useGrouping" && value.kind === "literal")
+            {
+                entries.push(`useGrouping: ${value.value === "never" ? "false" : value.value === "always" ? "true" : jsLiteral(value.value)}`);
+            }
+            else if (option === "fractionDigits" && value.kind === "literal" && /^[0-9]+$/.test(value.value))
+            {
+                entries.push(`minimumFractionDigits: ${value.value}`, `maximumFractionDigits: ${value.value}`);
+            }
+        }
+        return entries.length === 0 ? "{}" : `{ ${entries.join(", ")} }`;
+    }
+
+    private dateOptions(expression: Expression): string
+    {
+        const entries: string[] = [];
+        const fn = expression.fn ?? "date";
+        const literal = (name: string): string | undefined =>
+        {
+            const value = expression.options[name];
+            return value?.kind === "literal" ? value.value : undefined;
+        };
+        const length = literal(fn === "datetime" ? "dateLength" : "length") ?? (fn === "time" ? undefined : "medium");
+        if (length !== undefined && fn !== "time")
+        {
+            entries.push(`dateStyle: ${jsLiteral(length)}`);
+        }
+        const precision = literal(fn === "datetime" ? "timePrecision" : "precision") ?? (fn === "date" ? undefined : "minute");
+        if (precision !== undefined && fn !== "date")
+        {
+            entries.push(`timeStyle: ${jsLiteral(precision === "second" ? "medium" : "short")}`);
+        }
+        const zone = literal("timeZone");
+        if (zone !== undefined && zone !== "input")
+        {
+            entries.push(`timeZone: ${jsLiteral(zone)}`);
+        }
+        const hour12 = literal("hour12");
+        if (hour12 !== undefined)
+        {
+            entries.push(`hour12: ${hour12 === "true"}`);
+        }
+        const style = literal("timeZoneStyle");
+        if (style !== undefined)
+        {
+            entries.push(`timeZoneName: ${jsLiteral(style)}`);
+        }
+        return entries.length === 0 ? "{}" : `{ ${entries.join(", ")} }`;
+    }
+
+    /** The JavaScript for an expression's numeric value, before formatting. */
+    private numeric(expression: Expression): string
+    {
+        const operand = expression.operand;
+        let value: string;
+        if (operand === undefined)
+        {
+            this.fail(`:${expression.fn ?? ""} needs an operand`);
+        }
+        else if (operand.kind === "literal")
+        {
+            value = Number.isFinite(Number(operand.value)) ? String(Number(operand.value)) : this.fail(`${JSON.stringify(operand.value)} is not a number`);
+        }
+        else
+        {
+            value = this.argument(operand.name, "number");
+        }
+        if (expression.fn === "offset")
+        {
+            const add = this.optionValue(expression.options["add"]);
+            const subtract = this.optionValue(expression.options["subtract"]);
+            if ((add === undefined) === (subtract === undefined))
+            {
+                this.fail(":offset needs exactly one of add or subtract");
+            }
+            value = `(${value} ${add === undefined ? "-" : "+"} Number(${add ?? subtract ?? "0"}))`;
+        }
+        return value;
+    }
+
+    /** Resolves a plain `{$x}` to its `.input` declaration when one exists, or with `locals` to its `.local` one too, so a selector on a local selects as its expression does. */
+    private resolve(expression: Expression, locals = false): Expression
+    {
+        if (expression.fn === undefined && expression.operand?.kind === "variable")
+        {
+            const declared = this.message.declarations.get(expression.operand.name);
+            if (declared !== undefined && (locals || !declared.local))
+            {
+                return declared.expression;
+            }
+        }
+        return expression;
+    }
+
+    /** The JavaScript producing the formatted string of an expression. */
+    format(raw: Expression): string
+    {
+        const expression = this.resolve(raw);
+        const fn = expression.fn;
+        if (fn === undefined || fn === "string")
+        {
+            const operand = expression.operand;
+            if (operand === undefined)
+            {
+                this.fail(":string needs an operand");
+            }
+            return operand.kind === "literal" ? jsLiteral(operand.value) : `String(${this.argument(operand.name, "string")})`;
+        }
+        if (NUMBER_FUNCTIONS.has(fn))
+        {
+            const value = this.numeric(expression);
+            const reads = this.reads;
+            const options = this.numberOptions(expression);
+            if (this.reads === reads)
+            {
+                return `${this.shared(`new Intl.NumberFormat(locale, ${options})`)}().format(${value})`;
+            }
+            this.used.add("number");
+            return `$number(${value}, ${options})`;
+        }
+        if (DATE_FUNCTIONS.has(fn))
+        {
+            const operand = expression.operand;
+            if (operand === undefined)
+            {
+                this.fail(`:${fn} needs an operand`);
+            }
+            const value = operand.kind === "literal" ? `new Date(${jsLiteral(operand.value)})` : this.argument(operand.name, "date");
+            return `${this.shared(`new Intl.DateTimeFormat(locale, ${this.dateOptions(expression)})`)}().format(${value})`;
+        }
+        this.fail(`unknown function :${fn}`);
+    }
+
+    /** The JavaScript for a selector: its comparable value and the categories it matches. */
+    selector(raw: Expression): string
+    {
+        const expression = this.resolve(raw, true);
+        const fn = expression.fn ?? "string";
+        if (NUMBER_FUNCTIONS.has(fn))
+        {
+            const select = expression.options["select"];
+            const mode = select?.kind === "literal" ? select.value : "plural";
+            const value = fn === "percent" ? `(${this.numeric(expression)}) * 100` : this.numeric(expression);
+            if (mode === "exact")
+            {
+                return `{ value: String(${value}), categories: [] }`;
+            }
+            const type = jsLiteral(mode === "ordinal" ? "ordinal" : "cardinal");
+            const reads = this.reads;
+            const options = this.numberOptions(expression);
+            if (this.reads === reads)
+            {
+                return `{ value: String(${value}), categories: [${this.shared(`new Intl.PluralRules(locale, { ...new Intl.NumberFormat(locale, ${options}).resolvedOptions(), type: ${type} })`)}().select(${value})] }`;
+            }
+            this.used.add("plural");
+            return `{ value: String(${value}), categories: [$plural(${value}, ${type}, ${options})] }`;
+        }
+        if (fn === "string")
+        {
+            const operand = expression.operand;
+            if (operand === undefined)
+            {
+                this.fail("a selector needs an operand");
+            }
+            const value = operand.kind === "literal" ? jsLiteral(operand.value) : `String(${this.argument(operand.name, "string")})`;
+            return `{ value: ${value}, categories: [] }`;
+        }
+        this.fail(`:${fn} cannot select`);
+    }
+
+    pattern(parts: Part[]): string
+    {
+        if (parts.length === 0)
+        {
+            return "\"\"";
+        }
+        return parts.map((part) => (typeof part === "string" ? jsLiteral(part) : this.format(part))).join(" + ");
+    }
+
+    body(): string
+    {
+        for (const [name, declaration] of this.message.declarations)
+        {
+            if (declaration.local)
+            {
+                const value = this.format(declaration.expression);
+                const binding = PLAIN_NAME.test(name) ? `local_${name}` : `local_${this.locals.size}`;
+                this.locals.set(name, binding);
+                this.prelude.push(`const ${binding} = ${value};`);
+            }
+        }
+        if (this.message.pattern !== undefined)
+        {
+            return this.pattern(this.message.pattern);
+        }
+        const selectors = this.message.selectors.map((selector) => this.selector(selector));
+        const variants = this.message.variants.map((variant) => `{ keys: ${jsLiteral(variant.keys)}, pattern: () => ${this.pattern(variant.pattern)} }`);
+        this.used.add("select");
+        return `$select([${selectors.join(", ")}], [${variants.join(", ")}])`;
+    }
+}
+
+/** A group of helpers a compiled module shares; each is written only when one of the module's messages uses it. */
+type Helper = "cache" | "once" | "number" | "plural" | "select";
+
+/** The helpers in JavaScript and in TypeScript, in the order a module writes them. */
+const HELPERS: Record<Helper, { js: string; ts: string }> = {
+    cache: {
+        js: `const $formats = new Map();
+function $cached(kind, options, create)
+{
+    const key = kind + JSON.stringify(options);
+    let instance = $formats.get(key);
+    if (instance === undefined)
+    {
+        instance = create();
+        $formats.set(key, instance);
+    }
+    return instance;
+}`,
+        ts: `const $formats: Map<string, unknown> = new Map();
+function $cached<T>(kind: string, options: object, create: () => T): T
+{
+    const key = kind + JSON.stringify(options);
+    let instance = $formats.get(key) as T | undefined;
+    if (instance === undefined)
+    {
+        instance = create();
+        $formats.set(key, instance);
+    }
+    return instance;
+}`
+    },
+    once: {
+        js: `function $once(create)
+{
+    let instance;
+    return () => (instance ??= create());
+}`,
+        ts: `function $once<T>(create: () => T): () => T
+{
+    let instance: T | undefined;
+    return () => (instance ??= create());
+}`
+    },
+    number: {
+        js: `function $number(value, options)
+{
+    return $cached("n", options, () => new Intl.NumberFormat(locale, options)).format(value);
+}`,
+        ts: `function $number(value: number, options: Intl.NumberFormatOptions): string
+{
+    return $cached("n", options, () => new Intl.NumberFormat(locale, options)).format(value);
+}`
+    },
+    plural: {
+        js: `function $plural(value, type, options)
+{
+    return $cached("p" + type, options, () => new Intl.PluralRules(locale, { ...$cached("n", options, () => new Intl.NumberFormat(locale, options)).resolvedOptions(), type })).select(value);
+}`,
+        ts: `function $plural(value: number, type: "cardinal" | "ordinal", options: Intl.NumberFormatOptions): string
+{
+    return $cached("p" + type, options, () => new Intl.PluralRules(locale, { ...$cached("n", options, () => new Intl.NumberFormat(locale, options)).resolvedOptions(), type })).select(value);
+}`
+    },
+    select: {
+        js: `function $select(selectors, variants)
+{
+    let best;
+    let bestRank;
+    for (const variant of variants)
+    {
+        const rank = [];
+        let matches = true;
+        for (const [index, key] of variant.keys.entries())
+        {
+            const selector = selectors[index];
+            if (key === "*")
+            {
+                rank.push(0);
+            }
+            else if (key === selector.value)
+            {
+                rank.push(2);
+            }
+            else if (selector.categories.includes(key))
+            {
+                rank.push(1);
+            }
+            else
+            {
+                matches = false;
+                break;
+            }
+        }
+        if (!matches)
+        {
+            continue;
+        }
+        if (matches && $better(rank, bestRank))
+        {
+            best = variant;
+            bestRank = rank;
+        }
+    }
+    return best === undefined ? "" : best.pattern();
+}
+function $better(rank, current)
+{
+    if (current === undefined)
+    {
+        return true;
+    }
+    for (const [index, score] of rank.entries())
+    {
+        const other = current[index] ?? 0;
+        if (score !== other)
+        {
+            return score > other;
+        }
+    }
+    return false;
+}`,
+        ts: `interface Selector
+{
+    value: string;
+    categories: string[];
+}
+interface Variant
+{
+    keys: string[];
+    pattern: () => string;
+}
+function $better(rank: number[], current: number[] | undefined): boolean
+{
+    if (current === undefined)
+    {
+        return true;
+    }
+    for (const [index, score] of rank.entries())
+    {
+        const other = current[index] ?? 0;
+        if (score !== other)
+        {
+            return score > other;
+        }
+    }
+    return false;
+}
+function $select(selectors: Selector[], variants: Variant[]): string
+{
+    let best: Variant | undefined;
+    let bestRank: number[] | undefined;
+    for (const variant of variants)
+    {
+        const rank: number[] = [];
+        let matches = true;
+        for (const [index, key] of variant.keys.entries())
+        {
+            const selector = selectors[index];
+            if (key === "*")
+            {
+                rank.push(0);
+            }
+            else if (selector !== undefined && key === selector.value)
+            {
+                rank.push(2);
+            }
+            else if (selector !== undefined && selector.categories.includes(key))
+            {
+                rank.push(1);
+            }
+            else
+            {
+                matches = false;
+                break;
+            }
+        }
+        if (matches && $better(rank, bestRank))
+        {
+            best = variant;
+            bestRank = rank;
+        }
+    }
+    return best === undefined ? "" : best.pattern();
+}`
+    }
+};
+
+/** The helpers a module's messages use, with the cache that `$number` and `$plural` share. */
+function helpersFor(used: ReadonlySet<Helper>, javascript: boolean): string
+{
+    const needed = new Set(used);
+    if (needed.has("number") || needed.has("plural"))
+    {
+        needed.add("cache");
+    }
+    return (Object.keys(HELPERS) as Helper[]).filter((name) => needed.has(name)).map((name) => HELPERS[name][javascript ? "js" : "ts"]).join("\n");
+}
+
+function typeOf(type: ArgumentType): string
+{
+    return type === "number" ? "number" : type === "date" ? "Date | number" : "string | number";
+}
+
+/**
+ * Compiles one locale's catalog into a module: `locale`, one exported
+ * function per message named from its key, and the `Intl` helpers they
+ * share. Each function takes an `args` object typed from the message's
+ * placeholders, or nothing when the message has none. A formatter whose
+ * options are all literals is a module-level binding created on first use
+ * and shared by every message that formats the same way; options that read
+ * an argument find their formatter in a cache keyed by the options. Only
+ * the helpers the messages use are written.
+ */
+export function compileMessages(locale: string, catalog: Catalog, options: CompileOptions = {}): CompiledCatalog
+{
+    const javascript = options.language === "js";
+    const out: string[] = [];
+    out.push(`// Generated by @zerolith/i18n from ${commentText(options.source ?? `the ${locale} catalog`)}. Do not edit; regenerate instead.`);
+    if (javascript)
+    {
+        out.push("// @ts-check");
+    }
+    out.push(`export const locale${javascript ? "" : ": string"} = ${jsLiteral(locale)};`);
+    out.push("");
+    const head = out.length;
+    const formatters = new Map<string, string>();
+    const used = new Set<Helper>();
+    const names: string[] = [];
+    const seen = new Set<string>();
+    for (const [key, source] of Object.entries(catalog))
+    {
+        const name = identifier(key);
+        if (seen.has(name))
+        {
+            throw new Error(`zerolith/i18n: keys "${key}" and another one both become ${name}`);
+        }
+        if (name === "locale")
+        {
+            throw new Error(`zerolith/i18n: key "${key}" becomes locale, which every compiled module exports; rename the key`);
+        }
+        const binding = RESERVED.has(name) ? `message_${name}` : name;
+        seen.add(name);
+        names.push(name);
+        const message = new Parser(source, key).parse();
+        const emitter = new Emitter(key, message, formatters, used);
+        const body = emitter.body();
+        const args = [...emitter.arguments.entries()].toSorted(([a], [b]) => a.localeCompare(b));
+        const doc = source.replace(/\*\//g, "* /").replaceAll("<", "&lt;").split(SOURCE_LINES).map((line) => ` * ${line}`.trimEnd()).join("\n");
+        const argumentType = `{ ${args.map(([argument, type]) => `${property(argument)}: ${typeOf(type)}`).join("; ")} }`;
+        if (javascript)
+        {
+            out.push(`/**\n${doc}${args.length > 0 ? `\n * @param {${argumentType}} args` : ""}\n * @returns {string}\n */`);
+            out.push(`${binding === name ? "export " : ""}function ${binding}(${args.length > 0 ? "args" : ""})`);
+        }
+        else
+        {
+            out.push(`/**\n${doc}\n */`);
+            out.push(`${binding === name ? "export " : ""}function ${binding}(${args.length > 0 ? `args: ${argumentType}` : ""}): string`);
+        }
+        out.push("{");
+        for (const line of emitter.prelude)
+        {
+            out.push(`    ${line}`);
+        }
+        out.push(`    return ${body};`);
+        out.push("}");
+        if (binding !== name)
+        {
+            out.push(`export { ${binding} as ${name} };`);
+        }
+        out.push("");
+    }
+    const helpers = helpersFor(used, javascript);
+    const shared = Array.from(formatters, ([create, binding]) => `const ${binding} = $once(() => ${create});`);
+    out.splice(head, 0, ...(helpers === "" ? [] : [helpers, ""]), ...(shared.length === 0 ? [] : [...shared, ""]));
+    return { code: out.join("\n"), names };
+}
+
+/** The keys of a catalog as function names, for comparing locales. */
+export function messageNames(catalog: Catalog): string[]
+{
+    return Object.keys(catalog).map(identifier);
+}
+
+/**
+ * The index module for a set of locales: the list of locales and one lazy
+ * loader per locale, so each locale is its own chunk.
+ */
+export function compileIndex(locales: readonly string[], options: CompileOptions = {}): string
+{
+    const javascript = options.language === "js";
+    const extension = javascript ? "js" : "ts";
+    const lines = [`// Generated by @zerolith/i18n. Do not edit; regenerate instead.`];
+    if (javascript)
+    {
+        lines.push("// @ts-check");
+    }
+    if (!javascript)
+    {
+        lines.push(`import type * as first from ${jsLiteral(`./${locales[0] ?? "en"}.${extension}`)};`);
+        lines.push("");
+    }
+    lines.push(`export const locales${javascript ? "" : ": readonly string[]"} = ${jsLiteral(locales)};`);
+    lines.push("");
+    lines.push(`/** Loads one locale's messages; each locale is its own module. */`);
+    lines.push(javascript ? "export const loaders = {" : "export const loaders: Readonly<Record<string, () => Promise<typeof first>>> = {");
+    lines.push(locales.map((locale) => `    ${jsLiteral(locale)}: () => import(${jsLiteral(`./${locale}.${extension}`)})`).join(",\n"));
+    lines.push("};");
+    lines.push("");
+    return lines.join("\n");
+}