claude-translator 1.3.0 → 2.0.0

package/scripts/format-locale.test.mjs

@@ -0,0 +1,171 @@
+/**
+ * Locale-formatting contract tests. No network, no key, no model.
+ *
+ * The "must not touch" block is the important half. Rewriting a version number, a time
+ * or an IP address into a localised decimal is worse than doing nothing at all, and it
+ * would ship silently — the markup would still be byte-identical and every other gate
+ * would pass.
+ */
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { formatText, intlLocale } from './format-locale.mjs';
+
+const fmt = (text, locale, opts) => formatText(text, locale, opts).text;
+/** Intl uses NBSP/narrow-NBSP; normalise so assertions stay readable. */
+const norm = (s) => s.replace(/[  ]/g, ' ');
+
+// ── Grouped numbers ──────────────────────────────────────────────────────────
+
+test('grouped numbers take the target locale separators', () => {
+  assert.equal(norm(fmt('We processed 1,234,567 files', 'de')), 'We processed 1.234.567 files');
+  assert.equal(norm(fmt('We processed 1,234,567 files', 'fr')), 'We processed 1 234 567 files');
+  assert.equal(norm(fmt('We processed 1,234,567 files', 'en')), 'We processed 1,234,567 files');
+});
+
+test('a grouped decimal keeps its value and its precision', () => {
+  assert.equal(norm(fmt('1,234.50 units', 'de')), '1.234,50 units');
+  assert.equal(norm(fmt('1,234.5 units', 'de')), '1.234,5 units');
+});
+
+test('an ungrouped number is left alone — there is no convention to apply', () => {
+  assert.equal(fmt('We support 50 languages', 'de'), 'We support 50 languages');
+  assert.equal(fmt('Founded in 2026', 'de'), 'Founded in 2026');
+  assert.equal(fmt('Page 7', 'fr'), 'Page 7');
+});
+
+// ── Currency: formatted, never converted ─────────────────────────────────────
+
+test('currency symbol placement follows the locale, value unchanged', () => {
+  assert.equal(norm(fmt('$5', 'fr')), '5,00 $US');
+  assert.equal(norm(fmt('$1,234.50', 'de')), '1.234,50 $');
+  assert.match(norm(fmt('$5', 'en')), /^\$5\.00$/);
+});
+
+test('the numeric value of a price is never altered', () => {
+  for (const locale of ['de', 'fr', 'ja', 'es', 'ar']) {
+    const out = fmt('$49', locale);
+    assert.ok(/49/.test(out), `${locale}: 49 must survive, got ${out}`);
+    assert.ok(!/4[0-8](\D|$)/.test(out.replace(/49/g, '')), `${locale}: no other amount may appear`);
+  }
+});
+
+test('the currency is held constant — no conversion, ever', () => {
+  const out = norm(fmt('$100', 'de'));
+  assert.ok(!out.includes('€'), `must not become euros, got ${out}`);
+  assert.ok(out.includes('$'), `must stay dollars, got ${out}`);
+});
+
+test('a trailing ISO currency code is recognised', () => {
+  assert.equal(norm(fmt('1,500 USD', 'de')), '1.500,00 $');
+});
+
+test('currency formatting can be switched off', () => {
+  assert.equal(fmt('$1,234.50', 'de', { currency: 'off', numbers: false }), '$1,234.50');
+});
+
+// ── Percent ──────────────────────────────────────────────────────────────────
+
+test('percent spacing follows the locale', () => {
+  assert.equal(norm(fmt('Save 50%', 'fr')), 'Save 50 %');
+  assert.equal(norm(fmt('Save 50%', 'en')), 'Save 50%');
+  assert.equal(norm(fmt('Save 12.5%', 'de')), 'Save 12,5 %');
+});
+
+// ── Must not touch ───────────────────────────────────────────────────────────
+
+test('semantic version numbers are left alone', () => {
+  for (const s of ['Requires Node 20.5.1', 'Version 1.2.3 is out', 'v2.0 ships today']) {
+    assert.equal(fmt(s, 'de'), s, s);
+  }
+});
+
+test('times are left alone', () => {
+  for (const s of ['Opens at 10:30', 'Between 9:00 and 17:45']) {
+    assert.equal(fmt(s, 'de'), s, s);
+  }
+});
+
+test('IP addresses are left alone', () => {
+  assert.equal(fmt('Connect to 192.168.1.1 now', 'de'), 'Connect to 192.168.1.1 now');
+});
+
+test('ISO dates are left alone', () => {
+  assert.equal(fmt('Released 2026-08-29', 'de'), 'Released 2026-08-29');
+});
+
+test('phone numbers are left alone', () => {
+  for (const s of ['Call +1-800-555-0199', 'Call 1-800-555-0199']) {
+    assert.equal(fmt(s, 'de'), s, s);
+  }
+});
+
+test('fractions and ratios are left alone', () => {
+  assert.equal(fmt('A 1/2 scale model', 'de'), 'A 1/2 scale model');
+});
+
+test('file sizes without grouping are left alone', () => {
+  assert.equal(fmt('Upload up to 10 MB', 'de'), 'Upload up to 10 MB');
+  assert.equal(fmt('1 GB of storage', 'fr'), '1 GB of storage');
+});
+
+test('placeholders are never entered or altered', () => {
+  const src = 'Save <0>1,234</0> files and <1/> more';
+  const out = fmt(src, 'de');
+  assert.ok(out.includes('<0>'), 'opening placeholder survives');
+  assert.ok(out.includes('</0>'), 'closing placeholder survives');
+  assert.ok(out.includes('<1/>'), 'self-closing placeholder survives');
+  assert.equal((out.match(/<\/?\d+\/?>/g) ?? []).length, 3);
+});
+
+// ── Reporting ────────────────────────────────────────────────────────────────
+
+test('monetary amounts are reported for human review', () => {
+  const { money } = formatText('Plans from $9 to $99 per month', 'de');
+  assert.equal(money.length, 2);
+  assert.deepEqual(money.map((m) => m.value), [9, 99]);
+  assert.ok(money.every((m) => m.currency === 'USD'));
+});
+
+test('changes are itemised so a build can show its work', () => {
+  const { changes } = formatText('1,000 items at 50%', 'de');
+  assert.ok(changes.some((c) => c.kind === 'number'));
+  assert.ok(changes.some((c) => c.kind === 'percent'));
+});
+
+test('a string with nothing to format is returned byte-identical', () => {
+  const src = 'Translate your website into any language';
+  const { text, changes, money } = formatText(src, 'de');
+  assert.equal(text, src);
+  assert.equal(changes.length, 0);
+  assert.equal(money.length, 0);
+});
+
+test('empty and non-string input is survivable', () => {
+  assert.equal(formatText('', 'de').text, '');
+  assert.equal(formatText(null, 'de').text, null);
+  assert.equal(formatText(undefined, 'de').text, undefined);
+});
+
+// ── Locale tag ───────────────────────────────────────────────────────────────
+
+test('Intl gets the hreflang tag, not the URL path code', () => {
+  assert.equal(intlLocale({ hreflang: 'pt-BR', pathCode: 'pt-br' }), 'pt-BR');
+  assert.equal(intlLocale({ hreflang: 'zh-Hant', pathCode: 'zh-tw' }), 'zh-Hant');
+  assert.equal(intlLocale({ pathCode: 'es' }), 'es');
+});
+
+test('an unknown locale degrades to leaving text alone, never to a crash', () => {
+  const out = formatText('1,234 items', 'not-a-locale');
+  assert.equal(typeof out.text, 'string');
+});
+
+test('Spanish does not group four-digit numbers, but German does — this is not a bug', () => {
+  // CLDR minimumGroupingDigits=2 for es. "1234,50" is correct Spanish and "1.234,50" is
+  // correct German for the same amount. This looked like a lost separator during
+  // development and is the exact thing a future reader will try to "fix".
+  assert.equal(norm(fmt('$1,234.50', 'es')), '1234,50 US$');
+  assert.equal(norm(fmt('$1,234.50', 'de')), '1.234,50 $');
+  assert.equal(norm(fmt('12,345 items', 'es')), '12.345 items', 'five digits DO group in Spanish');
+});

package/scripts/glossary.mjs

@@ -0,0 +1,229 @@
+/**
+ * Glossary — terminology consistency and brand protection.
+ *
+ * Two questions this answers that `doNotTranslate` could not:
+ *
+ *   1. "Dashboard" must be "Panel de control" every time it appears, including inside
+ *      sentences that are otherwise all different. The translation memory already keeps
+ *      IDENTICAL strings consistent — it is keyed by the hash of the whole unit — but a
+ *      term inside varying sentences lands in different units, different batches, and
+ *      different stateless requests. Nothing compared them. A term base does.
+ *
+ *   2. "Apple" the company must survive; "apple" the fruit must be translated. The old
+ *      list could not express the difference: it was a flat array of strings, matched
+ *      against the WHOLE trimmed unit and pasted into one prompt line. Case sensitivity
+ *      plus word boundaries is the whole answer, and it needs a per-term flag.
+ *
+ * ── Shape ────────────────────────────────────────────────────────────────────
+ * Deliberately the same four fields the managed ConveyThis product stores per glossary
+ * row (rule / source_text / translate_text / target_language), so a glossary can move
+ * between the two without a translation layer.
+ *
+ *   { "source": "Dashboard", "rule": "translate",
+ *     "targets": { "es": "Panel de control", "de": "Dashboard" } }
+ *   { "source": "Apple",     "rule": "keep", "matchCase": true }
+ *
+ * `rule: "keep"` means leave it in the source language. `rule: "translate"` with
+ * `targets` pins the wording per locale; a locale with no entry in `targets` is simply
+ * not constrained, which is the honest default for a term nobody has decided yet.
+ *
+ * ── Why matching is conservative ─────────────────────────────────────────────
+ * Every match here becomes either a prompt instruction or a compliance finding, and
+ * `references/quality-review.md` is unambiguous that a heuristic which over-flags is
+ * worse than no heuristic. So: word boundaries always, case-sensitivity opt-in per term,
+ * and longest-term-first so "Acme Cloud Inc" wins over "Acme".
+ */
+
+import { readFileSync, existsSync } from 'fs';
+
+/** Unicode-aware-ish word boundary: the char before/after a term must not be a letter,
+ *  digit or underscore. Built by hand because JS \b is ASCII-only, so "Straße" would
+ *  boundary wrongly against a following accented letter. */
+const WORDISH = /[\p{L}\p{N}_]/u;
+
+const isWordish = (ch) => ch !== undefined && WORDISH.test(ch);
+
+/**
+ * Normalise one raw entry. Returns null for anything unusable rather than throwing,
+ * because a single malformed row must not take a 40-locale run down with it — the
+ * caller reports the count of skipped rows instead.
+ */
+function normalise(entry, index, problems) {
+  if (!entry || typeof entry !== 'object') {
+    problems.push(`entry ${index}: not an object`);
+    return null;
+  }
+  const source = typeof entry.source === 'string' ? entry.source.trim() : '';
+  if (!source) {
+    problems.push(`entry ${index}: missing "source"`);
+    return null;
+  }
+
+  const rule = entry.rule ?? 'translate';
+  if (rule !== 'keep' && rule !== 'translate') {
+    problems.push(`entry ${index} ("${source}"): rule must be "keep" or "translate", got "${rule}"`);
+    return null;
+  }
+
+  const targets = {};
+  if (entry.targets && typeof entry.targets === 'object') {
+    for (const [lang, value] of Object.entries(entry.targets)) {
+      if (typeof value === 'string' && value.trim()) targets[lang] = value.trim();
+    }
+  }
+  if (rule === 'translate' && Object.keys(targets).length === 0) {
+    // Not an error: a term listed with no targets yet is still worth tracking for
+    // consistency reporting. It just cannot constrain anything.
+    problems.push(`entry ${index} ("${source}"): rule "translate" with no targets — ignored`);
+    return null;
+  }
+
+  return {
+    source,
+    rule,
+    targets,
+    // Brands are the case-sensitive case, so "keep" defaults to case-sensitive and
+    // "translate" does not. Either can be overridden explicitly.
+    matchCase: entry.matchCase ?? rule === 'keep',
+    note: typeof entry.note === 'string' ? entry.note : null,
+  };
+}
+
+/**
+ * Load and validate. Accepts an array (inline in i18n.config.json) or a path to a JSON
+ * file — the same dual form `locales` already takes.
+ */
+export function loadGlossary(src, root, resolvePath) {
+  if (!src) return { terms: [], problems: [] };
+
+  let rawEntries = src;
+  if (typeof src === 'string') {
+    const p = resolvePath(root, src);
+    if (!existsSync(p)) {
+      console.error(`config.glossary points at ${p}, which does not exist`);
+      process.exit(1);
+    }
+    try {
+      rawEntries = JSON.parse(readFileSync(p, 'utf8'));
+    } catch (err) {
+      console.error(`config.glossary: ${p} is not valid JSON — ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  if (!Array.isArray(rawEntries)) {
+    console.error('config.glossary must be an array, or a path to a JSON file containing one');
+    process.exit(1);
+  }
+
+  const problems = [];
+  const terms = rawEntries.map((e, i) => normalise(e, i, problems)).filter(Boolean);
+
+  // Longest first, so "Acme Cloud Inc" is matched and consumed before "Acme".
+  terms.sort((a, b) => b.source.length - a.source.length);
+  return { terms, problems };
+}
+
+/**
+ * Does `text` contain `term` as a whole word?
+ *
+ * Case-insensitive matching still requires the boundary check, so "apple" does not
+ * match inside "pineapple" — the false positive that would otherwise make every
+ * fruit-adjacent sentence look like a brand violation.
+ */
+export function containsTerm(text, term) {
+  if (!text || !term?.source) return false;
+  const haystack = term.matchCase ? text : text.toLowerCase();
+  const needle = term.matchCase ? term.source : term.source.toLowerCase();
+
+  let from = 0;
+  for (;;) {
+    const at = haystack.indexOf(needle, from);
+    if (at === -1) return false;
+    const before = at === 0 ? undefined : haystack[at - 1];
+    const after = haystack[at + needle.length];
+    if (!isWordish(before) && !isWordish(after)) return true;
+    from = at + 1;
+  }
+}
+
+/**
+ * The subset of the glossary that actually appears in this batch.
+ *
+ * This is the whole reason the feature is affordable. A 500-term glossary pasted into
+ * the system prompt of every 40-unit batch would dominate token cost on a large site
+ * and push the real instructions out of the model's attention. Sending only the terms
+ * present in the batch keeps prompt growth proportional to what is actually at stake.
+ */
+export function termsForBatch(terms, texts, lang) {
+  if (!terms.length) return [];
+  return terms.filter((term) => {
+    // A "translate" term with no target for THIS locale constrains nothing, so it would
+    // only be noise in the prompt.
+    if (term.rule === 'translate' && !term.targets[lang]) return false;
+    return texts.some((t) => containsTerm(t, term));
+  });
+}
+
+/** The prompt lines for a batch's terms. Empty string when there is nothing to say. */
+export function glossaryPrompt(terms, lang) {
+  if (!terms.length) return '';
+  const lines = terms.map((t) => {
+    const how = t.rule === 'keep'
+      ? `leave exactly as "${t.source}"`
+      : `always render as "${t.targets[lang]}"`;
+    const cased = t.matchCase ? ' (this capitalisation only)' : '';
+    return `   - "${t.source}"${cased}: ${how}${t.note ? ` — ${t.note}` : ''}`;
+  });
+  return [
+    `TERMINOLOGY — these terms appear in this batch and are not free choices:`,
+    ...lines,
+    `   Match whole words only. A term that is part of a longer word is a different word.`,
+    `   Inflect for grammar where the target language requires it, but keep the stem.`,
+  ].join('\n');
+}
+
+/**
+ * Compliance check for one translated unit.
+ *
+ * Returns a list of violations, each { source, expected, rule }. Deliberately NOT a
+ * hard failure by default: target languages inflect ("Panel de control" →
+ * "del Panel de control"), compound ("Dashboard-Ansicht"), and decline, so a strict
+ * substring test would flag correct translations constantly. The caller decides.
+ */
+export function checkCompliance(sourceText, translatedText, terms, lang) {
+  const violations = [];
+  for (const term of terms) {
+    if (!containsTerm(sourceText, term)) continue;
+
+    if (term.rule === 'keep') {
+      // "keep" is the strict one and can afford to be: the term is supposed to come
+      // through byte-identical, so a plain case-sensitive substring test is right.
+      if (!translatedText.includes(term.source)) {
+        violations.push({ source: term.source, expected: term.source, rule: 'keep' });
+      }
+      continue;
+    }
+
+    const expected = term.targets[lang];
+    if (!expected) continue;
+    // Case-insensitive and boundary-free on purpose — this is the inflection-tolerant
+    // side of the check. "Panel de control" inside "del Panel de control" passes.
+    if (!translatedText.toLowerCase().includes(expected.toLowerCase())) {
+      violations.push({ source: term.source, expected, rule: 'translate' });
+    }
+  }
+  return violations;
+}
+
+/**
+ * A stable fingerprint of the glossary, stored in the translation memory so a changed
+ * glossary can invalidate exactly the units it affects rather than the whole locale.
+ */
+export function glossaryFingerprint(terms) {
+  const canonical = terms
+    .map((t) => `${t.rule}|${t.matchCase ? 'C' : 'i'}|${t.source}|${JSON.stringify(t.targets)}`)
+    .sort()
+    .join('\n');
+  return canonical;
+}

package/scripts/glossary.test.mjs

@@ -0,0 +1,188 @@
+/**
+ * Glossary contract tests. No network, no key, no model.
+ *
+ * The case that motivated the feature is the first one: a user asked whether the tool
+ * can tell Apple (the company) from apple (the fruit). Before this module it could not
+ * — the do-not-translate list was matched against the whole trimmed unit and pasted
+ * into one prompt line with no case guidance.
+ */
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { tmpdir } from 'os';
+import { mkdtempSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+
+import {
+  loadGlossary, containsTerm, termsForBatch, glossaryPrompt,
+  checkCompliance, glossaryFingerprint,
+} from './glossary.mjs';
+
+const load = (entries) => loadGlossary(entries, '/nowhere', resolve);
+const term = (entry) => load([entry]).terms[0];
+
+// ── The Apple problem ────────────────────────────────────────────────────────
+
+test('a case-sensitive brand matches the company but not the fruit', () => {
+  const apple = term({ source: 'Apple', rule: 'keep' });
+  assert.equal(apple.matchCase, true, 'rule "keep" must default to case-sensitive');
+
+  assert.ok(containsTerm('Apple announced a new device', apple));
+  assert.ok(!containsTerm('I ate an apple for lunch', apple));
+});
+
+test('a brand does not match inside a longer word', () => {
+  const apple = term({ source: 'Apple', rule: 'keep' });
+  assert.ok(!containsTerm('Applesauce is on sale', apple));
+  assert.ok(!containsTerm('The Appleton office', apple));
+});
+
+test('a case-insensitive term still respects word boundaries', () => {
+  const t = term({ source: 'apple', rule: 'keep', matchCase: false });
+  assert.ok(containsTerm('An apple a day', t));
+  assert.ok(containsTerm('Apple pie recipe', t), 'case-insensitive should match either case');
+  assert.ok(!containsTerm('pineapple juice', t), 'must not match inside pineapple');
+});
+
+test('sentence-initial and punctuation-adjacent terms match', () => {
+  const acme = term({ source: 'Acme', rule: 'keep' });
+  assert.ok(containsTerm('Acme is great', acme), 'start of string');
+  assert.ok(containsTerm('We love Acme.', acme), 'followed by a period');
+  assert.ok(containsTerm('(Acme)', acme), 'wrapped in parentheses');
+  assert.ok(containsTerm('Acme', acme), 'the whole string');
+});
+
+// ── Term base ────────────────────────────────────────────────────────────────
+
+test('longer terms sort before shorter ones so the specific name wins', () => {
+  const { terms } = load([
+    { source: 'Acme', rule: 'keep' },
+    { source: 'Acme Cloud Inc', rule: 'keep' },
+  ]);
+  assert.equal(terms[0].source, 'Acme Cloud Inc');
+});
+
+test('per-locale targets pin the wording', () => {
+  const t = term({ source: 'Dashboard', rule: 'translate', targets: { es: 'Panel de control', de: 'Dashboard' } });
+  assert.equal(t.targets.es, 'Panel de control');
+  assert.equal(t.matchCase, false, 'rule "translate" defaults to case-insensitive');
+});
+
+test('a "translate" term with no targets is dropped, with a reported reason', () => {
+  const { terms, problems } = load([{ source: 'Widget', rule: 'translate' }]);
+  assert.equal(terms.length, 0);
+  assert.match(problems[0], /no targets/);
+});
+
+test('malformed rows are skipped, not fatal', () => {
+  const { terms, problems } = load([
+    { source: 'Acme', rule: 'keep' },
+    { source: '', rule: 'keep' },
+    { rule: 'keep' },
+    { source: 'Bad', rule: 'nonsense' },
+    'not an object',
+  ]);
+  assert.equal(terms.length, 1, 'the one good row survives');
+  assert.equal(problems.length, 4);
+});
+
+// ── Batch subsetting (the cost control) ──────────────────────────────────────
+
+test('only terms present in the batch are selected', () => {
+  const { terms } = load([
+    { source: 'Dashboard', rule: 'translate', targets: { es: 'Panel de control' } },
+    { source: 'Workspace', rule: 'translate', targets: { es: 'Espacio de trabajo' } },
+    { source: 'Apple', rule: 'keep' },
+  ]);
+  const picked = termsForBatch(terms, ['Open the Dashboard to begin'], 'es');
+  assert.deepEqual(picked.map((t) => t.source), ['Dashboard']);
+});
+
+test('a term with no target for THIS locale is not sent to the model', () => {
+  const { terms } = load([
+    { source: 'Dashboard', rule: 'translate', targets: { es: 'Panel de control' } },
+  ]);
+  assert.equal(termsForBatch(terms, ['Open the Dashboard'], 'es').length, 1);
+  assert.equal(termsForBatch(terms, ['Open the Dashboard'], 'fr').length, 0,
+    'fr has no pinned target, so the term constrains nothing and must not bloat the prompt');
+});
+
+test('an empty glossary produces no prompt text at all', () => {
+  assert.equal(glossaryPrompt([], 'es'), '');
+  assert.deepEqual(termsForBatch([], ['anything'], 'es'), []);
+});
+
+test('the prompt names the rule and the capitalisation constraint', () => {
+  const { terms } = load([
+    { source: 'Apple', rule: 'keep' },
+    { source: 'Dashboard', rule: 'translate', targets: { es: 'Panel de control' } },
+  ]);
+  const picked = termsForBatch(terms, ['Apple built the Dashboard'], 'es');
+  const prompt = glossaryPrompt(picked, 'es');
+  assert.match(prompt, /leave exactly as "Apple"/);
+  assert.match(prompt, /this capitalisation only/);
+  assert.match(prompt, /always render as "Panel de control"/);
+});
+
+// ── Compliance ───────────────────────────────────────────────────────────────
+
+test('a dropped brand is a violation; a surviving one is not', () => {
+  const { terms } = load([{ source: 'Acme', rule: 'keep' }]);
+  assert.equal(checkCompliance('Acme is fast', 'Acme es rápido', terms, 'es').length, 0);
+
+  const bad = checkCompliance('Acme is fast', 'Cumbre es rápido', terms, 'es');
+  assert.equal(bad.length, 1);
+  assert.equal(bad[0].rule, 'keep');
+  assert.equal(bad[0].expected, 'Acme');
+});
+
+test('compliance tolerates inflection around a pinned term', () => {
+  const { terms } = load([
+    { source: 'Dashboard', rule: 'translate', targets: { es: 'Panel de control' } },
+  ]);
+  const ok = checkCompliance('Open the Dashboard', 'Abre el Panel de control', terms, 'es');
+  assert.equal(ok.length, 0);
+
+  const alsoOk = checkCompliance('Dashboard settings', 'Ajustes del panel de control', terms, 'es');
+  assert.equal(alsoOk.length, 0, 'case and surrounding words must not trigger a false positive');
+
+  const bad = checkCompliance('Open the Dashboard', 'Abre el Tablero', terms, 'es');
+  assert.equal(bad.length, 1);
+});
+
+test('a term absent from the source is never checked against the target', () => {
+  const { terms } = load([{ source: 'Acme', rule: 'keep' }]);
+  assert.equal(checkCompliance('Nothing to see', 'Nada que ver', terms, 'es').length, 0);
+});
+
+// ── Fingerprint ──────────────────────────────────────────────────────────────
+
+test('the fingerprint is order-independent but content-sensitive', () => {
+  const a = load([
+    { source: 'Acme', rule: 'keep' },
+    { source: 'Dashboard', rule: 'translate', targets: { es: 'Panel' } },
+  ]).terms;
+  const b = load([
+    { source: 'Dashboard', rule: 'translate', targets: { es: 'Panel' } },
+    { source: 'Acme', rule: 'keep' },
+  ]).terms;
+  assert.equal(glossaryFingerprint(a), glossaryFingerprint(b), 'reordering must not invalidate a memory');
+
+  const c = load([
+    { source: 'Acme', rule: 'keep' },
+    { source: 'Dashboard', rule: 'translate', targets: { es: 'Panel de control' } },
+  ]).terms;
+  assert.notEqual(glossaryFingerprint(a), glossaryFingerprint(c), 'a changed target must invalidate');
+});
+
+// ── Loading from a file ──────────────────────────────────────────────────────
+
+test('a glossary loads from a JSON file path', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'ct-glossary-'));
+  const file = join(dir, 'glossary.json');
+  writeFileSync(file, JSON.stringify([{ source: 'Acme', rule: 'keep' }]));
+
+  const { terms } = loadGlossary('glossary.json', dir, resolve);
+  assert.equal(terms.length, 1);
+  assert.equal(terms[0].source, 'Acme');
+});