mygo-runtime 0.4.8 → 0.5.0

package/README.md

@@ -40,3 +40,16 @@ await done;
 A Go method returning an error rejects with a `CallError` (see
 `isCallError`). Outside a MyGo window, e.g. when the dev server is opened in a
 browser, calls reject and `isMyGo()` is false.
+
+`mygo-runtime/i18n` formats the messages of the app's catalogs in its pages,
+as package `i18n` does in Go: messages of ICU MessageFormat, with the plural
+rules, numbers and dates of `Intl`. `mygo generate` writes a typed module of
+the catalogs next to the client (`locales.ts`) on top of it:
+
+```ts
+import { messages } from "./locales"; // generated
+
+status.textContent = messages.filesSelected(3); // "3 files selected"
+```
+
+`formatMessage(locale, message, args)` formats a message of your own.

package/dist/i18n.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Formats the messages of a MyGo app's catalogs in its pages: messages of
+ * ICU MessageFormat, as package i18n formats them in Go, with the plural
+ * rules, numbers and dates of the browser's `Intl`. The module
+ * `mygo generate` writes next to the TypeScript client (`locales.ts`) is
+ * built on it:
+ *
+ * ```ts
+ * import { messages } from "./locales";
+ *
+ * status.textContent = messages.filesSelected(3); // "3 files selected"
+ * ```
+ *
+ * Use {@link formatMessage} directly to format a message of your own.
+ *
+ * @module
+ */
+/** A part of a parsed message. */
+export type MessagePart = string | {
+    type: "pound";
+} | {
+    type: "arg";
+    name: string;
+} | {
+    type: "number" | "date" | "time";
+    name: string;
+    style: string;
+} | {
+    type: "plural" | "selectordinal" | "select";
+    name: string;
+    offset: number;
+    cases: {
+        key: string;
+        parts: MessagePart[];
+    }[];
+};
+/** The error of a message that does not parse. */
+export declare class MessageSyntaxError extends Error {
+    /** The message. */
+    readonly source: string;
+    /** Where in it the error is, in UTF-16 code units. */
+    readonly offset: number;
+    constructor(
+    /** The message. */
+    source: string, 
+    /** Where in it the error is, in UTF-16 code units. */
+    offset: number, reason: string);
+}
+/**
+ * Parses a message of ICU MessageFormat, as package i18n's ParseMessage
+ * does: the same messages parse, and fail, in Go and in pages.
+ */
+export declare function parseMessage(source: string): MessagePart[];
+/** The hooks that write numbers and dates, which tests and apps may replace. */
+export declare const formatters: {
+    /**
+     * Writes a number in an ICU number style: "" (the default), "integer",
+     * "percent", or a skeleton ("::percent .00"), of which this formatter
+     * reads percent, integer, precision-integer, the precision of fraction
+     * digits (.00, .0#, .##), group-off and currency/, and writes the rest
+     * as the default. Package i18n reads the same, but currencies.
+     */
+    number(locale: string, n: number, style: string, digits?: number): string;
+    /**
+     * Writes a time: its date, its time or both ("datetime"), in an ICU
+     * style, "short", "medium" (the default), "long" or "full", or a
+     * skeleton of CLDR ("::yMMMd"), which Intl finds the locale's pattern
+     * of as package i18n does.
+     */
+    date(locale: string, d: Date, kind: "date" | "time" | "datetime", style: string): string;
+};
+/**
+ * The options of Intl.DateTimeFormat of a skeleton of CLDR, "yMMMd" or
+ * "jm": V8 makes the skeleton back of them, and finds its pattern with
+ * ICU's DateTimePatternGenerator. An hour letter other than j is an
+ * hourCycle, as in package i18n. EEEEEE, CLDR's short weekday ("Mo"),
+ * has no option of Intl: it is the abbreviated one ("Mon"), where package
+ * i18n writes the short one.
+ */
+export declare function skeletonOptions(skeleton: string): Intl.DateTimeFormatOptions;
+/** The pseudo locales, which test layouts without translations. */
+export declare const pseudoLocales: readonly ["en-XA", "ar-XB"];
+/** Reports whether tag is a pseudo locale: en-XA or ar-XB. */
+export declare function isPseudoLocale(tag: string): boolean;
+/**
+ * Formats a message of ICU MessageFormat with the values of its arguments
+ * for locale, as package i18n's Message.Format does: its plural rules
+ * pick the cases, its conventions write numbers and dates, and the pseudo
+ * locales en-XA and ar-XB transform the message. An argument args lacks is
+ * written as it is, `{name}`. Throws a {@link MessageSyntaxError} for a
+ * message that does not parse.
+ */
+export declare function formatMessage(locale: string, message: string, args?: Record<string, unknown>): string;
+/** The data of a catalog, as the module `mygo generate` writes has it. */
+export interface CatalogData {
+    /** The source language, which every message falls back to. */
+    source: string;
+    /** The languages of the catalog: the source, then the others. */
+    languages: string[];
+    /** For each language, the languages it falls back along: itself, its parents, the source. */
+    fallbacks: Record<string, string[]>;
+    /** The names of the arguments of each key, in the order its function takes them. */
+    params: Record<string, string[]>;
+    /** The messages of each language by key. */
+    messages: Record<string, Record<string, string>>;
+}
+/** A catalog of messages in a page, which {@link createCatalog} returns. */
+export interface Catalog<M> {
+    /** The languages of the catalog: the source, then the others. */
+    readonly languages: readonly string[];
+    /** Formats the message of key in locale, or returns key without one. */
+    format(locale: string, key: string, args?: Record<string, unknown>): string;
+    /** Returns the language of the catalog whose messages locale says. */
+    resolve(locale: string): string;
+    /** The messages in the language the page shows, read at each call. */
+    messages(): M;
+    /** The messages in the language of locale. */
+    messagesIn(locale: string): M;
+}
+/**
+ * Returns the language the page shows: the app's, which the MyGo runtime
+ * holds (`window.mygo.locale`, set before the page's scripts run), else
+ * the browser's first preferred language.
+ */
+export declare function currentLocale(): string;
+/** Creates the catalog of a module `mygo generate` wrote. */
+export declare function createCatalog<M>(data: CatalogData): Catalog<M>;

package/dist/i18n.js

@@ -0,0 +1,661 @@
+// src/i18n.ts
+class MessageSyntaxError extends Error {
+  source;
+  offset;
+  constructor(source, offset, reason) {
+    super(`${reason} at offset ${offset} of ${JSON.stringify(source)}`);
+    this.source = source;
+    this.offset = offset;
+    this.name = "MessageSyntaxError";
+  }
+}
+var pluralKeywords = ["zero", "one", "two", "few", "many", "other"];
+function isPatternSpace(c) {
+  return /^[\t\n\v\f\r \u0085\u200e\u200f\u2028\u2029]$/.test(c);
+}
+function isPatternSyntax(c) {
+  const r = c.codePointAt(0);
+  if (r < 128) {
+    return r >= 33 && r <= 47 || r >= 58 && r <= 64 || r >= 91 && r <= 94 || r === 96 || r >= 123 && r <= 126;
+  }
+  return r >= 161 && r <= 167 || r === 169 || r === 171 || r === 172 || r === 174 || r === 176 || r === 177 || r === 182 || r === 187 || r === 191 || r === 215 || r === 247 || r >= 8208 && r <= 8231 || r >= 8240 && r <= 8254 || r >= 8257 && r <= 8275 || r >= 8277 && r <= 8286 || r >= 8592 && r <= 9311 || r >= 9472 && r <= 10101 || r >= 10132 && r <= 11263 || r >= 11776 && r <= 11903 || r >= 12289 && r <= 12291 || r >= 12296 && r <= 12320 || r === 12336 || r === 64830 || r === 64831 || r === 65093 || r === 65094;
+}
+var decimalRe = /^-?\d+(\.\d+)?$/;
+function parseMessage(source) {
+  let i = 0;
+  const s = source;
+  const fail = (reason) => {
+    throw new MessageSyntaxError(source, i, reason);
+  };
+  const space = () => {
+    while (i < s.length && isPatternSpace(s[i]))
+      i++;
+  };
+  const word = () => {
+    const start = i;
+    while (i < s.length) {
+      const c = String.fromCodePoint(s.codePointAt(i));
+      if (isPatternSpace(c) || isPatternSyntax(c))
+        break;
+      i += c.length;
+    }
+    return s.slice(start, i);
+  };
+  const validName = (name) => /^\d/.test(name) ? /^(0|[1-9]\d*)$/.test(name) : /^[\p{L}_]/u.test(name);
+  const message = (depth, inPlural) => {
+    if (depth > 32)
+      fail("arguments nest too deep");
+    const parts = [];
+    let text = "";
+    const flush = () => {
+      if (text !== "")
+        parts.push(text);
+      text = "";
+    };
+    while (i < s.length) {
+      const c = s[i];
+      if (c === "'") {
+        i++;
+        if (s[i] === "'") {
+          text += "'";
+          i++;
+        } else if (i < s.length && (s[i] === "{" || s[i] === "}" || s[i] === "#" && inPlural)) {
+          while (i < s.length) {
+            if (s[i] === "'") {
+              if (s[i + 1] === "'") {
+                text += "'";
+                i += 2;
+                continue;
+              }
+              i++;
+              break;
+            }
+            text += s[i];
+            i++;
+          }
+        } else {
+          text += "'";
+        }
+      } else if (c === "{") {
+        flush();
+        parts.push(argument(depth));
+      } else if (c === "}") {
+        break;
+      } else if (c === "#" && inPlural) {
+        flush();
+        parts.push({ type: "pound" });
+        i++;
+      } else {
+        text += c;
+        i++;
+      }
+    }
+    flush();
+    return parts;
+  };
+  const argument = (depth) => {
+    i++;
+    space();
+    const name = word();
+    if (name === "")
+      fail("an argument has no name");
+    if (!validName(name))
+      fail(`${JSON.stringify(name)} is not an argument name`);
+    space();
+    if (i >= s.length)
+      fail(`unclosed argument {${name}`);
+    if (s[i] === "}") {
+      i++;
+      return { type: "arg", name };
+    }
+    if (s[i] !== ",")
+      fail(`expected , or } after the argument name ${JSON.stringify(name)}`);
+    i++;
+    space();
+    const type = word();
+    space();
+    if (type === "number" || type === "date" || type === "time") {
+      let style = "";
+      if (s[i] === ",") {
+        i++;
+        const start = i;
+        let nest = 0;
+        for (;; ) {
+          if (i >= s.length)
+            fail("unclosed style");
+          const c = s[i];
+          if (c === "'") {
+            const end = s.indexOf("'", i + 1);
+            if (end < 0)
+              fail("unclosed quote in a style");
+            i = end + 1;
+            continue;
+          }
+          if (c === "{")
+            nest++;
+          if (c === "}") {
+            if (nest === 0)
+              break;
+            nest--;
+          }
+          i++;
+        }
+        style = s.slice(start, i).replace(/^[\s\u0085\u200e\u200f]+|[\s\u0085\u200e\u200f]+$/g, "");
+        if (style === "")
+          fail(`the ${type} argument ${JSON.stringify(name)} has an empty style`);
+      }
+      if (s[i] !== "}")
+        fail(`unclosed argument {${name}, ${type}`);
+      i++;
+      return { type, name, style };
+    }
+    if (type === "")
+      fail(`the argument ${JSON.stringify(name)} has no type`);
+    if (type !== "plural" && type !== "selectordinal" && type !== "select") {
+      fail(`unknown argument type ${JSON.stringify(type)} (want number, date, time, plural, selectordinal or select)`);
+    }
+    if (s[i] !== ",")
+      fail(`expected , after ${type}`);
+    i++;
+    const plural = type !== "select";
+    let offset = 0;
+    space();
+    if (plural && s.startsWith("offset:", i)) {
+      i += "offset:".length;
+      space();
+      const start = i;
+      while (i < s.length && s[i] >= "0" && s[i] <= "9")
+        i++;
+      if (start === i || i - start > 15)
+        fail("offset: needs a number");
+      offset = Number(s.slice(start, i));
+    }
+    const cases = [];
+    for (;; ) {
+      space();
+      if (i >= s.length)
+        fail(`unclosed ${type} argument ${JSON.stringify(name)}`);
+      if (s[i] === "}") {
+        i++;
+        break;
+      }
+      let key;
+      if (plural && s[i] === "=") {
+        i++;
+        const start = i;
+        while (i < s.length && /[0-9.]/.test(s[i]))
+          i++;
+        const value = s.slice(start, i);
+        if (!/^\d+(\.\d+)?$/.test(value))
+          fail(`=${value} is not a number`);
+        key = "=" + value;
+      } else {
+        key = word();
+        if (key === "")
+          fail(`expected a case of the ${type} argument ${JSON.stringify(name)}`);
+        if (plural && !pluralKeywords.includes(key)) {
+          fail(`${JSON.stringify(key)} is not a plural category (zero, one, two, few, many, other)`);
+        }
+      }
+      if (cases.some((c) => c.key === key))
+        fail(`the ${type} argument ${JSON.stringify(name)} has the case ${key} twice`);
+      space();
+      if (s[i] !== "{")
+        fail(`expected { after the case ${key}`);
+      i++;
+      const parts = message(depth + 1, plural);
+      if (i >= s.length)
+        fail(`unclosed case ${key}`);
+      i++;
+      cases.push({ key, parts });
+    }
+    if (!cases.some((c) => c.key === "other"))
+      fail(`the ${type} argument ${JSON.stringify(name)} has no other case`);
+    return { type, name, offset, cases };
+  };
+  const parts = message(0, false);
+  if (i < s.length)
+    fail("unmatched }");
+  return parts;
+}
+function toNum(v) {
+  if (typeof v === "number")
+    return Number.isFinite(v) ? { value: v, text: String(v) } : undefined;
+  if (typeof v === "bigint")
+    return { value: Number(v), text: v.toString() };
+  if (typeof v === "string") {
+    const t = v.trim();
+    if (!decimalRe.test(t))
+      return;
+    return { value: Number(t), digits: t.includes(".") ? t.split(".")[1].length : 0, text: t };
+  }
+  return;
+}
+function minus(n, offset) {
+  if (offset === 0)
+    return n;
+  const value = n.value - offset;
+  if (n.digits !== undefined)
+    return { value, digits: n.digits, text: value.toFixed(n.digits) };
+  return { value, text: String(value) };
+}
+function exactEquals(text, exact) {
+  if (text.startsWith("-"))
+    return false;
+  const norm = (s) => {
+    let [i, f = ""] = s.split(".");
+    i = i.replace(/^0+(?=\d)/, "");
+    f = f.replace(/0+$/, "");
+    return f === "" ? i : `${i}.${f}`;
+  };
+  return /^\d+(\.\d+)?$/.test(text) && norm(text) === norm(exact);
+}
+var caches = new Map;
+function cached(key, make) {
+  let v = caches.get(key);
+  if (!v) {
+    v = make();
+    if (caches.size > 256)
+      caches.clear();
+    caches.set(key, v);
+  }
+  return v;
+}
+function safeLocale(locale) {
+  try {
+    return Intl.getCanonicalLocales(locale)[0];
+  } catch {
+    return;
+  }
+}
+function pluralCategory(locale, n, type) {
+  const digits = n.digits;
+  const pr = cached(`p|${locale}|${type}|${digits ?? ""}`, () => new Intl.PluralRules(safeLocale(locale), digits === undefined ? { type } : { type, minimumFractionDigits: digits, maximumFractionDigits: digits }));
+  return pr.select(Math.abs(n.value));
+}
+var formatters = {
+  number(locale, n, style, digits) {
+    const options = {};
+    const stems = style.startsWith("::") ? style.slice(2).trim().split(/\s+/) : [style];
+    let fraction = false;
+    for (const stem of stems) {
+      if (stem === "integer" || stem === "precision-integer") {
+        options.maximumFractionDigits = 0;
+        options.roundingMode = "halfEven";
+      } else if (stem === "percent") {
+        options.style = "percent";
+        options.roundingMode = "halfEven";
+      } else if (stem === "group-off") {
+        options.useGrouping = false;
+      } else if (/^\.[0#]+$/.test(stem)) {
+        options.minimumFractionDigits = stem.split("0").length - 1;
+        options.maximumFractionDigits = stem.length - 1;
+        fraction = true;
+      } else if (stem.startsWith("currency/")) {
+        options.style = "currency";
+        options.currency = stem.slice("currency/".length);
+      }
+    }
+    if (digits !== undefined && !fraction && options.style === undefined && options.maximumFractionDigits === undefined) {
+      options.minimumFractionDigits = options.maximumFractionDigits = Math.min(digits, 100);
+    }
+    const nf = cached(`n|${locale}|${JSON.stringify(options)}`, () => new Intl.NumberFormat(safeLocale(locale), options));
+    return nf.format(n);
+  },
+  date(locale, d, kind, style) {
+    const s = ["short", "medium", "long", "full"].includes(style) ? style : "medium";
+    const options = style.startsWith("::") ? skeletonOptions(style.slice(2).trim()) : kind === "date" ? { dateStyle: s } : kind === "time" ? { timeStyle: s } : { dateStyle: "short", timeStyle: "short" };
+    const df = cached(`d|${locale}|${JSON.stringify(options)}`, () => new Intl.DateTimeFormat(safeLocale(locale), options));
+    return df.format(d);
+  }
+};
+function skeletonOptions(skeleton) {
+  const o = {};
+  for (const [field] of skeleton.matchAll(/([A-Za-z])\1*/g)) {
+    const n = field.length;
+    switch (field[0]) {
+      case "y":
+        o.year = n === 2 ? "2-digit" : "numeric";
+        break;
+      case "M":
+      case "L":
+        o.month = n === 1 ? "numeric" : n === 2 ? "2-digit" : n === 3 ? "short" : n === 4 ? "long" : "narrow";
+        break;
+      case "d":
+        o.day = n === 2 ? "2-digit" : "numeric";
+        break;
+      case "E":
+      case "c":
+        o.weekday = n === 4 ? "long" : n === 5 ? "narrow" : "short";
+        break;
+      case "j":
+      case "h":
+      case "H":
+      case "K":
+      case "k":
+        o.hour = n === 2 ? "2-digit" : "numeric";
+        if (field[0] === "h")
+          o.hourCycle = "h12";
+        if (field[0] === "H")
+          o.hourCycle = "h23";
+        if (field[0] === "K")
+          o.hourCycle = "h11";
+        if (field[0] === "k")
+          o.hourCycle = "h24";
+        break;
+      case "m":
+        o.minute = n === 2 ? "2-digit" : "numeric";
+        break;
+      case "s":
+        o.second = n === 2 ? "2-digit" : "numeric";
+        break;
+      case "z":
+      case "v":
+        o.timeZoneName = n >= 4 ? "long" : "short";
+        break;
+    }
+  }
+  return o;
+}
+function valueString(locale, v) {
+  if (typeof v === "string")
+    return v;
+  if (v instanceof Date)
+    return formatters.date(locale, v, "datetime", "short");
+  if (v === null || v === undefined)
+    return "";
+  if (typeof v === "number" || typeof v === "bigint") {
+    const n = toNum(v);
+    return n ? formatters.number(locale, n.value, "", n.digits) : String(v);
+  }
+  if (v instanceof Error)
+    return v.message;
+  return String(v);
+}
+var accented = {
+  a: "å",
+  b: "ƀ",
+  c: "ç",
+  d: "ð",
+  e: "é",
+  f: "ƒ",
+  g: "ĝ",
+  h: "ĥ",
+  i: "î",
+  j: "ĵ",
+  k: "ķ",
+  l: "ļ",
+  m: "ɱ",
+  n: "ñ",
+  o: "ö",
+  p: "þ",
+  q: "ǫ",
+  r: "ŕ",
+  s: "š",
+  t: "ţ",
+  u: "û",
+  v: "ṽ",
+  w: "ŵ",
+  x: "ẋ",
+  y: "ý",
+  z: "ž",
+  A: "Å",
+  B: "Ɓ",
+  C: "Ç",
+  D: "Ð",
+  E: "É",
+  F: "Ƒ",
+  G: "Ĝ",
+  H: "Ĥ",
+  I: "Î",
+  J: "Ĵ",
+  K: "Ķ",
+  L: "Ļ",
+  M: "Ṁ",
+  N: "Ñ",
+  O: "Ö",
+  P: "Þ",
+  Q: "Ǫ",
+  R: "Ŕ",
+  S: "Š",
+  T: "Ţ",
+  U: "Û",
+  V: "Ṽ",
+  W: "Ŵ",
+  X: "Ẋ",
+  Y: "Ý",
+  Z: "Ž"
+};
+var padWords = "one two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen sixteen seventeen eighteen nineteen twenty".split(" ");
+var RLM = "‏";
+var RLO = "‮";
+var PDF = "‬";
+var pseudoLocales = ["en-XA", "ar-XB"];
+function canonical(tag) {
+  return safeLocale(tag.replace(/_/g, "-").split(/[.@]/)[0]) ?? "";
+}
+function stripExtensions(tag) {
+  const parts = tag.split("-");
+  const i = parts.findIndex((p, i) => i > 0 && p.length === 1);
+  return i < 0 ? tag : parts.slice(0, i).join("-");
+}
+function isPseudoLocale(tag) {
+  return pseudoLocales.includes(stripExtensions(canonical(tag)));
+}
+function pseudoFor(locale) {
+  switch (stripExtensions(canonical(locale))) {
+    case "en-XA": {
+      let length = 0;
+      return {
+        text(s) {
+          let out = "";
+          for (const c of s) {
+            out += accented[c] ?? c;
+            length++;
+          }
+          return out;
+        },
+        placeholder: (s) => s,
+        wrap(s) {
+          const pad = Math.floor((length * 2 + 4) / 5);
+          let out = "[" + s;
+          for (let i = 0, n = 0;n < pad; i++) {
+            const w = padWords[i % padWords.length];
+            out += " " + w;
+            n += 1 + w.length;
+          }
+          return out + "]";
+        }
+      };
+    }
+    case "ar-XB":
+      return {
+        text: (s) => s.replace(/[^\s]+/gu, (w) => RLM + RLO + w + PDF + RLM),
+        placeholder: (s) => RLM + s + RLM,
+        wrap: (s) => s
+      };
+  }
+  return;
+}
+function formatParts(parts, locale, pluralLocale, args, pseudo, pound) {
+  let out = "";
+  const placeholder = (s) => pseudo ? pseudo.placeholder(s) : s;
+  for (const part of parts) {
+    if (typeof part === "string") {
+      out += pseudo ? pseudo.text(part) : part;
+      continue;
+    }
+    if (part.type === "pound") {
+      if (!pound) {
+        out += "#";
+      } else if (pound.num) {
+        out += placeholder(formatters.number(locale, pound.num.value, "", pound.num.digits));
+      } else {
+        out += placeholder(valueString(locale, pound.raw));
+      }
+      continue;
+    }
+    if (!Object.prototype.hasOwnProperty.call(args, part.name)) {
+      out += `{${part.name}}`;
+      continue;
+    }
+    const v = args[part.name];
+    switch (part.type) {
+      case "arg":
+        out += placeholder(valueString(locale, v));
+        break;
+      case "number": {
+        const n = toNum(v);
+        out += placeholder(n ? formatters.number(locale, n.value, part.style, n.digits) : valueString(locale, v));
+        break;
+      }
+      case "date":
+      case "time":
+        out += placeholder(v instanceof Date ? formatters.date(locale, v, part.type, part.style) : valueString(locale, v));
+        break;
+      case "select": {
+        const key = typeof v === "string" ? v : typeof v === "number" ? toNum(v)?.text ?? String(v) : String(v);
+        const c = part.cases.find((c) => c.key === key) ?? part.cases.find((c) => c.key === "other");
+        out += formatParts(c.parts, locale, pluralLocale, args, pseudo, pound);
+        break;
+      }
+      case "plural":
+      case "selectordinal": {
+        const n = toNum(v);
+        const other = part.cases.find((c) => c.key === "other");
+        if (!n) {
+          out += formatParts(other.parts, locale, pluralLocale, args, pseudo, { raw: v });
+          break;
+        }
+        let chosen = part.cases.find((c) => c.key.startsWith("=") && exactEquals(n.text, c.key.slice(1)));
+        const shown = minus(n, part.offset);
+        if (!chosen) {
+          const cat = pluralCategory(pluralLocale, shown, part.type === "plural" ? "cardinal" : "ordinal");
+          chosen = part.cases.find((c) => c.key === cat) ?? other;
+        }
+        out += formatParts(chosen.parts, locale, pluralLocale, args, pseudo, { num: shown });
+        break;
+      }
+    }
+  }
+  return out;
+}
+var parsedCache = new Map;
+function parsed(message) {
+  let parts = parsedCache.get(message);
+  if (!parts) {
+    parts = parseMessage(message);
+    parsedCache.set(message, parts);
+  }
+  return parts;
+}
+function formatMessage(locale, message, args = {}) {
+  const pseudo = pseudoFor(locale);
+  return format(parsed(message), pseudo ? "en" : locale, pseudo ? "en" : locale, args, pseudo);
+}
+function format(parts, locale, pluralLocale, args, pseudo) {
+  const out = formatParts(parts, locale, pluralLocale, args, pseudo, undefined);
+  return pseudo ? pseudo.wrap(out) : out;
+}
+function currentLocale() {
+  const rt = globalThis.mygo;
+  const locale = typeof rt?.locale === "function" ? rt.locale() : rt?.locale;
+  if (typeof locale === "string" && locale !== "")
+    return locale;
+  if (typeof navigator !== "undefined")
+    return navigator.languages?.[0] ?? navigator.language ?? "";
+  return "";
+}
+function createCatalog(data) {
+  const resolved = new Map;
+  const resolve = (locale) => {
+    let r = resolved.get(locale);
+    if (r !== undefined)
+      return r;
+    r = data.source;
+    const tag = stripExtensions(canonical(locale));
+    if (data.languages.includes(tag)) {
+      r = tag;
+    } else if (tag !== "" && !isPseudoLocale(tag)) {
+      const found = truncations(tag).find((t) => data.languages.includes(t)) ?? sameScript(tag, data.languages);
+      if (found)
+        r = found;
+    }
+    resolved.set(locale, r);
+    return r;
+  };
+  const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+  const lookup = (locale, key) => {
+    const lang = isPseudoLocale(locale) ? data.source : resolve(locale);
+    for (const t of data.fallbacks[lang] ?? [data.source]) {
+      const messages = has(data.messages, t) ? data.messages[t] : undefined;
+      const m = messages && has(messages, key) ? messages[key] : undefined;
+      if (m !== undefined)
+        return [m, t];
+    }
+    return;
+  };
+  const formatKey = (locale, key, args = {}) => {
+    const found = lookup(locale, key);
+    if (!found)
+      return key;
+    const [message, lang] = found;
+    let parts;
+    try {
+      parts = parsed(message);
+    } catch {
+      return key;
+    }
+    const pseudo = pseudoFor(locale);
+    const numbers = pseudo || locale === "" ? lang : locale;
+    return format(parts, numbers, lang, args, pseudo);
+  };
+  const bind = (locale) => {
+    const out = {};
+    for (const [key, names] of Object.entries(data.params)) {
+      out[key] = (...values) => {
+        const args = {};
+        names.forEach((name, i) => args[name] = values[i]);
+        return formatKey(locale(), key, args);
+      };
+    }
+    return out;
+  };
+  return {
+    languages: data.languages,
+    format: formatKey,
+    resolve,
+    messages: () => bind(currentLocale),
+    messagesIn: (locale) => bind(() => locale)
+  };
+}
+function truncations(tag) {
+  const parts = tag.split("-");
+  const out = [];
+  for (let n = parts.length;n > 0; n--)
+    out.push(parts.slice(0, n).join("-"));
+  return out;
+}
+function sameScript(tag, langs) {
+  try {
+    const want = new Intl.Locale(tag).maximize();
+    const same = langs.filter((l) => {
+      const have = new Intl.Locale(l).maximize();
+      return have.language === want.language && have.script === want.script;
+    });
+    return same.find((l) => new Intl.Locale(l).maximize().region === want.region) ?? same[0];
+  } catch {
+    return;
+  }
+}
+export {
+  MessageSyntaxError,
+  createCatalog,
+  currentLocale,
+  formatMessage,
+  formatters,
+  isPseudoLocale,
+  parseMessage,
+  pseudoLocales,
+  skeletonOptions
+};

package/dist/index.d.ts

@@ -13,8 +13,8 @@
  *
  * @module
  */
-import type { Channel as ChannelType, Runtime, WindowControls } from "./types";
-export type { Platform, Runtime, WindowControls } from "./types";
+import type { Channel as ChannelType, Direction, Runtime, ThemePreferences, WindowControls } from "./types";
+export type { Direction, LocaleChange, Platform, Runtime, ThemePreferences, WindowControls } from "./types";
 declare global {
     interface Window {
         /** The MyGo runtime; missing outside MyGo windows. */
@@ -56,6 +56,34 @@ export declare const Channel: new <T = unknown>(onmessage?: (value: T) => void)
 export declare function on<T = unknown>(name: string, listener: (payload: T) => void): () => void;
 /** Like {@link on}, but unsubscribes after the first event. */
 export declare function once<T = unknown>(name: string, listener: (payload: T) => void): () => void;
+/**
+ * The language the app shows, a BCP 47 tag such as "en" or "zh-Hans"
+ * (`App.Locale`): the page has it from document start, so its first paint
+ * can be in it.
+ *
+ * ```ts
+ * document.documentElement.lang = locale();
+ * document.documentElement.dir = direction();
+ * ```
+ */
+export declare function locale(): string;
+/** The direction the language the app shows is written in: "ltr" or "rtl". */
+export declare function direction(): Direction;
+/**
+ * Subscribes to changes of the language the app shows, as `App.SetLocale`
+ * makes them, or the user's languages while the app follows them. The
+ * listener hears only of a language the page did not have: a page loaded
+ * after a change starts with the new one. Returns a function that
+ * unsubscribes.
+ *
+ * ```ts
+ * onLocaleChange((tag, dir) => {
+ *   document.documentElement.lang = tag;
+ *   document.documentElement.dir = dir;
+ * });
+ * ```
+ */
+export declare function onLocaleChange(listener: (locale: string, dir: Direction) => void): () => void;
 /** A typed event sent by the Go side, declared with `mygo.NewEvent`. */
 export interface GoEvent<T> {
     readonly name: string;
@@ -95,5 +123,64 @@ export interface FileDrop {
  * ```
  */
 export declare function onFileDrop(listener: (drop: FileDrop) => void): () => void;
+/** The document a window shows (mygo.NewDocuments), as Go describes it. */
+export interface DocumentState {
+    /** The file name, or a name such as "Untitled 2" while untitled. */
+    name: string;
+    /** The file, "" while the document is untitled. */
+    path: string;
+    /** Whether the document has unsaved changes. */
+    edited: boolean;
+    /** Whether its file can't be written: saving asks for another. */
+    readOnly: boolean;
+    /** Whether another app changed its file while it had unsaved changes. */
+    conflict: boolean;
+    /** Whether its file was deleted: saving writes it again. */
+    deleted: boolean;
+}
+/**
+ * Subscribes to the state of the window's document: edited, saved,
+ * renamed, moved, changed by another app. Only the app's own pages get it.
+ * Returns a function that unsubscribes.
+ *
+ * ```ts
+ * onDocumentState(({ name, edited }) => {
+ *   heading.textContent = edited ? `${name} (edited)` : name;
+ * });
+ * ```
+ */
+export declare function onDocumentState(listener: (state: DocumentState) => void): () => void;
+/**
+ * Subscribes to the window's document being read from its file again:
+ * reverted, or changed by another app while it had no unsaved changes.
+ * Fetch its content again, with the service bound to
+ * `Documents.Service()`. Returns a function that unsubscribes.
+ */
+export declare function onDocumentReload(listener: () => void): () => void;
+/**
+ * Returns the accent color and the accessibility settings of the desktop
+ * (`mygo.Theme.Preferences()` in Go), current from document start on.
+ * Throws outside MyGo, as {@link runtime} does.
+ *
+ * ```ts
+ * const { accent, reduceTransparency } = preferences();
+ * ```
+ *
+ * CSS gets the accent and the text scale from the `--mygo-accent` and
+ * `--mygo-text-scale` variables of `:root`.
+ */
+export declare function preferences(): ThemePreferences;
+/**
+ * Subscribes to changes of the desktop's preferences, which
+ * {@link preferences} returns; the listener gets the new ones. Returns a
+ * function that unsubscribes.
+ *
+ * ```ts
+ * const apply = (p: ThemePreferences) => root.classList.toggle("opaque", p.reduceTransparency);
+ * apply(preferences());
+ * onPreferences(apply);
+ * ```
+ */
+export declare function onPreferences(listener: (preferences: ThemePreferences) => void): () => void;
 /** The window hosting the page, e.g. for a custom title bar. */
 export declare const currentWindow: WindowControls;

package/dist/index.js

@@ -24,6 +24,15 @@ function on(name, listener) {
 function once(name, listener) {
   return runtime().once(name, listener);
 }
+function locale() {
+  return runtime().locale;
+}
+function direction() {
+  return runtime().dir;
+}
+function onLocaleChange(listener) {
+  return on("mygo:locale", (p) => listener(p.locale, p.dir));
+}
 function event(name) {
   return {
     name,
@@ -37,6 +46,18 @@ function isCallError(err) {
 function onFileDrop(listener) {
   return on("mygo:file-drop", listener);
 }
+function onDocumentState(listener) {
+  return on("mygo:document-state", listener);
+}
+function onDocumentReload(listener) {
+  return on("mygo:document-reload", () => listener());
+}
+function preferences() {
+  return runtime().preferences;
+}
+function onPreferences(listener) {
+  return on("mygo:preferences", listener);
+}
 var currentWindow = {
   minimize: async () => runtime().window.minimize(),
   maximize: async () => runtime().window.maximize(),
@@ -51,11 +72,18 @@ export {
   Channel,
   call,
   currentWindow,
+  direction,
   event,
   isCallError,
   isMyGo,
+  locale,
   on,
+  onDocumentReload,
+  onDocumentState,
   onFileDrop,
+  onLocaleChange,
+  onPreferences,
   once,
+  preferences,
   runtime
 };

package/dist/types.d.ts

@@ -1,5 +1,14 @@
 /** The operating system, using Node.js' `process.platform` names. */
 export type Platform = "darwin" | "linux" | "win32";
+/** The direction a language is written in: left to right, or right to left. */
+export type Direction = "ltr" | "rtl";
+/** The payload of the `mygo:locale` event. */
+export interface LocaleChange {
+    /** The language the app shows now, e.g. "zh-Hans". */
+    locale: string;
+    /** The direction it is written in. */
+    dir: Direction;
+}
 /** Controls for the window hosting the page, handy for custom title bars. */
 export interface WindowControls {
     minimize(): Promise<void>;
@@ -32,6 +41,26 @@ export interface Channel<T = unknown> extends AsyncIterable<T> {
      */
     close(): void;
 }
+/**
+ * The accent color and the accessibility settings of the desktop, as
+ * `mygo.ThemePreferences` encodes them.
+ */
+export interface ThemePreferences {
+    /** The accent color of the desktop's controls as "#rrggbb", or null where the desktop has none. */
+    accent: string | null;
+    /** Whether the desktop asks for less motion; `prefers-reduced-motion` tells it too. */
+    reduceMotion: boolean;
+    /**
+     * Whether the desktop asks for opaque surfaces in place of translucent
+     * ones: macOS's Reduce Transparency, Windows's transparency effects
+     * turned off. Linux desktops have no such setting.
+     */
+    reduceTransparency: boolean;
+    /** Whether the desktop asks for more contrast; `prefers-contrast` tells it too. */
+    highContrast: boolean;
+    /** How many times larger than usual text should be; 1 is usual. */
+    textScale: number;
+}
 /** The runtime MyGo injects into every page as `window.mygo`. */
 export interface Runtime {
     /** Calls a bound Go method, e.g. `call("Greeter.Greet", "Ada")`. */
@@ -51,6 +80,20 @@ export interface Runtime {
     readonly windowId: number;
     /** MyGo version. */
     readonly version: string;
+    /**
+     * The desktop's preferences, current from document start on; the
+     * `mygo:preferences` event tells their changes.
+     */
+    readonly preferences: ThemePreferences;
+    /**
+     * The language the app shows, a BCP 47 tag such as "en" or "zh-Hans"
+     * (`App.Locale`): of the languages the app is written in, the one the
+     * user reads best, or the one `App.SetLocale` chose. A page has it from
+     * document start, and the `mygo:locale` event tells of changes.
+     */
+    readonly locale: string;
+    /** The direction `locale` is written in, for `<html dir>`. */
+    readonly dir: Direction;
     /** The window hosting this page. */
     readonly window: WindowControls;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mygo-runtime",
-  "version": "0.4.8",
+  "version": "0.5.0",
   "description": "Typed access to the MyGo runtime in the pages of MyGo desktop apps",
   "keywords": [
     "mygo",
@@ -20,6 +20,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./i18n": {
+      "types": "./dist/i18n.d.ts",
+      "default": "./dist/i18n.js"
     }
   },
   "types": "./dist/index.d.ts",