@zerolith/i18n 0.1.0-alpha.5 → 0.1.0-alpha.6

package/src/compile.ts

@@ -25,6 +25,7 @@ export interface CompileOptions
 /** 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[];
@@ -414,6 +415,18 @@ const NUMBER_OPTIONS: Record<string, string> = {
     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"]);
+
+/** 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 : JSON.stringify(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 !== "");
@@ -428,11 +441,29 @@ class Emitter
     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)
+    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
@@ -442,6 +473,7 @@ class Emitter
 
     private argument(name: string, type: ArgumentType): string
     {
+        this.reads++;
         const local = this.locals.get(name);
         if (local !== undefined)
         {
@@ -456,7 +488,7 @@ class Emitter
         {
             this.fail(`$${name} is used both as ${existing} and as ${type}`);
         }
-        return `args.${name}`;
+        return PLAIN_NAME.test(name) ? `args.${name}` : `args[${JSON.stringify(name)}]`;
     }
 
     private optionValue(value: Literal | Variable | undefined): string | undefined
@@ -507,7 +539,7 @@ class Emitter
                 entries.push(`minimumFractionDigits: ${value.value}`, `maximumFractionDigits: ${value.value}`);
             }
         }
-        return `{ ${entries.join(", ")} }`;
+        return entries.length === 0 ? "{}" : `{ ${entries.join(", ")} }`;
     }
 
     private dateOptions(expression: Expression): string
@@ -544,7 +576,7 @@ class Emitter
         {
             entries.push(`timeZoneName: ${JSON.stringify(style)}`);
         }
-        return `{ ${entries.join(", ")} }`;
+        return entries.length === 0 ? "{}" : `{ ${entries.join(", ")} }`;
     }
 
     /** The JavaScript for an expression's numeric value, before formatting. */
@@ -577,13 +609,13 @@ class Emitter
         return value;
     }
 
-    /** Resolves a plain `{$x}` to its declaration when one exists. */
-    private resolve(expression: Expression): Expression
+    /** 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 && !declared.local)
+            if (declared !== undefined && (locals || !declared.local))
             {
                 return declared.expression;
             }
@@ -607,7 +639,15 @@ class Emitter
         }
         if (NUMBER_FUNCTIONS.has(fn))
         {
-            return `number(${this.numeric(expression)}, ${this.numberOptions(expression)})`;
+            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))
         {
@@ -617,7 +657,7 @@ class Emitter
                 this.fail(`:${fn} needs an operand`);
             }
             const value = operand.kind === "literal" ? `new Date(${JSON.stringify(operand.value)})` : this.argument(operand.name, "date");
-            return `date(${value}, ${this.dateOptions(expression)})`;
+            return `${this.shared(`new Intl.DateTimeFormat(locale, ${this.dateOptions(expression)})`)}().format(${value})`;
         }
         this.fail(`unknown function :${fn}`);
     }
@@ -625,7 +665,7 @@ class Emitter
     /** The JavaScript for a selector: its comparable value and the categories it matches. */
     selector(raw: Expression): string
     {
-        const expression = this.resolve(raw);
+        const expression = this.resolve(raw, true);
         const fn = expression.fn ?? "string";
         if (NUMBER_FUNCTIONS.has(fn))
         {
@@ -636,7 +676,15 @@ class Emitter
             {
                 return `{ value: String(${value}), categories: [] }`;
             }
-            return `{ value: String(${value}), categories: [plural(${value}, ${JSON.stringify(mode === "ordinal" ? "ordinal" : "cardinal")})] }`;
+            const type = JSON.stringify(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")
         {
@@ -667,8 +715,9 @@ class Emitter
             if (declaration.local)
             {
                 const value = this.format(declaration.expression);
-                this.locals.set(name, `local_${name}`);
-                this.prelude.push(`const local_${name} = ${value};`);
+                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)
@@ -677,35 +726,76 @@ class Emitter
         }
         const selectors = this.message.selectors.map((selector) => this.selector(selector));
         const variants = this.message.variants.map((variant) => `{ keys: ${JSON.stringify(variant.keys)}, pattern: () => ${this.pattern(variant.pattern)} }`);
-        return `select([${selectors.join(", ")}], [${variants.join(", ")}])`;
+        this.used.add("select");
+        return `$select([${selectors.join(", ")}], [${variants.join(", ")}])`;
     }
 }
 
-const HELPERS = `const formats = new Map();
-function cached(kind, options, create)
+/** 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);
+    let instance = $formats.get(key);
     if (instance === undefined)
     {
         instance = create();
-        formats.set(key, instance);
+        $formats.set(key, instance);
     }
     return instance;
-}
-function number(value, options)
+}`,
+        ts: `const $formats: Map<string, unknown> = new Map();
+function $cached<T>(kind: string, options: object, create: () => T): T
 {
-    return cached("n", options, () => new Intl.NumberFormat(locale, options)).format(value);
-}
-function date(value, options)
+    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)
 {
-    return cached("d", options, () => new Intl.DateTimeFormat(locale, options)).format(value);
-}
-function plural(value, type)
+    let instance;
+    return () => (instance ??= create());
+}`,
+        ts: `function $once<T>(create: () => T): () => T
 {
-    return cached("p", { type }, () => new Intl.PluralRules(locale, { type })).select(value);
-}
-function select(selectors, variants)
+    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;
@@ -738,7 +828,7 @@ function select(selectors, variants)
         {
             continue;
         }
-        if (matches && better(rank, bestRank))
+        if (matches && $better(rank, bestRank))
         {
             best = variant;
             bestRank = rank;
@@ -746,7 +836,7 @@ function select(selectors, variants)
     }
     return best === undefined ? "" : best.pattern();
 }
-function better(rank, current)
+function $better(rank, current)
 {
     if (current === undefined)
     {
@@ -761,9 +851,8 @@ function better(rank, current)
         }
     }
     return false;
-}`;
-
-const HELPERS_TS = `interface Selector
+}`,
+        ts: `interface Selector
 {
     value: string;
     categories: string[];
@@ -773,31 +862,7 @@ interface Variant
     keys: string[];
     pattern: () => string;
 }
-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;
-}
-function number(value: number, options: Intl.NumberFormatOptions): string
-{
-    return cached("n", options, () => new Intl.NumberFormat(locale, options)).format(value);
-}
-function date(value: Date | number, options: Intl.DateTimeFormatOptions): string
-{
-    return cached("d", options, () => new Intl.DateTimeFormat(locale, options)).format(value);
-}
-function plural(value: number, type: "cardinal" | "ordinal"): string
-{
-    return cached("p", { type }, () => new Intl.PluralRules(locale, { type })).select(value);
-}
-function better(rank: number[], current: number[] | undefined): boolean
+function $better(rank: number[], current: number[] | undefined): boolean
 {
     if (current === undefined)
     {
@@ -813,7 +878,7 @@ function better(rank: number[], current: number[] | undefined): boolean
     }
     return false;
 }
-function select(selectors: Selector[], variants: Variant[]): string
+function $select(selectors: Selector[], variants: Variant[]): string
 {
     let best: Variant | undefined;
     let bestRank: number[] | undefined;
@@ -842,14 +907,27 @@ function select(selectors: Selector[], variants: Variant[]): string
                 break;
             }
         }
-        if (matches && better(rank, bestRank))
+        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
 {
@@ -860,7 +938,11 @@ function typeOf(type: ArgumentType): string
  * 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.
+ * 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
 {
@@ -873,8 +955,9 @@ export function compileMessages(locale: string, catalog: Catalog, options: Compi
     }
     out.push(`export const locale${javascript ? "" : ": string"} = ${JSON.stringify(locale)};`);
     out.push("");
-    out.push(javascript ? HELPERS : HELPERS_TS);
-    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))
@@ -884,23 +967,28 @@ export function compileMessages(locale: string, catalog: Catalog, options: Compi
         {
             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);
+        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, "* /").split(/\r?\n/).map((line) => ` * ${line}`.trimEnd()).join("\n");
-        const argumentType = `{ ${args.map(([argument, type]) => `${argument}: ${typeOf(type)}`).join("; ")} }`;
+        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(`export function ${name}(${args.length > 0 ? "args" : ""})`);
+            out.push(`${binding === name ? "export " : ""}function ${binding}(${args.length > 0 ? "args" : ""})`);
         }
         else
         {
             out.push(`/**\n${doc}\n */`);
-            out.push(`export function ${name}(${args.length > 0 ? `args: ${argumentType}` : ""}): string`);
+            out.push(`${binding === name ? "export " : ""}function ${binding}(${args.length > 0 ? `args: ${argumentType}` : ""}): string`);
         }
         out.push("{");
         for (const line of emitter.prelude)
@@ -909,8 +997,15 @@ export function compileMessages(locale: string, catalog: Catalog, options: Compi
         }
         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 };
 }
 

package/src/index.ts

@@ -12,7 +12,9 @@ import { type ReadableSignal, type Signal, computed, effect, signal } from "zero
 /** One entry of an `Accept-Language` header or of `navigator.languages`. */
 export interface LanguageRange
 {
+    /** The language tag, or `*` for any language, as written before any `;` parameters. */
     readonly range: string;
+    /** The entry's `q` weight between 0 and 1, rounded to three decimals; 1 when the entry gives none. */
     readonly quality: number;
 }
 
@@ -67,7 +69,9 @@ function canonical(tag: string): string
  * `Accept-Language` header, `navigator.languages`, or one tag. Each range
  * is tried in order of quality, first as an exact match, then by dropping
  * subtags from the end as RFC 4647 lookup does, then as the language of a
- * more specific supported locale. `*` and no match at all give `fallback`.
+ * more specific supported locale, preferring one written in the same
+ * script, so `zh-HK` finds `zh-TW` before `zh-CN`. `*` and no match at all
+ * give `fallback`.
  */
 export function negotiateLocale(requested: string | readonly string[] | null | undefined, supported: readonly string[], fallback: string): string
 {
@@ -89,18 +93,33 @@ export function negotiateLocale(requested: string | readonly string[] | null | u
             }
         }
         const language = wanted.split("-")[0] ?? wanted;
-        const related = candidates.find((candidate) => candidate.lower.startsWith(`${language}-`));
-        if (related !== undefined)
+        const related = candidates.filter((candidate) => candidate.lower.startsWith(`${language}-`));
+        if (related.length > 0)
         {
-            return related.tag;
+            const script = scriptOf(range);
+            return (related.find((candidate) => scriptOf(candidate.tag) === script) ?? related[0])?.tag ?? fallback;
         }
     }
     return fallback;
 }
 
-const RTL_LANGUAGES = new Set(["ar", "arc", "ckb", "dv", "fa", "he", "iw", "ks", "ku", "nqo", "pa-arab", "ps", "sd", "syr", "ug", "ur", "yi"]);
+/** The script a locale is written in, with the likely script filled in, as `Hant` for `zh-TW`; undefined for a tag that does not parse. */
+function scriptOf(tag: string): string | undefined
+{
+    try
+    {
+        return new Intl.Locale(tag).maximize().script;
+    }
+    catch
+    {
+        return undefined;
+    }
+}
 
-/** The writing direction of a locale, from `Intl.Locale` where the engine provides it and from the script or language otherwise. */
+/** The scripts written right to left, by their ISO 15924 codes in lowercase. */
+const RTL_SCRIPTS: ReadonlySet<string> = new Set(["adlm", "arab", "hebr", "mand", "mend", "nkoo", "rohg", "samr", "syrc", "thaa", "yezi"]);
+
+/** The writing direction of a locale, from `Intl.Locale` where the engine provides it and otherwise from its script, the likely one when the tag names none, as engines decide. */
 export function localeDirection(locale: string): "ltr" | "rtl"
 {
     try
@@ -112,13 +131,7 @@ export function localeDirection(locale: string): "ltr" | "rtl"
         {
             return info.direction === "rtl" ? "rtl" : "ltr";
         }
-        const language = parsed.language.toLowerCase();
-        const script = parsed.script?.toLowerCase();
-        if (script === "arab" || script === "hebr" || script === "thaa" || script === "syrc" || script === "nkoo")
-        {
-            return "rtl";
-        }
-        return RTL_LANGUAGES.has(language) || RTL_LANGUAGES.has(`${language}-${script ?? ""}`) ? "rtl" : "ltr";
+        return RTL_SCRIPTS.has((parsed.maximize().script ?? "").toLowerCase()) ? "rtl" : "ltr";
     }
     catch
     {
@@ -131,7 +144,7 @@ export interface LocaleOptions
 {
     /** The locales the application ships, most preferred first. */
     supported: readonly string[];
-    /** The locale used when nothing matches. Defaults to the first supported one. */
+    /** The locale used when nothing matches, one of `supported`. Defaults to the first supported one. */
     fallback?: string;
     /** What to negotiate from at first: an `Accept-Language` header, `navigator.languages`, or a tag. Defaults to the fallback. */
     initial?: string | readonly string[] | null;
@@ -144,16 +157,25 @@ export interface LocaleState
     readonly locale: ReadableSignal<string>;
     /** The writing direction of the current locale. */
     readonly direction: ReadableSignal<"ltr" | "rtl">;
+    /** A copy of the `supported` option, in the same order; `set` negotiates against it. */
     readonly supported: readonly string[];
     /** Switches locales after negotiating the request against `supported`. */
     set(requested: string | readonly string[]): void;
 }
 
-/** Creates the locale state for an application. */
+/** Creates the locale state for an application. Throws a `TypeError` when `supported` is empty or `fallback` is not one of its locales, since the locale must always be one of them. */
 export function createLocale(options: LocaleOptions): LocaleState
 {
     const supported = [...options.supported];
-    const fallback = options.fallback ?? supported[0] ?? "en";
+    if (supported.length === 0)
+    {
+        throw new TypeError("zerolith/i18n: createLocale needs at least one supported locale");
+    }
+    const fallback = options.fallback === undefined ? (supported[0] ?? "") : supported.find((tag) => canonical(tag).toLowerCase() === canonical(options.fallback ?? "").toLowerCase());
+    if (fallback === undefined)
+    {
+        throw new TypeError(`zerolith/i18n: the fallback ${options.fallback ?? ""} is not one of the supported locales, ${supported.join(", ")}`);
+    }
     const locale: Signal<string> = signal(negotiateLocale(options.initial ?? fallback, supported, fallback), { name: "locale" });
     return {
         locale,
@@ -179,10 +201,15 @@ export function applyLocale(state: LocaleState, doc: Document = document): () =>
 /** Formatters for the current locale; each reads the locale signal when called, so a computed value or template re-renders on a locale change. */
 export interface Formatters
 {
+    /** Formats a number with `Intl.NumberFormat`. */
     number(value: number, options?: Intl.NumberFormatOptions): string;
+    /** Formats a `Date`, or a timestamp in milliseconds since the epoch, with `Intl.DateTimeFormat`. */
     date(value: Date | number, options?: Intl.DateTimeFormatOptions): string;
+    /** Formats a time `value` units of `unit` away from now with `Intl.RelativeTimeFormat`, such as `in 2 hours`; a negative value lies in the past. */
     relative(value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions): string;
+    /** Joins strings into a list with `Intl.ListFormat`, such as `a, b, and c` in English. */
     list(values: Iterable<string>, options?: Intl.ListFormatOptions): string;
+    /** Selects the plural category of a number with `Intl.PluralRules`, such as `one` or `other`, for choosing a message variant. */
     plural(value: number, options?: Intl.PluralRulesOptions): Intl.LDMLPluralRule;
 }