react-cheminfo 0.23.0 → 0.25.0

package/src/translate/core/mergeMessages.ts

@@ -0,0 +1,74 @@
+import type { Messages } from './catalog.ts';
+import { ownMessage } from './catalog.ts';
+
+/**
+ * Merge a translator's messages into a locale file.
+ *
+ * Keys come out in the order of the English file, so a pull request's diff is
+ * the lines that changed and nothing else; keys the English file no longer has
+ * are kept, last, because removing them is not the translator's decision.
+ * @param source - The English messages, whose order is followed.
+ * @param existing - The locale file as it is in the repository.
+ * @param updates - The messages the translator wrote.
+ * @returns The merged messages.
+ */
+export function mergeMessages(
+  source: Messages,
+  existing: Messages,
+  updates: Messages,
+): Messages {
+  const entries: Array<[string, string]> = [];
+  for (const key of Object.keys(source)) {
+    const message = ownMessage(updates, key) ?? ownMessage(existing, key);
+    if (message !== undefined) entries.push([key, message]);
+  }
+  for (const [key, message] of Object.entries(existing)) {
+    if (!Object.hasOwn(source, key)) entries.push([key, message]);
+  }
+  return Object.fromEntries(entries);
+}
+
+/**
+ * The keys whose message an update actually changes.
+ * @param existing - The locale file as it is in the repository.
+ * @param updates - The messages the translator wrote.
+ * @returns The keys that differ, in the order of the updates.
+ */
+export function changedKeys(existing: Messages, updates: Messages): string[] {
+  const keys: string[] = [];
+  for (const [key, message] of Object.entries(updates)) {
+    if (ownMessage(existing, key) !== message) keys.push(key);
+  }
+  return keys;
+}
+
+/**
+ * Write messages the way a catalog file is committed: two-space JSON with a
+ * final newline, which is also what Prettier leaves untouched.
+ * @param messages - The messages.
+ * @returns The file content.
+ */
+export function serializeMessages(messages: Messages): string {
+  return `${JSON.stringify(messages, null, 2)}\n`;
+}
+
+/**
+ * Read a catalog file, refusing anything but a flat object of strings.
+ * @param text - The file content.
+ * @returns The messages.
+ * @throws {TypeError} When the content is not a flat object of strings.
+ */
+export function parseMessages(text: string): Messages {
+  const parsed: unknown = JSON.parse(text);
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new TypeError('a catalog file must hold one JSON object');
+  }
+  const entries: Array<[string, string]> = [];
+  for (const [key, value] of Object.entries(parsed)) {
+    if (typeof value !== 'string') {
+      throw new TypeError(`the message "${key}" is not a string`);
+    }
+    entries.push([key, value]);
+  }
+  return Object.fromEntries(entries);
+}

package/src/translate/core/session.ts

@@ -0,0 +1,250 @@
+import { IntlMessageFormat } from 'intl-messageformat';
+
+import type { CatalogSource, MessageRef, Messages } from './catalog.ts';
+import { SOURCE_LOCALE, ownMessage } from './catalog.ts';
+import { checkTranslation } from './checkTranslation.ts';
+import { markText } from './marker.ts';
+import type { TranslatableTable } from './tables.ts';
+
+/** The values a message's placeholders are filled with. */
+export type MessageValues = Record<string, string | number | Date>;
+
+/** The version of the page ↔ overlay protocol this session speaks. */
+export const BRIDGE_PROTOCOL = 2;
+
+/** Where a page in translate mode exposes its session to the overlay. */
+export const BRIDGE_GLOBAL = '__cheminfoTranslate';
+
+/** A catalog as the overlay sees it: the source, what is published, the edits. */
+export interface CatalogSnapshot extends CatalogSource {
+  /** The locale file as published with the site. */
+  translation: Messages;
+  /** The messages edited in the overlay and not yet submitted. */
+  drafts: Messages;
+}
+
+/**
+ * What a page in translate mode offers the overlay. It is the only contract
+ * between the two, so an overlay released later still drives a page built
+ * earlier as long as the protocol number matches.
+ */
+export interface TranslateBridge {
+  /** The protocol version; the overlay refuses a page speaking another. */
+  readonly protocol: typeof BRIDGE_PROTOCOL;
+  /** The locale being translated into. */
+  readonly locale: string;
+  /** Every catalog the page registered. */
+  catalogs: () => CatalogSnapshot[];
+  /**
+   * The tables of the page whose rows a translator may write — the element
+   * sheet, a list of ions — with the columns that are text rather than
+   * measurement. Empty on a page that shows no table.
+   */
+  tables: () => TranslatableTable[];
+  /** The message a marker found in the DOM stands for. */
+  resolveMarker: (id: number) => MessageRef | undefined;
+  /** Show an edited message on the page; `undefined` removes the edit. */
+  setDraft: (ref: MessageRef, message: string | undefined) => void;
+  /** Be told whenever a draft changes; returns the function that stops it. */
+  subscribe: (listener: () => void) => () => void;
+}
+
+/** How a session is set up. */
+export interface TranslateSessionOptions {
+  /** The locale messages are shown in. */
+  locale: string;
+  /** Every catalog the page renders from. */
+  catalogs: readonly CatalogSource[];
+  /**
+   * The published messages of `locale`, by catalog id.
+   * @default {}
+   */
+  translations?: Readonly<Record<string, Messages>>;
+  /**
+   * Whether every formatted message carries its invisible marker, which is
+   * what translate mode is.
+   * @default false
+   */
+  marked?: boolean;
+  /**
+   * The tables whose rows are translated, declared so the overlay can offer
+   * them as a grid: a cell of a table is rarely on the page being looked at,
+   * and 118 of them are never Alt-clicked one by one.
+   * @default []
+   */
+  tables?: readonly TranslatableTable[];
+}
+
+interface CatalogState {
+  source: CatalogSource;
+  translation: Messages;
+  drafts: Map<string, string>;
+}
+
+/**
+ * Formats the messages of a page, and in translate mode lets the overlay edit
+ * them live: a draft replaces the published message as soon as it can be
+ * formatted, and a draft that cannot is ignored rather than breaking the page.
+ */
+export class TranslateSession implements TranslateBridge {
+  public readonly protocol = BRIDGE_PROTOCOL;
+  public readonly locale: string;
+  readonly #marked: boolean;
+  readonly #catalogs = new Map<string, CatalogState>();
+  readonly #ids = new Map<string, number>();
+  readonly #refs: MessageRef[] = [];
+  readonly #listeners = new Set<() => void>();
+  readonly #formatters = new Map<string, IntlMessageFormat | null>();
+  readonly #checked = new Map<string, boolean>();
+  readonly #tables: readonly TranslatableTable[];
+  #version = 0;
+
+  public constructor(options: TranslateSessionOptions) {
+    const {
+      locale,
+      catalogs,
+      translations = {},
+      marked = false,
+      tables = [],
+    } = options;
+    this.locale = locale;
+    this.#marked = marked;
+    this.#tables = tables;
+    for (const source of catalogs) {
+      this.#catalogs.set(source.id, {
+        source,
+        translation: translations[source.id] ?? {},
+        drafts: new Map(),
+      });
+    }
+  }
+
+  /**
+   * Increases on every draft change, for a view that re-renders on it.
+   * @returns The current version.
+   */
+  public get version(): number {
+    return this.#version;
+  }
+
+  /**
+   * Format one message: the draft, else the published translation, else the
+   * English message — the first that passes its check against the English
+   * one and formats. A draft that drops a placeholder formats without error,
+   * so the check, not the formatting, is what keeps it off the page.
+   * @param catalogId - The catalog the message belongs to.
+   * @param key - The key of the message.
+   * @param values - What the placeholders are filled with.
+   * @returns The text to show; the key itself when no catalog has it.
+   */
+  public format(catalogId: string, key: string, values?: MessageValues) {
+    const catalog = this.#catalogs.get(catalogId);
+    if (catalog === undefined) return key;
+    const source = ownMessage(catalog.source.messages, key);
+    if (source === undefined) return key;
+
+    const draft = this.#usable(source, catalog.drafts.get(key));
+    const translation = this.#usable(
+      source,
+      ownMessage(catalog.translation, key),
+    );
+    const text =
+      this.#tryFormat(draft, this.locale, values) ??
+      this.#tryFormat(translation, this.locale, values) ??
+      this.#tryFormat(source, SOURCE_LOCALE, values) ??
+      source;
+    return this.#marked ? markText(text, this.#idOf(catalogId, key)) : text;
+  }
+
+  public catalogs(): CatalogSnapshot[] {
+    const snapshots: CatalogSnapshot[] = [];
+    for (const { source, translation, drafts } of this.#catalogs.values()) {
+      snapshots.push({
+        ...source,
+        translation,
+        drafts: Object.fromEntries(drafts),
+      });
+    }
+    return snapshots;
+  }
+
+  /**
+   * The tables whose rows a translator may write.
+   * @returns One entry per table the page declared.
+   */
+  public tables(): TranslatableTable[] {
+    return [...this.#tables];
+  }
+
+  public resolveMarker(id: number): MessageRef | undefined {
+    return this.#refs[id];
+  }
+
+  public setDraft(ref: MessageRef, message: string | undefined): void {
+    const catalog = this.#catalogs.get(ref.catalogId);
+    if (catalog === undefined) return;
+    if (ownMessage(catalog.source.messages, ref.key) === undefined) return;
+    if (catalog.drafts.get(ref.key) === message) return;
+    if (message === undefined) {
+      catalog.drafts.delete(ref.key);
+    } else {
+      catalog.drafts.set(ref.key, message);
+    }
+    this.#version++;
+    for (const listener of this.#listeners) listener();
+  }
+
+  public subscribe(listener: () => void): () => void {
+    this.#listeners.add(listener);
+    return () => {
+      this.#listeners.delete(listener);
+    };
+  }
+
+  #idOf(catalogId: string, key: string): number {
+    const name = `${catalogId}\n${key}`;
+    let id = this.#ids.get(name);
+    if (id === undefined) {
+      id = this.#refs.length;
+      this.#refs.push({ catalogId, key });
+      this.#ids.set(name, id);
+    }
+    return id;
+  }
+
+  #usable(source: string, message: string | undefined): string | undefined {
+    if (message === undefined) return undefined;
+    const name = JSON.stringify([source, message]);
+    let usable = this.#checked.get(name);
+    if (usable === undefined) {
+      usable = checkTranslation(source, message).length === 0;
+      this.#checked.set(name, usable);
+    }
+    return usable ? message : undefined;
+  }
+
+  #tryFormat(
+    message: string | undefined,
+    locale: string,
+    values: MessageValues | undefined,
+  ): string | undefined {
+    if (message === undefined) return undefined;
+    const name = `${locale}\n${message}`;
+    let formatter = this.#formatters.get(name);
+    if (formatter === undefined) {
+      try {
+        formatter = new IntlMessageFormat(message, locale);
+      } catch {
+        formatter = null;
+      }
+      this.#formatters.set(name, formatter);
+    }
+    if (formatter === null) return undefined;
+    try {
+      const output = formatter.format(values);
+      return Array.isArray(output) ? output.join('') : String(output);
+    } catch {
+      return undefined;
+    }
+  }
+}

package/src/translate/core/start.ts

@@ -0,0 +1,183 @@
+/**
+ * Turning a page into a translatable one.
+ *
+ * A site opened with `?translate=<locale>` formats every message with its
+ * invisible marker, hands its session to the overlay as
+ * `window.__cheminfoTranslate`, and loads that overlay from
+ * translate.cheminfo.org. Nothing of this is paid for by an ordinary visit:
+ * the site imports this module only once it has seen the parameter.
+ */
+
+import { isLanguageTag } from '../../language/core/languageParam.ts';
+
+import type { CatalogSource, Messages } from './catalog.ts';
+import { SOURCE_LOCALE } from './catalog.ts';
+import { BRIDGE_GLOBAL, TranslateSession } from './session.ts';
+import type { TranslatableTable } from './tables.ts';
+
+/** The query parameter that opens a page in translate mode. */
+export const TRANSLATE_PARAM = 'translate';
+
+/** Where the overlay is served from unless a site says otherwise. */
+export const TRANSLATE_ORIGIN = 'https://translate.cheminfo.org';
+
+/**
+ * The locale a page is being translated into, from its address:
+ * `?translate=fr` opens the overlay for French.
+ * @param search - The query string, e.g. `location.search`.
+ * @returns The locale, or `undefined` when the page is not in translate mode,
+ *   or names English, or names something that is not a language at all.
+ */
+export function readTranslateLocale(search: string): string | undefined {
+  const value = new URLSearchParams(search).get(TRANSLATE_PARAM);
+  if (value === null || value === SOURCE_LOCALE || !isLanguageTag(value)) {
+    return undefined;
+  }
+  return value;
+}
+
+/** How a page enters translate mode. */
+export interface StartTranslatingOptions {
+  /** The locale being translated into, from {@link readTranslateLocale}. */
+  locale: string;
+  /** Every catalog the page renders messages from. */
+  catalogs: readonly CatalogSource[];
+  /**
+   * The published messages of the locale, by catalog id, so the overlay opens
+   * on what the site already ships rather than on English.
+   * @default {}
+   */
+  translations?: Readonly<Record<string, Messages>>;
+  /**
+   * The tables whose rows a translator may write.
+   * @default []
+   */
+  tables?: readonly TranslatableTable[];
+  /**
+   * Where the overlay is loaded from.
+   * @default 'https://translate.cheminfo.org'
+   */
+  origin?: string;
+  /**
+   * The document the overlay script is added to.
+   * @default globalThis.document
+   */
+  document?: Document;
+  /**
+   * Told when the overlay cannot be fetched — translate.cheminfo.org down, a
+   * network that blocks it, an address typed wrong. The site is expected to
+   * stop formatting through the session, so a page nobody can edit goes back
+   * to being an ordinary page rather than staying marked with no editor.
+   * @default undefined
+   */
+  onUnavailable?: () => void;
+  /**
+   * How long to wait for the overlay before giving up on it, in ms. A server
+   * that accepts the connection and then says nothing never fails the script,
+   * so waiting for `error` alone would wait for ever.
+   * @default 10000
+   */
+  timeout?: number;
+}
+
+/**
+ * Put a page into translate mode.
+ *
+ * The session is exposed before the overlay is loaded, so the overlay finds a
+ * page already formatting marked messages. The site is handed the session back
+ * and must format through it from then on — that is what makes an edit show up
+ * as it is typed.
+ * @param options - See {@link StartTranslatingOptions}.
+ * @returns The session the page formats through.
+ */
+export function startTranslating(
+  options: StartTranslatingOptions,
+): TranslateSession {
+  const {
+    locale,
+    catalogs,
+    translations = {},
+    tables = [],
+    origin = TRANSLATE_ORIGIN,
+    document: target = globalThis.document,
+    onUnavailable,
+    timeout = OVERLAY_TIMEOUT,
+  } = options;
+
+  const session = new TranslateSession({
+    locale,
+    catalogs,
+    translations,
+    tables,
+    marked: true,
+  });
+  Object.assign(globalThis, { [BRIDGE_GLOBAL]: session });
+  loadOverlay(origin, { document: target, onUnavailable, timeout });
+  return session;
+}
+
+/** How long the overlay has to arrive before the page gives up on it. */
+const OVERLAY_TIMEOUT = 10_000;
+
+/** How the overlay script is added, and what happens when it does not come. */
+export interface LoadOverlayOptions {
+  /**
+   * The document to add it to.
+   * @default globalThis.document
+   */
+  document?: Document;
+  /**
+   * Told when it cannot be fetched, or does not arrive in time.
+   * @default undefined
+   */
+  onUnavailable?: () => void;
+  /**
+   * How long to wait, in ms.
+   * @default 10000
+   */
+  timeout?: number;
+}
+
+/**
+ * Add the overlay script to the page, once.
+ * @param origin - Where the overlay is served from.
+ * @param options - See {@link LoadOverlayOptions}.
+ */
+export function loadOverlay(
+  origin: string,
+  options: LoadOverlayOptions = {},
+): void {
+  const {
+    document: target = globalThis.document,
+    onUnavailable,
+    timeout = OVERLAY_TIMEOUT,
+  } = options;
+  if (target === undefined) return;
+  const src = `${origin.replace(/\/$/, '')}/overlay.js`;
+  for (const loaded of target.querySelectorAll('script')) {
+    if (loaded.src === src) return;
+  }
+
+  const script = target.createElement('script');
+  script.type = 'module';
+  script.src = src;
+  script.async = true;
+
+  // The page is only worth marking while there is an editor to use the marks,
+  // so a script that never arrives takes translate mode down with it.
+  let settled = false;
+  const giveUp = () => {
+    if (settled) return;
+    settled = true;
+    script.remove();
+    onUnavailable?.();
+  };
+  const timer = globalThis.setTimeout(giveUp, timeout);
+  script.addEventListener('error', giveUp);
+  script.addEventListener('load', () => {
+    settled = true;
+    globalThis.clearTimeout(timer);
+  });
+
+  target.head.append(script);
+}