react-cheminfo 0.22.0 → 0.24.0

package/src/translate/core/checkTranslation.ts

@@ -0,0 +1,128 @@
+import type { MessageFormatElement } from '@formatjs/icu-messageformat-parser';
+import { TYPE, parse } from '@formatjs/icu-messageformat-parser';
+
+/** What can be wrong with one translated message. */
+export type MessageProblemKind =
+  | 'empty'
+  | 'syntax'
+  | 'source-syntax'
+  | 'missing-argument'
+  | 'unknown-argument';
+
+/** One thing wrong with a translated message, worded for the translator. */
+export interface MessageProblem {
+  /** What kind of problem it is. */
+  kind: MessageProblemKind;
+  /** The sentence the translator reads. */
+  message: string;
+  /**
+   * The placeholder or tag the problem is about, written as it appears in a
+   * message: `{count}` or `<link>`.
+   * @default undefined
+   */
+  argument?: string;
+}
+
+/**
+ * Check a translation against the English message it translates: it must be
+ * a valid ICU message and use exactly the placeholders and tags of the source.
+ * @param source - The English message.
+ * @param translation - The translated message.
+ * @returns Every problem found; empty when the translation can be used.
+ */
+export function checkTranslation(
+  source: string,
+  translation: string,
+): MessageProblem[] {
+  if (translation.trim() === '') {
+    return [{ kind: 'empty', message: 'The translation is empty.' }];
+  }
+
+  let expected: Set<string>;
+  try {
+    expected = messageArguments(source);
+  } catch (error) {
+    return [
+      {
+        kind: 'source-syntax',
+        message: `The English message itself is not valid: ${describe(error)}`,
+      },
+    ];
+  }
+
+  let actual: Set<string>;
+  try {
+    actual = messageArguments(translation);
+  } catch (error) {
+    return [{ kind: 'syntax', message: describe(error) }];
+  }
+
+  const problems: MessageProblem[] = [];
+  for (const argument of expected) {
+    if (!actual.has(argument)) {
+      problems.push({
+        kind: 'missing-argument',
+        argument,
+        message: `${argument} is in the English message but not in the translation.`,
+      });
+    }
+  }
+  for (const argument of actual) {
+    if (!expected.has(argument)) {
+      problems.push({
+        kind: 'unknown-argument',
+        argument,
+        message: `${argument} is not in the English message, so nothing would fill it.`,
+      });
+    }
+  }
+  return problems;
+}
+
+/**
+ * The placeholders and tags a message uses, each written as it appears in the
+ * message: `{count}` for an argument, `<link>` for a tag.
+ * @param message - An ICU message.
+ * @returns The set of placeholders and tags.
+ * @throws {SyntaxError} When the message does not parse.
+ */
+export function messageArguments(message: string): Set<string> {
+  const found = new Set<string>();
+  collect(parse(message), found);
+  return found;
+}
+
+function collect(elements: MessageFormatElement[], found: Set<string>): void {
+  for (const element of elements) {
+    switch (element.type) {
+      case TYPE.argument:
+      case TYPE.number:
+      case TYPE.date:
+      case TYPE.time:
+        found.add(`{${element.value}}`);
+        break;
+      case TYPE.select:
+      case TYPE.plural:
+        found.add(`{${element.value}}`);
+        for (const option of Object.values(element.options)) {
+          collect(option.value, found);
+        }
+        break;
+      case TYPE.tag:
+        found.add(`<${element.value}>`);
+        collect(element.children, found);
+        break;
+      case TYPE.literal:
+      case TYPE.pound:
+        break;
+      // no default
+    }
+  }
+}
+
+function describe(error: unknown): string {
+  if (error instanceof Error) {
+    return `The message does not parse (${error.message}).`;
+  }
+  return 'The message does not parse.';
+}

package/src/translate/core/contribution.ts

@@ -0,0 +1,99 @@
+/**
+ * What the overlay sends the server, and what the server answers.
+ */
+
+import type { Messages } from './catalog.ts';
+
+/** The longest message a contribution may carry, in characters. */
+export const MAX_MESSAGE_LENGTH = 5000;
+
+/** The most messages one catalog of a contribution may carry. */
+export const MAX_MESSAGES_PER_CATALOG = 2000;
+
+/** The most catalogs one contribution may carry. */
+export const MAX_CATALOGS = 32;
+
+/** The longest name a translator may be credited under. */
+export const MAX_CONTRIBUTOR_LENGTH = 100;
+
+/** The longest note a translator may leave for the reviewer. */
+export const MAX_NOTE_LENGTH = 1000;
+
+/** The messages translated for one catalog. */
+export interface ContributionCatalog {
+  /** The repository the catalog lives in, written `owner/repo`. */
+  repository: string;
+  /** The catalog directory, relative to the repository root. */
+  directory: string;
+  /** The translated messages by key. */
+  messages: Messages;
+}
+
+/** One submission from the overlay. */
+export interface Contribution {
+  /** The locale the messages are written in. */
+  locale: string;
+  /** The translated messages, catalog by catalog. */
+  catalogs: ContributionCatalog[];
+  /**
+   * The name the pull request credits.
+   * @default undefined
+   */
+  contributor?: string;
+  /**
+   * A note for whoever reviews the pull request.
+   * @default undefined
+   */
+  note?: string;
+  /**
+   * Continuation tokens of pull requests this translator opened before: a
+   * repository that has an open one gets a new commit there, not a new PR.
+   * @default []
+   */
+  continuations?: string[];
+}
+
+/** A pull request a contribution opened or added to. */
+export interface ContributionPullRequest {
+  /** The repository the pull request is on, `owner/repo`. */
+  repository: string;
+  /** Its number. */
+  number: number;
+  /** Where to read it. */
+  url: string;
+  /** How many messages this contribution changed in it. */
+  messageCount: number;
+  /** Whether an existing pull request was added to rather than opened. */
+  updated: boolean;
+  /** The token that lets the same translator add to it next time. */
+  continuation: string;
+}
+
+/** What a successful submission answers. */
+export interface ContributionResult {
+  /** One entry per repository that changed; empty when nothing did. */
+  pullRequests: ContributionPullRequest[];
+}
+
+/** One reason a submission was refused. */
+export interface ContributionProblem {
+  /** The repository concerned. */
+  repository: string;
+  /** The catalog directory concerned. */
+  directory: string;
+  /**
+   * The message concerned, when the problem is about one.
+   * @default undefined
+   */
+  key?: string;
+  /** The sentence the translator reads. */
+  message: string;
+}
+
+/** What a refused submission answers. */
+export interface ContributionRejection {
+  /** A summary of why. */
+  error: string;
+  /** Every problem found. */
+  problems: ContributionProblem[];
+}

package/src/translate/core/index.ts

@@ -0,0 +1,72 @@
+// Both travel with the catalogs: a server validating a submission and naming
+// the language in a pull request must not have to load the whole of
+// `react-cheminfo/core` to do it.
+export { languageName } from '../../language/core/languageName.ts';
+export { isLanguageTag } from '../../language/core/languageParam.ts';
+export type { CatalogSource, MessageRef, Messages } from './catalog.ts';
+export {
+  SOURCE_LOCALE,
+  catalogFile,
+  isCatalogDirectory,
+  ownMessage,
+} from './catalog.ts';
+export type { MessageProblem, MessageProblemKind } from './checkTranslation.ts';
+export { checkTranslation, messageArguments } from './checkTranslation.ts';
+export type {
+  Contribution,
+  ContributionCatalog,
+  ContributionProblem,
+  ContributionPullRequest,
+  ContributionRejection,
+  ContributionResult,
+} from './contribution.ts';
+export {
+  MAX_CATALOGS,
+  MAX_CONTRIBUTOR_LENGTH,
+  MAX_MESSAGES_PER_CATALOG,
+  MAX_MESSAGE_LENGTH,
+  MAX_NOTE_LENGTH,
+} from './contribution.ts';
+export {
+  encodeMarker,
+  hasMarker,
+  markText,
+  readMarkers,
+  stripMarkers,
+} from './marker.ts';
+export {
+  changedKeys,
+  mergeMessages,
+  parseMessages,
+  serializeMessages,
+} from './mergeMessages.ts';
+export type {
+  CatalogSnapshot,
+  MessageValues,
+  TranslateBridge,
+  TranslateSessionOptions,
+} from './session.ts';
+export { BRIDGE_GLOBAL, BRIDGE_PROTOCOL, TranslateSession } from './session.ts';
+export type { StartTranslatingOptions } from './start.ts';
+export {
+  TRANSLATE_ORIGIN,
+  TRANSLATE_PARAM,
+  loadOverlay,
+  readTranslateLocale,
+  startTranslating,
+} from './start.ts';
+export type {
+  MessageSuggestion,
+  SuggestionKind,
+  SuggestionOptions,
+  TranslatedPair,
+} from './suggestions.ts';
+export { messageSimilarity, messageSuggestions } from './suggestions.ts';
+export type {
+  TableCell,
+  TranslatableField,
+  TranslatableFieldSize,
+  TranslatableRow,
+  TranslatableTable,
+} from './tables.ts';
+export { tableCells, tableKey } from './tables.ts';

package/src/translate/core/marker.ts

@@ -0,0 +1,85 @@
+/**
+ * The invisible mark a message carries while a page is being translated.
+ *
+ * In translate mode every formatted message is prefixed with its id, written
+ * in characters that take no space and join nothing. Whatever the string then
+ * becomes — a text node, a `title`, a `placeholder`, a prop handed to a
+ * third-party component — the overlay finds it in the DOM and knows which
+ * message it is, without any component having been written for it.
+ *
+ * The digits are the invisible mathematical operators U+2061–U+2064, closed by
+ * WORD JOINER U+2060: none of them is whitespace, none joins emoji the way
+ * ZERO WIDTH JOINER does, and all are default-ignorable, so fonts draw nothing.
+ */
+
+const DIGITS = ['⁡', '⁢', '⁣', '⁤'] as const;
+const END = '⁠';
+const BASE = DIGITS.length;
+const FIRST_DIGIT = 0x20_61;
+
+const MARKER = /[⁡-⁤]+⁠/;
+const MARKERS = /[⁡-⁤]+⁠/g;
+
+/**
+ * Write a message id as an invisible marker.
+ * @param id - The id, a non-negative integer.
+ * @returns The marker, to be put in front of the formatted message.
+ */
+export function encodeMarker(id: number): string {
+  if (!Number.isSafeInteger(id) || id < 0) {
+    throw new RangeError(`a marker id is a non-negative integer, got ${id}`);
+  }
+  let digits = '';
+  let rest = id;
+  do {
+    digits = `${DIGITS[rest % BASE]}${digits}`;
+    rest = Math.floor(rest / BASE);
+  } while (rest > 0);
+  return `${digits}${END}`;
+}
+
+/**
+ * Prefix a formatted message with the marker of its id.
+ * @param text - The message as it will be shown.
+ * @param id - The id of the message.
+ * @returns The same text, with the invisible marker in front.
+ */
+export function markText(text: string, id: number): string {
+  return `${encodeMarker(id)}${text}`;
+}
+
+/**
+ * The ids of every message a string carries, in the order they appear.
+ * @param text - A text node's data or an attribute's value.
+ * @returns The ids; empty when the string holds no marker.
+ */
+export function readMarkers(text: string): number[] {
+  const ids: number[] = [];
+  for (const match of text.matchAll(MARKERS)) {
+    const marker = match[0];
+    let id = 0;
+    for (let index = 0; index < marker.length - 1; index++) {
+      id = id * BASE + (marker.codePointAt(index) ?? FIRST_DIGIT) - FIRST_DIGIT;
+    }
+    ids.push(id);
+  }
+  return ids;
+}
+
+/**
+ * Whether a string carries at least one marker.
+ * @param text - The string to look at.
+ * @returns True when a marker is present.
+ */
+export function hasMarker(text: string): boolean {
+  return MARKER.test(text);
+}
+
+/**
+ * The string with every marker removed, as it reads outside translate mode.
+ * @param text - A string that may carry markers.
+ * @returns The visible text only.
+ */
+export function stripMarkers(text: string): string {
+  return text.replaceAll(MARKERS, '');
+}

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);
+}