claude-translator 1.4.0 → 2.0.0

package/scripts/roles.mjs

@@ -0,0 +1,142 @@
+/**
+ * Element context — telling the translator WHAT a string is, not just what it says.
+ *
+ * The prompt has always ended rule 5 with "Headings stay headings; button labels stay
+ * short." That sentence was unenforceable: the model received `{ id, text }` and had no
+ * way to tell a <button> from a paragraph. Every string looked like prose.
+ *
+ * extract.mjs already knows the answer — it walks the DOM and has `node.tagName` in hand
+ * at the moment it records a unit. It simply threw it away. This module turns that tag
+ * into a short label the model can act on.
+ *
+ * ── Why a separate field, not a richer `kind` ────────────────────────────────
+ * build-locales.mjs switches on `seg.kind === 'block' | 'jsonld' | startsWith('attr:')`
+ * to decide how to escape a replacement. A value like 'block:button' would fall through
+ * to escHtml and print literal &lt;0&gt; placeholder tokens as visible text on every
+ * localized page — silent corruption that no test catches. So `kind` is untouched and
+ * `el` is new.
+ *
+ * ── Why this costs nothing ───────────────────────────────────────────────────
+ * Ordinary prose returns null and the field is omitted from the payload entirely. Only
+ * the strings where the answer changes the translation carry it.
+ */
+
+/**
+ * Block-level elements whose register genuinely differs from body copy.
+ *
+ * <a> is the interesting entry. It is an INLINE element in extract.mjs, so a link inside
+ * a sentence is absorbed into the surrounding block as a <0>…</0> placeholder and never
+ * recorded on its own. An <a> that DOES surface as its own unit is therefore a standalone
+ * link — a call to action or a nav item — which makes it a high-precision signal rather
+ * than noise.
+ */
+const BLOCK_ROLES = {
+  button: 'button',
+  a: 'button',
+  h1: 'heading',
+  h2: 'heading',
+  h3: 'heading',
+  h4: 'heading',
+  h5: 'heading',
+  h6: 'heading',
+  title: 'page title',
+  label: 'form label',
+  legend: 'form label',
+  summary: 'expander label',
+  th: 'table header',
+  figcaption: 'caption',
+  option: 'menu option',
+  optgroup: 'menu option',
+};
+
+/** Attribute-sourced strings. The attribute name IS the role. */
+const ATTR_ROLES = {
+  'attr:alt': 'image alt text',
+  'attr:placeholder': 'input placeholder',
+  'attr:aria-label': 'accessible label',
+  'attr:aria-description': 'accessible description',
+  'attr:title': 'tooltip',
+};
+
+/**
+ * Meta tags carry their key in `el` as `meta:<key>`, because `kind` flattens every one of
+ * them to `attr:content` and a description behaves nothing like an og:title.
+ */
+const META_ROLES = {
+  description: 'meta description',
+  'og:description': 'social share description',
+  'twitter:description': 'social share description',
+  'og:title': 'social share title',
+  'twitter:title': 'social share title',
+  'og:site_name': 'site name',
+  'og:image:alt': 'image alt text',
+  'twitter:image:alt': 'image alt text',
+};
+
+/**
+ * The label for one unit, or null when it is ordinary prose.
+ *
+ * @param {{kind?: string, el?: string|null}} unit  a record from i18n/source.json
+ */
+export function roleOf(unit) {
+  if (!unit || typeof unit !== 'object') return null;
+  const { kind, el } = unit;
+
+  // A conflicting element cleared the hint at extraction time. Saying nothing is correct
+  // here — a confident wrong answer is worse than no answer.
+  if (el === null || el === undefined) {
+    return kind === 'jsonld' ? 'structured data' : null;
+  }
+
+  if (typeof el === 'string' && el.startsWith('meta:')) {
+    return META_ROLES[el.slice(5)] ?? 'page metadata';
+  }
+
+  if (typeof kind === 'string' && kind.startsWith('attr:')) {
+    return ATTR_ROLES[kind] ?? null;
+  }
+
+  if (kind === 'jsonld') return 'structured data';
+
+  return BLOCK_ROLES[el] ?? null;
+}
+
+/**
+ * The guidance block appended to the system prompt, listing only the roles actually
+ * present in this batch. Empty string when the batch is all prose, so a run that
+ * translates nothing but paragraphs pays not a single extra token.
+ */
+export function rolePrompt(roles) {
+  const present = [...new Set(roles.filter(Boolean))].sort();
+  if (!present.length) return '';
+
+  const ADVICE = {
+    button: 'A control the user clicks. Keep it at or near the source length — it sits in a fixed-width box. Use whatever construction your language uses on buttons, which is often not the imperative: an infinitive, a verbal noun, or a bare noun may all read better than a literal command. No final period.',
+    'form label': 'Names a field. Short, nominal, no final period.',
+    'expander label': 'A short clickable summary. Keep it terse.',
+    heading: 'A headline. Keep it headline-shaped and roughly the source length; do not expand it into a sentence.',
+    'page title': 'The browser tab and search-result title. Under about 60 characters if the language allows.',
+    'meta description': 'Search-result copy. One or two sentences, under about 155 characters, written to be read in a results page.',
+    'social share title': 'A share-card headline. Short and concrete.',
+    'social share description': 'A share-card summary. One sentence.',
+    'image alt text': 'Describes an image for someone who cannot see it. Plain and factual, no "image of".',
+    'input placeholder': 'Example text inside an empty field. Very short.',
+    'accessible label': 'Read aloud by a screen reader. Say what the control does.',
+    'accessible description': 'Extra screen-reader detail. One short phrase.',
+    tooltip: 'A hover hint. One short phrase.',
+    'table header': 'A column heading. Very short, nominal.',
+    caption: 'A figure caption. One short sentence.',
+    'menu option': 'One choice in a dropdown. Very short.',
+    'site name': 'The name of the site. Usually left unchanged.',
+    'page metadata': 'Metadata, not body copy. Keep it compact.',
+    'structured data': 'A search-engine structured-data value. Plain text, no markup, no added punctuation.',
+  };
+
+  return [
+    `CONTEXT`,
+    `Some items carry an "el" field naming what the string is on the page. It is not part`,
+    `of the text and must not be translated or echoed. Where it appears, honour it:`,
+    ...present.map((r) => `   - ${r}: ${ADVICE[r] ?? 'Keep the register appropriate to this element.'}`),
+    `Items with no "el" field are body copy — translate them normally.`,
+  ].join('\n');
+}

package/scripts/roles.test.mjs

@@ -0,0 +1,140 @@
+/**
+ * Element-context contract tests. No network, no key, no model.
+ *
+ * The prompt has always said "button labels stay short" while the model had no way to
+ * know what a button was. These tests pin the mapping that finally makes that actionable,
+ * and — more importantly — pin the cases where the tool must say NOTHING rather than
+ * guess.
+ */
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { roleOf, rolePrompt } from './roles.mjs';
+
+const unit = (el, kind = 'block') => ({ kind, el });
+
+// ── Controls ─────────────────────────────────────────────────────────────────
+
+test('a button is a button', () => {
+  assert.equal(roleOf(unit('button')), 'button');
+});
+
+test('a standalone <a> is treated as a call to action', () => {
+  // <a> is INLINE in extract.mjs, so a link inside a sentence is absorbed into the
+  // surrounding block as a placeholder and never recorded on its own. An <a> that DOES
+  // surface as its own unit is a standalone link — a CTA or a nav item.
+  assert.equal(roleOf(unit('a')), 'button');
+});
+
+test('headings at every level map to one role', () => {
+  for (const h of ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']) {
+    assert.equal(roleOf(unit(h)), 'heading', h);
+  }
+});
+
+test('form and table furniture get their own roles', () => {
+  assert.equal(roleOf(unit('label')), 'form label');
+  assert.equal(roleOf(unit('legend')), 'form label');
+  assert.equal(roleOf(unit('summary')), 'expander label');
+  assert.equal(roleOf(unit('th')), 'table header');
+  assert.equal(roleOf(unit('figcaption')), 'caption');
+  assert.equal(roleOf(unit('option')), 'menu option');
+  assert.equal(roleOf(unit('title')), 'page title');
+});
+
+// ── Prose says nothing ───────────────────────────────────────────────────────
+
+test('ordinary prose returns null so the field is omitted entirely', () => {
+  for (const el of ['p', 'div', 'span', 'li', 'td', 'blockquote', 'section']) {
+    assert.equal(roleOf(unit(el)), null, el);
+  }
+});
+
+test('an unknown element is prose, not a guess', () => {
+  assert.equal(roleOf(unit('marquee')), null);
+  assert.equal(roleOf(unit('my-web-component')), null);
+});
+
+// ── The collision case ───────────────────────────────────────────────────────
+
+test('a cleared element yields no hint at all', () => {
+  // extract.mjs sets el to null when the same string appears as both a button and a
+  // paragraph. Saying nothing is correct: a confident wrong answer is worse than none.
+  assert.equal(roleOf(unit(null)), null);
+  assert.equal(roleOf({ kind: 'block' }), null, 'a missing el behaves like a cleared one');
+});
+
+// ── Attributes ───────────────────────────────────────────────────────────────
+
+test('attribute roles come from the attribute, not the element', () => {
+  assert.equal(roleOf({ kind: 'attr:alt', el: 'img' }), 'image alt text');
+  assert.equal(roleOf({ kind: 'attr:placeholder', el: 'input' }), 'input placeholder');
+  assert.equal(roleOf({ kind: 'attr:aria-label', el: 'button' }), 'accessible label');
+  assert.equal(roleOf({ kind: 'attr:title', el: 'abbr' }), 'tooltip');
+});
+
+test('an unmapped attribute is silent rather than mislabelled', () => {
+  assert.equal(roleOf({ kind: 'attr:data-thing', el: 'div' }), null);
+});
+
+// ── Meta tags ────────────────────────────────────────────────────────────────
+
+test('meta tags are distinguished by key, which kind alone cannot express', () => {
+  // Every meta tag arrives as kind "attr:content"; the key travels in el.
+  assert.equal(roleOf({ kind: 'attr:content', el: 'meta:description' }), 'meta description');
+  assert.equal(roleOf({ kind: 'attr:content', el: 'meta:og:title' }), 'social share title');
+  assert.equal(roleOf({ kind: 'attr:content', el: 'meta:og:description' }), 'social share description');
+  assert.equal(roleOf({ kind: 'attr:content', el: 'meta:og:image:alt' }), 'image alt text');
+});
+
+test('an unrecognised meta key still says "not body copy"', () => {
+  assert.equal(roleOf({ kind: 'attr:content', el: 'meta:custom:thing' }), 'page metadata');
+});
+
+// ── JSON-LD ──────────────────────────────────────────────────────────────────
+
+test('structured data is labelled even though it has no element', () => {
+  assert.equal(roleOf({ kind: 'jsonld', el: null }), 'structured data');
+});
+
+// ── Defensive ────────────────────────────────────────────────────────────────
+
+test('junk input never throws', () => {
+  for (const junk of [null, undefined, 'string', 42, []]) {
+    assert.doesNotThrow(() => roleOf(junk));
+  }
+  assert.equal(roleOf(null), null);
+});
+
+// ── The prompt block ─────────────────────────────────────────────────────────
+
+test('a batch of pure prose produces no prompt text and costs no tokens', () => {
+  assert.equal(rolePrompt([]), '');
+  assert.equal(rolePrompt([null, null, undefined]), '');
+});
+
+test('only the roles present in the batch are described', () => {
+  const p = rolePrompt(['button', 'heading']);
+  assert.match(p, /- button:/);
+  assert.match(p, /- heading:/);
+  assert.ok(!/image alt text/.test(p), 'roles absent from the batch must not be described');
+});
+
+test('duplicates collapse, so forty buttons describe the role once', () => {
+  const p = rolePrompt(Array(40).fill('button'));
+  assert.equal((p.match(/- button:/g) ?? []).length, 1);
+});
+
+test('the button advice does not demand the imperative', () => {
+  // Languages differ: German UI prefers a verbal noun, French the infinitive. Ordering a
+  // literal imperative everywhere is precisely the defect this feature exists to avoid.
+  const p = rolePrompt(['button']);
+  assert.match(p, /not the imperative/i);
+  assert.match(p, /fixed-width/);
+});
+
+test('the prompt tells the model el is metadata, not text to translate', () => {
+  const p = rolePrompt(['button']);
+  assert.match(p, /must not be translated or echoed/);
+});

package/scripts/tqa-score.mjs

@@ -0,0 +1,127 @@
+/**
+ * TQA scoring primitives — the parts with no I/O, no network and no config, so they can
+ * be tested directly. tqa.mjs owns the run; this file owns the arithmetic and the
+ * sampling, which are the parts a reader is entitled to check.
+ */
+
+/**
+ * Severity weights. These are the conventional MQM values — minor 1, major 5,
+ * critical 10 — kept rather than tuned, so a score here means the same thing it means
+ * in any other MQM report.
+ */
+export const WEIGHT = { minor: 1, major: 5, critical: 10 };
+
+/**
+ * The typology offered to the judge. Deliberately short: a long taxonomy produces
+ * category-shopping and inconsistent labelling between runs, and the categories that
+ * matter for web localization are these.
+ */
+export const CATEGORIES = [
+  'accuracy/mistranslation',
+  'accuracy/omission',
+  'accuracy/addition',
+  'accuracy/untranslated',
+  'fluency/grammar',
+  'fluency/spelling',
+  'fluency/register',
+  'fluency/awkward',
+  'terminology/inconsistent',
+  'terminology/glossary',
+  'locale/number-date-currency',
+  'style/tone',
+  'markup/placeholder',
+];
+
+// ── Deterministic sampling ───────────────────────────────────────────────────
+
+/** mulberry32 — a small seeded PRNG, so a reported score can be reproduced exactly. */
+export function rng(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+export const words = (s) => (String(s).trim().match(/\S+/g) ?? []).length;
+
+/**
+ * Stratified sample, weighted by how often a unit appears on the site.
+ *
+ * A uniform sample over-represents the long tail of one-off strings and under-represents
+ * the header, footer and nav that every visitor reads on every page. `count` is already
+ * recorded by extract.mjs, so weighting by it costs nothing and makes the score reflect
+ * what people actually see. Strata are frequency terciles, sampled proportionally.
+ */
+export function stratifiedSample(units, n, seed) {
+  if (units.length <= n) return units.slice();
+  const rand = rng(seed);
+  const sorted = units.slice().sort((a, b) => (b.count ?? 1) - (a.count ?? 1));
+  const third = Math.ceil(sorted.length / 3);
+  const strata = [sorted.slice(0, third), sorted.slice(third, third * 2), sorted.slice(third * 2)];
+
+  const picked = [];
+  strata.forEach((stratum, i) => {
+    if (!stratum.length) return;
+    // The most-repeated third gets half the sample; the rest split the remainder.
+    const share = i === 0 ? 0.5 : 0.25;
+    const want = Math.min(stratum.length, Math.max(1, Math.round(n * share)));
+    const pool = stratum.slice();
+    for (let k = 0; k < want && pool.length; k++) {
+      picked.push(pool.splice(Math.floor(rand() * pool.length), 1)[0]);
+    }
+  });
+  return picked.slice(0, n);
+}
+
+
+/**
+ * MQM score for a set of assessed units.
+ */
+export function score(assessed) {
+  const totalWords = assessed.reduce((n, a) => n + a.words, 0);
+  let penalty = 0;
+  const byCategory = {};
+  const bySeverity = { minor: 0, major: 0, critical: 0 };
+
+  for (const a of assessed) {
+    for (const e of a.errors) {
+      penalty += WEIGHT[e.severity];
+      bySeverity[e.severity]++;
+      byCategory[e.category] = (byCategory[e.category] ?? 0) + 1;
+    }
+  }
+  const mqm = totalWords ? 100 - (penalty / totalWords) * 100 : 100;
+  return {
+    mqm: Math.round(mqm * 100) / 100,
+    penalty,
+    totalWords,
+    unitsAssessed: assessed.length,
+    unitsClean: assessed.filter((a) => a.errors.length === 0).length,
+    bySeverity,
+    byCategory,
+  };
+}
+
+
+/** Parse the judge's per-unit payload. Anything unreadable is dropped, never guessed. */
+export function parseErrors(raw) {
+  if (typeof raw !== 'string') return null;
+  const text = raw.trim();
+  if (!text) return [];
+  try {
+    const parsed = JSON.parse(text);
+    if (!Array.isArray(parsed)) return null;
+    return parsed
+      .map((e) => ({
+        category: String(e.c ?? e.category ?? '').trim(),
+        severity: String(e.s ?? e.severity ?? '').trim().toLowerCase(),
+        note: String(e.n ?? e.note ?? '').trim(),
+      }))
+      .filter((e) => WEIGHT[e.severity] !== undefined);
+  } catch {
+    return null;
+  }
+}

package/scripts/tqa-score.test.mjs

@@ -0,0 +1,144 @@
+/**
+ * TQA scoring contract tests. No network, no key, no model.
+ *
+ * A published quality score is only worth what its arithmetic is worth, so the MQM
+ * formula, the sampling determinism and the judge-failure handling are all pinned here.
+ */
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { WEIGHT, rng, words, stratifiedSample, parseErrors, score } from './tqa-score.mjs';
+
+const unit = (n, errors = []) => ({ words: n, errors });
+
+// ── MQM arithmetic ───────────────────────────────────────────────────────────
+
+test('a clean sample scores 100', () => {
+  const r = score([unit(50), unit(50)]);
+  assert.equal(r.mqm, 100);
+  assert.equal(r.penalty, 0);
+  assert.equal(r.unitsClean, 2);
+});
+
+test('severity weights are the conventional MQM values', () => {
+  assert.deepEqual(WEIGHT, { minor: 1, major: 5, critical: 10 });
+});
+
+test('the score is penalty per 100 words', () => {
+  // one major (5 points) over 100 words = 5 points per 100 words = 95.
+  const r = score([unit(100, [{ category: 'accuracy/mistranslation', severity: 'major' }])]);
+  assert.equal(r.mqm, 95);
+
+  // the same error over 500 words is a fifth of the penalty density.
+  const r2 = score([unit(500, [{ category: 'accuracy/mistranslation', severity: 'major' }])]);
+  assert.equal(r2.mqm, 99);
+});
+
+test('a critical error costs ten times a minor one', () => {
+  const minor = score([unit(100, [{ category: 'fluency/grammar', severity: 'minor' }])]);
+  const critical = score([unit(100, [{ category: 'accuracy/mistranslation', severity: 'critical' }])]);
+  assert.equal(100 - minor.mqm, 1);
+  assert.equal(100 - critical.mqm, 10);
+});
+
+test('errors are counted by severity and category', () => {
+  const r = score([
+    unit(100, [
+      { category: 'fluency/grammar', severity: 'minor' },
+      { category: 'fluency/grammar', severity: 'major' },
+    ]),
+    unit(100, [{ category: 'terminology/glossary', severity: 'critical' }]),
+  ]);
+  assert.deepEqual(r.bySeverity, { minor: 1, major: 1, critical: 1 });
+  assert.deepEqual(r.byCategory, { 'fluency/grammar': 2, 'terminology/glossary': 1 });
+  assert.equal(r.unitsClean, 0);
+});
+
+test('an empty assessment scores 100 rather than dividing by zero', () => {
+  const r = score([]);
+  assert.equal(r.mqm, 100);
+  assert.equal(r.totalWords, 0);
+});
+
+// ── Sampling ─────────────────────────────────────────────────────────────────
+
+const pool = (n) => Array.from({ length: n }, (_, i) => ({ hash: `h${i}`, count: n - i }));
+
+test('sampling is deterministic for a given seed', () => {
+  const a = stratifiedSample(pool(300), 50, 42).map((u) => u.hash);
+  const b = stratifiedSample(pool(300), 50, 42).map((u) => u.hash);
+  assert.deepEqual(a, b, 'the same seed must reproduce the same sample');
+});
+
+test('a different seed gives a different sample', () => {
+  const a = stratifiedSample(pool(300), 50, 1).map((u) => u.hash);
+  const b = stratifiedSample(pool(300), 50, 2).map((u) => u.hash);
+  assert.notDeepEqual(a, b);
+});
+
+test('a pool smaller than the sample is returned whole', () => {
+  assert.equal(stratifiedSample(pool(10), 100, 1).length, 10);
+});
+
+test('the sample never exceeds the requested size', () => {
+  assert.equal(stratifiedSample(pool(1000), 100, 1).length, 100);
+});
+
+test('frequent strings are over-represented, because visitors read them more', () => {
+  // pool(300) has count descending, so the top third is the most-repeated third.
+  const picked = stratifiedSample(pool(300), 90, 7);
+  const fromTopThird = picked.filter((u) => Number(u.hash.slice(1)) < 100).length;
+  assert.ok(fromTopThird > 30, `expected the top third to be over-sampled, got ${fromTopThird}/90`);
+});
+
+test('the PRNG is stable across runs', () => {
+  const a = [rng(123)(), rng(123)(), rng(123)()];
+  assert.equal(a[0], a[1]);
+  assert.equal(a[1], a[2]);
+});
+
+// ── Word counting ────────────────────────────────────────────────────────────
+
+test('word counting ignores surrounding whitespace', () => {
+  assert.equal(words('  one two   three  '), 3);
+  assert.equal(words(''), 0);
+  assert.equal(words('single'), 1);
+});
+
+// ── Judge output parsing ─────────────────────────────────────────────────────
+
+test('an empty error list parses as clean', () => {
+  assert.deepEqual(parseErrors('[]'), []);
+  assert.deepEqual(parseErrors('  '), []);
+});
+
+test('short and long field names both parse', () => {
+  const short = parseErrors('[{"c":"fluency/grammar","s":"minor","n":"agreement"}]');
+  assert.equal(short.length, 1);
+  assert.equal(short[0].category, 'fluency/grammar');
+  assert.equal(short[0].severity, 'minor');
+
+  const long = parseErrors('[{"category":"fluency/grammar","severity":"major","note":"x"}]');
+  assert.equal(long[0].severity, 'major');
+});
+
+test('an unknown severity is dropped rather than scored', () => {
+  const r = parseErrors('[{"c":"fluency/grammar","s":"catastrophic"}]');
+  assert.deepEqual(r, [], 'a severity with no weight cannot be scored, so it is not counted');
+});
+
+test('unreadable judge output is null, NOT an empty list', () => {
+  // This distinction is load-bearing. Treating a failed judgement as "no errors found"
+  // would inflate the score every time the judge failed — exactly backwards.
+  assert.equal(parseErrors('not json'), null);
+  assert.equal(parseErrors('{"not":"an array"}'), null);
+  assert.equal(parseErrors(undefined), null);
+  assert.equal(parseErrors(null), null);
+});
+
+test('severity casing from the model is normalised', () => {
+  const r = parseErrors('[{"c":"fluency/grammar","s":"MAJOR"}]');
+  assert.equal(r.length, 1);
+  assert.equal(r[0].severity, 'major');
+});