react-cheminfo 0.23.0 → 0.24.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,121 @@
+/**
+ * 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;
+}
+
+/**
+ * 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,
+  } = options;
+
+  const session = new TranslateSession({
+    locale,
+    catalogs,
+    translations,
+    tables,
+    marked: true,
+  });
+  Object.assign(globalThis, { [BRIDGE_GLOBAL]: session });
+  loadOverlay(origin, target);
+  return session;
+}
+
+/**
+ * Add the overlay script to the page, once.
+ * @param origin - Where the overlay is served from.
+ * @param target - The document to add it to.
+ */
+export function loadOverlay(
+  origin: string,
+  target = globalThis.document,
+): void {
+  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;
+  target.head.append(script);
+}

package/src/translate/core/suggestions.ts

@@ -0,0 +1,211 @@
+/**
+ * What a translator is offered before typing: the translations already made
+ * for the same English, for English that differs only where the text is not
+ * language, and for English that merely looks like it.
+ *
+ * A table is where this earns its place. Half of 118 element names are the
+ * same word in two languages and the other half differ by an ending; a column
+ * of quantities is a handful of phrases repeated with one word changed. A
+ * translator who is shown what was done three rows above confirms instead of
+ * typing, and the column stays consistent with itself — which is the thing a
+ * long table loses first.
+ *
+ * Nothing here invents a translation. Every suggestion is a translation
+ * somebody already wrote, either as it stands or with the part that is not
+ * language put back.
+ */
+
+import leven from 'leven';
+
+/** One message already translated, which a suggestion is drawn from. */
+export interface TranslatedPair {
+  /** The key it is kept under, so the translator can see where it came from. */
+  key: string;
+  /** The English message. */
+  source: string;
+  /** Its translation. */
+  target: string;
+}
+
+/**
+ * How a suggestion was arrived at.
+ *
+ * - `exact` — the same English message, translated elsewhere.
+ * - `pattern` — English that differs only in a part that is not language (a
+ *   number, a symbol, a formula), with that part put back into the
+ *   translation.
+ * - `similar` — English that looks like this one; the translation is offered
+ *   to be adapted, not to be taken as it is.
+ */
+export type SuggestionKind = 'exact' | 'pattern' | 'similar';
+
+/** One translation offered for a message. */
+export interface MessageSuggestion {
+  /** What goes in the box if the translator takes it. */
+  message: string;
+  /** How it was arrived at. */
+  kind: SuggestionKind;
+  /** Between 0 and 1; 1 is the same English message. */
+  score: number;
+  /** The already-translated message it was drawn from. */
+  from: TranslatedPair;
+}
+
+/** How suggestions are chosen. */
+export interface SuggestionOptions {
+  /**
+   * The most suggestions to return.
+   * @default 5
+   */
+  limit?: number;
+  /**
+   * How alike two English messages must be before one is offered for the
+   * other, between 0 and 1.
+   * @default 0.55
+   */
+  minimumScore?: number;
+}
+
+const DEFAULT_LIMIT = 5;
+const DEFAULT_MINIMUM = 0.55;
+const KIND_ORDER: Record<SuggestionKind, number> = {
+  exact: 0,
+  pattern: 1,
+  similar: 2,
+};
+
+/**
+ * The translations worth offering for one English message.
+ * @param source - The English message being translated.
+ * @param pairs - Every message already translated in this language.
+ * @param options - See {@link SuggestionOptions}.
+ * @returns The suggestions, best first; empty when nothing is close enough.
+ */
+export function messageSuggestions(
+  source: string,
+  pairs: readonly TranslatedPair[],
+  options: SuggestionOptions = {},
+): MessageSuggestion[] {
+  const { limit = DEFAULT_LIMIT, minimumScore = DEFAULT_MINIMUM } = options;
+  if (source === '' || limit <= 0) return [];
+
+  const found: MessageSuggestion[] = [];
+  for (const pair of pairs) {
+    if (pair.target === '' || pair.source === '') continue;
+    const suggestion = suggestFrom(source, pair, minimumScore);
+    if (suggestion !== undefined) found.push(suggestion);
+  }
+
+  found.sort(compareSuggestions);
+  const best: MessageSuggestion[] = [];
+  const taken = new Set<string>();
+  for (const suggestion of found) {
+    if (taken.has(suggestion.message)) continue;
+    taken.add(suggestion.message);
+    best.push(suggestion);
+    if (best.length === limit) break;
+  }
+  return best;
+}
+
+/**
+ * How alike two messages are, as the suggestions rank them.
+ * @param first - One message.
+ * @param second - The other.
+ * @returns 1 when they are the same, 0 when they share nothing.
+ */
+export function messageSimilarity(first: string, second: string): number {
+  const longest = Math.max(first.length, second.length);
+  if (longest === 0) return 1;
+  return 1 - leven(first, second) / longest;
+}
+
+/**
+ * The best offer one already-translated message can make for another.
+ * @param source - The English being translated.
+ * @param pair - The already-translated message to draw from.
+ * @param minimumScore - How alike the two must be to be worth offering.
+ * @returns The suggestion, or `undefined` when the pair is too far away.
+ */
+function suggestFrom(
+  source: string,
+  pair: TranslatedPair,
+  minimumScore: number,
+): MessageSuggestion | undefined {
+  if (pair.source === source) {
+    return { message: pair.target, kind: 'exact', score: 1, from: pair };
+  }
+
+  // An edit can never be smaller than the difference in length, so a pair that
+  // cannot reach the threshold is dropped before the distance is computed.
+  const longest = Math.max(source.length, pair.source.length);
+  const shortest = Math.min(source.length, pair.source.length);
+  if (longest === 0 || shortest / longest < minimumScore) return undefined;
+
+  const pattern = patternSuggestion(source, pair);
+  if (pattern !== undefined && pattern.score >= minimumScore) return pattern;
+
+  const score = messageSimilarity(source, pair.source);
+  if (score < minimumScore) return undefined;
+  return { message: pair.target, kind: 'similar', score, from: pair };
+}
+
+/**
+ * A translation whose English differs from this one only in a run of text
+ * that survives into the translation unchanged — a number, a symbol, a
+ * formula. That run is the only thing put back, so nothing is invented.
+ * @param source - The English being translated.
+ * @param pair - The already-translated message to draw from.
+ * @returns The suggestion, or `undefined` when the run cannot be put back.
+ */
+function patternSuggestion(
+  source: string,
+  pair: TranslatedPair,
+): MessageSuggestion | undefined {
+  const prefix = commonPrefix(source, pair.source);
+  const suffix = commonSuffix(source.slice(prefix), pair.source.slice(prefix));
+  const own = source.slice(prefix, source.length - suffix);
+  const theirs = pair.source.slice(prefix, pair.source.length - suffix);
+  if (theirs === '') return undefined;
+
+  // The varying run must appear once and only once, or putting it back would
+  // be a guess about which occurrence was meant.
+  const at = pair.target.indexOf(theirs);
+  if (at === -1 || pair.target.includes(theirs, at + 1)) return undefined;
+
+  const message =
+    pair.target.slice(0, at) + own + pair.target.slice(at + theirs.length);
+  const kept = prefix + suffix;
+  const score = kept / Math.max(source.length, pair.source.length);
+  return { message, kind: 'pattern', score, from: pair };
+}
+
+function commonPrefix(first: string, second: string): number {
+  const limit = Math.min(first.length, second.length);
+  let length = 0;
+  while (length < limit && first[length] === second[length]) length++;
+  return length;
+}
+
+function commonSuffix(first: string, second: string): number {
+  const limit = Math.min(first.length, second.length);
+  let length = 0;
+  while (
+    length < limit &&
+    first[first.length - 1 - length] === second[second.length - 1 - length]
+  ) {
+    length++;
+  }
+  return length;
+}
+
+function compareSuggestions(
+  first: MessageSuggestion,
+  second: MessageSuggestion,
+): number {
+  if (first.kind !== second.kind) {
+    return KIND_ORDER[first.kind] - KIND_ORDER[second.kind];
+  }
+  if (first.score !== second.score) return second.score - first.score;
+  return first.from.key < second.from.key ? -1 : 1;
+}