prosebook 0.0.1 → 0.2.0

package/src/tools/lock.ts

@@ -0,0 +1,95 @@
+/**
+ * Stale translations: a translation made from source text that has since changed.
+ *
+ * The lock records, per translation, a hash of the source it was made from and a hash of the
+ * translation itself. Editing the translation re-anchors it to the current source; editing only
+ * the source leaves the old anchor in place, which is what marks it stale. Nobody has to remember
+ * to flag anything: `prosebook status` lists what is stale, and `prosebook accept` re-anchors a
+ * translation that was still right.
+ *
+ * The lock also keeps the text behind each anchor, once per distinct text, so a stale translation
+ * can show its translator what changed rather than only what the source says now.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+
+import type { Catalog } from './catalog.ts';
+
+export interface Lock {
+  version: 2;
+  /** Source text by hash: every text some translation is anchored to. */
+  sources: Record<string, string>;
+  /** Per locale, per key: `<source hash>:<translation hash>`. */
+  translations: Record<string, Record<string, string>>;
+}
+
+export function hash(text: string): string {
+  return createHash('sha256').update(text).digest('hex').slice(0, 10);
+}
+
+export function emptyLock(): Lock {
+  return { version: 2, sources: {}, translations: {} };
+}
+
+/** The lock at `path`. A version 1 lock, which held only the translations, reads with no source texts. */
+export function readLock(path: string): Lock {
+  if (!existsSync(path)) return emptyLock();
+  const raw = JSON.parse(readFileSync(path, 'utf8')) as Partial<Lock> | Record<string, Record<string, string>>;
+  if ((raw as Partial<Lock>).version === 2) return { ...emptyLock(), ...(raw as Partial<Lock>) };
+  return { version: 2, sources: {}, translations: raw as Record<string, Record<string, string>> };
+}
+
+const sortedEntries = <T>(record: Record<string, T>) => Object.fromEntries(Object.entries(record).sort(([a], [b]) => (a < b ? -1 : 1)));
+
+export function serializeLock(lock: Lock): string {
+  const translations = Object.fromEntries(
+    Object.keys(lock.translations)
+      .sort()
+      .map((locale) => [locale, sortedEntries(lock.translations[locale]!)]),
+  );
+  return `${JSON.stringify({ version: 2, sources: sortedEntries(lock.sources), translations }, null, 2)}\n`;
+}
+
+export interface StaleTranslation {
+  /** The source the translation was made from, where the lock recorded it. */
+  was: string | undefined;
+  /** The source now. */
+  now: string;
+  /** The translation, made from `was`. */
+  translation: string;
+}
+
+export interface Reconciled {
+  lock: Lock;
+  /** Per locale, per key: the translations made from a source that has changed since. */
+  stale: Map<string, Map<string, StaleTranslation>>;
+}
+
+/**
+ * The lock brought up to date with the catalog, and what is stale. `accept` re-anchors the given
+ * translations (per locale, keys, or `true` for all of them) to the current source.
+ */
+export function reconcile(catalog: Catalog, previous: Lock, accept: Map<string, Set<string> | true> = new Map()): Reconciled {
+  const lock = emptyLock();
+  const stale = new Map<string, Map<string, StaleTranslation>>();
+  for (const message of catalog.messages) {
+    const source = hash(message.text);
+    for (const [locale, translation] of message.translations) {
+      const text = hash(translation.text);
+      const [anchor, recorded] = (previous.translations[locale]?.[message.key] ?? '').split(':');
+      const accepted = accept.get(locale);
+      const reanchor =
+        anchor === undefined || anchor === '' || recorded !== text || accepted === true || accepted?.has(message.key) === true;
+      const kept = reanchor ? source : anchor;
+      (lock.translations[locale] ??= {})[message.key] = `${kept}:${text}`;
+      const keptText = kept === source ? message.text : previous.sources[kept];
+      if (keptText !== undefined) lock.sources[kept] = keptText;
+      if (!reanchor && anchor !== source) {
+        let keys = stale.get(locale);
+        if (keys === undefined) stale.set(locale, (keys = new Map()));
+        keys.set(message.key, { was: keptText, now: message.text, translation: translation.text });
+      }
+    }
+  }
+  return { lock, stale };
+}

package/src/tools/mf1.ts

@@ -0,0 +1,246 @@
+/**
+ * The element tree written as MF1 (ICU MessageFormat) text, for `migrate`. A tree read from MF2 holds
+ * `Intl` options where MF1 holds skeletons, so each is written as the skeleton that parses back to the
+ * same options, or as the named style MF2's function was mapped from; where neither exists the
+ * message is reported rather than changed.
+ */
+import { isDateElement, isNumberElement, isTimeElement, parse, TYPE } from '@formatjs/icu-messageformat-parser';
+import type { DateElement, DateTimeSkeleton, NumberElement, NumberSkeleton, TimeElement } from '@formatjs/icu-messageformat-parser';
+
+import type { MessageFormatElement } from './icu.ts';
+import type { Mf2DateSkeleton, Mf2NumberSkeleton } from './mf2.ts';
+
+type Element = MessageFormatElement;
+
+export function toMf1(ast: Element[]): string {
+  return print(native(ast, undefined), false);
+}
+
+const CATEGORY_ORDER = ['zero', 'one', 'two', 'few', 'many', 'other'];
+
+/**
+ * Printed as a person would write it: `{n, plural, =0 {…} one {…} other {…}}`, exact arms first and
+ * `other` last. (formatjs's printer packs and reorders arms.)
+ */
+function print(elements: Element[], inPlural: boolean): string {
+  return elements
+    .map((el, i) => {
+      switch (el.type) {
+        case TYPE.literal:
+          return escape(el.value, inPlural, elements[i + 1] === undefined);
+        case TYPE.argument:
+          return `{${el.value}}`;
+        case TYPE.number:
+        case TYPE.date:
+        case TYPE.time: {
+          const kind = el.type === TYPE.number ? 'number' : el.type === TYPE.date ? 'date' : 'time';
+          const style = el.style;
+          if (style === null || style === undefined) return `{${el.value}, ${kind}}`;
+          if (typeof style === 'string') return `{${el.value}, ${kind}, ${style}}`;
+          const skeleton = 'tokens' in style ? style.tokens.map((t) => [t.stem, ...t.options].join('/')).join(' ') : style.pattern;
+          return `{${el.value}, ${kind}, ::${skeleton}}`;
+        }
+        case TYPE.pound:
+          return '#';
+        case TYPE.tag:
+          return `<${el.value}>${print(el.children, inPlural)}</${el.value}>`;
+        case TYPE.select:
+        case TYPE.plural: {
+          const arms = Object.entries(el.options);
+          const rank = (arm: string) => (arm.startsWith('=') ? -1 : arm === 'other' ? 99 : Math.max(0, CATEGORY_ORDER.indexOf(arm)));
+          if (el.type === TYPE.plural)
+            arms.sort(([a], [b]) => (rank(a) !== rank(b) ? rank(a) - rank(b) : Number(a.slice(1)) - Number(b.slice(1))));
+          else arms.sort(([a], [b]) => (a === 'other' ? 1 : 0) - (b === 'other' ? 1 : 0));
+          const head = el.type === TYPE.select ? 'select' : el.pluralType === 'ordinal' ? 'selectordinal' : 'plural';
+          const offset = el.type === TYPE.plural && el.offset !== 0 ? ` offset:${el.offset}` : '';
+          const body = arms.map(([arm, o]) => `${arm} {${print(o.value, el.type === TYPE.plural)}}`).join(' ');
+          return `{${el.value}, ${head},${offset} ${body}}`;
+        }
+        default:
+          return '';
+      }
+    })
+    .join('');
+}
+
+/**
+ * Literal text, quoted where ICU would read it as syntax. An apostrophe starts a quote only before a
+ * special character, so one before ordinary text (`don't`) stays single.
+ */
+function escape(text: string, inPlural: boolean, last: boolean): string {
+  const special = (c: string | undefined) => c === '{' || c === '}' || c === '<' || (inPlural && c === '#');
+  let out = '';
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!;
+    if (special(c)) out += `'${c}'`;
+    // Before the next placeholder or tag, a trailing apostrophe would quote its brace.
+    else if (c === "'") out += special(text[i + 1]) || text[i + 1] === "'" || (!last && i === text.length - 1) ? "''" : "'";
+    else out += c;
+  }
+  return out;
+}
+
+/** The tree with MF2 styles replaced by MF1 ones, and `#` where a plural prints its own value. */
+function native(elements: Element[], plural: { value: string; offset: number } | undefined): Element[] {
+  return elements.map((el): Element => {
+    if (isNumberElement(el)) {
+      if (plural?.offset === 0 && el.value === plural.value && plainNumber(el)) return { type: TYPE.pound };
+      return { ...el, style: numberStyle(el) };
+    }
+    if (isDateElement(el) || isTimeElement(el)) return dateElement(el);
+    if (el.type === TYPE.plural) {
+      const inner = { value: el.value, offset: el.offset };
+      return { ...el, options: Object.fromEntries(Object.entries(el.options).map(([k, o]) => [k, { value: native(o.value, inner) }])) };
+    }
+    // formatjs reads `#` as text inside a select, even one inside a plural.
+    if (el.type === TYPE.select)
+      return { ...el, options: Object.fromEntries(Object.entries(el.options).map(([k, o]) => [k, { value: native(o.value, undefined) }])) };
+    if (el.type === TYPE.tag) return { ...el, children: native(el.children, plural) };
+    return el;
+  });
+}
+
+function plainNumber(el: NumberElement): boolean {
+  const style = el.style;
+  return (
+    style === null || style === undefined || ('mf2' in Object(style) && Object.keys((style as NumberSkeleton).parsedOptions).length === 0)
+  );
+}
+
+function same(a: object, b: object): boolean {
+  const norm = (o: object) =>
+    JSON.stringify(
+      Object.entries(o)
+        .filter(([, v]) => v !== undefined)
+        .sort(([x], [y]) => x.localeCompare(y)),
+    );
+  return norm(a) === norm(b);
+}
+
+function numberStyle(el: NumberElement): NumberElement['style'] {
+  const style = el.style;
+  if (style === null || style === undefined || typeof style === 'string' || !('mf2' in style)) return style;
+  const options = (style as Mf2NumberSkeleton).parsedOptions as Record<string, unknown>;
+  if (Object.keys(options).length === 0) return null;
+  if (same(options, { maximumFractionDigits: 0 })) return 'integer';
+  if (same(options, { style: 'percent' })) return 'percent';
+  const skeleton = numberSkeleton(options);
+  const parsed = skeleton === undefined ? undefined : skeletonStyle(`{n, number, ::${skeleton}}`);
+  // `unit-width-*` sets both displays; `Intl` reads only the one its style uses.
+  const relevant = (o: Record<string, unknown>) => {
+    const { currencyDisplay, unitDisplay, ...rest } = o;
+    return { ...rest, ...(o.style === 'currency' ? { currencyDisplay } : {}), ...(o.style === 'unit' ? { unitDisplay } : {}) };
+  };
+  if (parsed === undefined || !same(relevant(parsed.parsedOptions as Record<string, unknown>), relevant(options)))
+    throw new Error(`{${el.value} ${mf2Text((style as Mf2NumberSkeleton).mf2)}} formats in a way no MF1 skeleton says`);
+  return parsed as NumberSkeleton;
+}
+
+function skeletonStyle(source: string): NumberSkeleton | DateTimeSkeleton | undefined {
+  try {
+    const el = parse(source, { shouldParseSkeletons: true })[0];
+    return el !== undefined && 'style' in el && typeof el.style === 'object' && el.style !== null ? el.style : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The ICU number skeleton for `Intl` options, as far as formatjs reads skeletons back. */
+function numberSkeleton(o: Record<string, unknown>): string | undefined {
+  const tokens: string[] = [];
+  if (o.style === 'percent') tokens.push('percent');
+  if (o.style === 'currency') tokens.push(`currency/${String(o.currency)}`);
+  if (o.style === 'unit') tokens.push(`unit/${String(o.unit)}`);
+  const width =
+    o.style === 'currency'
+      ? { narrowSymbol: 'unit-width-narrow', code: 'unit-width-short', name: 'unit-width-full-name' }[String(o.currencyDisplay)]
+      : o.style === 'unit'
+        ? { narrow: 'unit-width-narrow', short: 'unit-width-short', long: 'unit-width-full-name' }[String(o.unitDisplay)]
+        : undefined;
+  if (width !== undefined) tokens.push(width);
+  if (o.currencySign === 'accounting') tokens.push('sign-accounting');
+  const sign = { always: 'sign-always', exceptZero: 'sign-except-zero', never: 'sign-never' }[String(o.signDisplay)];
+  if (sign !== undefined) tokens.push(sign);
+  if (o.useGrouping === false) tokens.push('group-off');
+  if (typeof o.minimumIntegerDigits === 'number') tokens.push(`integer-width/*${'0'.repeat(o.minimumIntegerDigits)}`);
+
+  const minF = o.minimumFractionDigits as number | undefined;
+  const maxF = o.maximumFractionDigits as number | undefined;
+  let fraction: string | undefined;
+  if (minF !== undefined && maxF !== undefined) fraction = `.${'0'.repeat(minF)}${'#'.repeat(maxF - minF)}`;
+  else if (maxF !== undefined) fraction = maxF === 0 ? '.' : `.${'#'.repeat(maxF)}`;
+  else if (minF !== undefined) fraction = `.${'0'.repeat(minF)}*`;
+  const minS = o.minimumSignificantDigits as number | undefined;
+  const maxS = o.maximumSignificantDigits as number | undefined;
+  let significant: string | undefined;
+  if (minS !== undefined && maxS !== undefined) significant = `${'@'.repeat(minS)}${'#'.repeat(maxS - minS)}`;
+  else if (maxS !== undefined) significant = `@${'#'.repeat(maxS - 1)}`;
+  else if (minS !== undefined) significant = `${'@'.repeat(minS)}+`;
+  if (significant !== undefined)
+    significant += o.roundingPriority === 'morePrecision' ? 'r' : o.roundingPriority === 'lessPrecision' ? 's' : '';
+  if (fraction !== undefined)
+    tokens.push(fraction + (o.trailingZeroDisplay === 'stripIfInteger' ? '/w' : significant !== undefined ? `/${significant}` : ''));
+  else if (significant !== undefined) tokens.push(significant);
+
+  const mode = {
+    floor: 'rounding-mode-floor',
+    ceil: 'rounding-mode-ceiling',
+    trunc: 'rounding-mode-down',
+    expand: 'rounding-mode-up',
+    halfEven: 'rounding-mode-half-even',
+    halfTrunc: 'rounding-mode-half-down',
+    halfExpand: 'rounding-mode-half-up',
+  }[String(o.roundingMode)];
+  if (mode !== undefined) tokens.push(mode);
+  return tokens.length > 0 ? tokens.join(' ') : undefined;
+}
+
+/** MF2 date and time functions as the MF1 named style they were mapped from (see `dateFunction` in mf2.ts). */
+const NAMED: Record<string, readonly [TYPE.date | TYPE.time, string]> = {
+  'date length=short': [TYPE.date, 'short'],
+  date: [TYPE.date, 'medium'],
+  'date length=long': [TYPE.date, 'long'],
+  'date fields=year-month-day-weekday length=long': [TYPE.date, 'full'],
+  time: [TYPE.time, 'short'],
+  'time precision=second': [TYPE.time, 'medium'],
+  'time precision=second timeZoneStyle=short': [TYPE.time, 'long'],
+  'time precision=second timeZoneStyle=long': [TYPE.time, 'full'],
+};
+
+function dateElement(el: DateElement | TimeElement): Element {
+  const style = el.style;
+  if (typeof style !== 'object' || style === null || !('mf2' in style)) return el;
+  const fn = (style as Mf2DateSkeleton).mf2;
+  const named = NAMED[mf2Text(fn, true).slice(1)];
+  if (named !== undefined) return { type: named[0], value: el.value, style: named[1] };
+  const skeleton = dateSkeleton(style.parsedOptions);
+  const parsed = skeleton === undefined ? undefined : skeletonStyle(`{d, date, ::${skeleton}}`);
+  if (parsed === undefined || !same(parsed.parsedOptions, style.parsedOptions))
+    throw new Error(`{${el.value} ${mf2Text(fn)}} formats in a way no MF1 date skeleton says: use :date or :time with a length`);
+  return { type: TYPE.date, value: el.value, style: parsed as DateTimeSkeleton };
+}
+
+function dateSkeleton(o: Intl.DateTimeFormatOptions): string | undefined {
+  if (o.hour !== undefined || o.timeZone !== undefined || o.calendar !== undefined || o.hour12 !== undefined) return undefined;
+  const letters: Record<string, Record<string, string>> = {
+    weekday: { short: 'EEE', long: 'EEEE', narrow: 'EEEEE' },
+    year: { numeric: 'y', '2-digit': 'yy' },
+    month: { numeric: 'M', '2-digit': 'MM', short: 'MMM', long: 'MMMM', narrow: 'MMMMM' },
+    day: { numeric: 'd', '2-digit': 'dd' },
+  };
+  let out = '';
+  for (const [field, forms] of Object.entries(letters)) {
+    const value = o[field as keyof Intl.DateTimeFormatOptions];
+    if (value === undefined) continue;
+    const letter = forms[String(value)];
+    if (letter === undefined) return undefined;
+    out += letter;
+  }
+  return out === '' ? undefined : out;
+}
+
+function mf2Text(fn: { name: string; options: Record<string, string> }, sortOptions = false): string {
+  const options = Object.entries(fn.options);
+  if (sortOptions) options.sort(([a], [b]) => a.localeCompare(b));
+  return [`:${fn.name}`, ...options.map(([k, v]) => `${k}=${v}`)].join(' ');
+}