claude-translator 1.3.0 → 2.0.0

package/scripts/translate.mjs

@@ -27,10 +27,12 @@ import { join } from 'path';
 import { fileURLToPath } from 'url';
 
 import {
-  SOURCE_FILE as SRC_FILE, TM_DIR, LOCALES, RTL, DNT, MODEL as CFG_MODEL,
+  SOURCE_FILE as SRC_FILE, TM_DIR, LOCALES, RTL, DNT, GLOSSARY, MODEL as CFG_MODEL,
   ROOT_DIR as ROOT, SITE_NAME, SITE_DESCRIPTION, SOURCE_LANGUAGE,
   PROVIDER as CFG_PROVIDER, API_BASE_URL, API_KEY_ENV, JSON_MODE, PRICING,
 } from './config.mjs';
+import { termsForBatch, glossaryPrompt, glossaryFingerprint, containsTerm } from './glossary.mjs';
+import { roleOf, rolePrompt } from './roles.mjs';
 import { hint, link } from './credit.mjs';
 import { loadProvider, extractJson } from './providers/index.mjs';
 
@@ -115,10 +117,18 @@ const TECH_TOKENS = [
   'OCR', 'GDPR', 'SSL', 'TLS', 'API', 'SDK', 'URL', 'HTTP', 'HTTPS', 'SEO', 'CSS', 'RSS',
 ];
 
-const GLOSSARY = [...new Set([...DNT.brands, ...DNT.formats, ...TECH_TOKENS])];
+/**
+ * The flat never-translate list that still goes into rule 2. The structured glossary
+ * (config.GLOSSARY) carries the same brands plus per-locale targets and is injected
+ * per batch; this line stays because format and protocol tokens are correct unchanged
+ * in every language and are cheap to state once.
+ */
+const DNT_NAMES = [...new Set([...DNT.brands, ...DNT.formats, ...TECH_TOKENS])];
 
-function systemPrompt(langCode) {
+function systemPrompt(langCode, batchTerms = [], batchRoles = []) {
   const name = LANG_NAMES[langCode] ?? langCode;
+  const terminology = glossaryPrompt(batchTerms, langCode);
+  const context = rolePrompt(batchRoles);
   return [
     `You are a professional translator localising the website of ${SITE_NAME}${SITE_DESCRIPTION ? `, ${SITE_DESCRIPTION}` : ''}.`,
     `Translate from ${SOURCE_LANGUAGE} into ${name} (${langCode}).`,
@@ -127,7 +137,9 @@ function systemPrompt(langCode) {
     `1. Preserve every placeholder EXACTLY: <0>, </0>, <1/> and so on. Same count, same numbers.`,
     `   Placeholders wrap inline markup — move them so they wrap the equivalent words in your`,
     `   translation, but never drop, add, renumber or reorder their nesting.`,
-    `2. Never translate these names: ${GLOSSARY.join(', ')}.`,
+    `2. Never translate these names: ${DNT_NAMES.join(', ')}.`,
+    `   Match whole words, and respect capitalisation: a lowercase common noun that`,
+    `   happens to spell a brand name is the common noun, and must be translated.`,
     `3. This is marketing and product copy. Translate meaning and tone, not word for word.`,
     `   Keep it natural and idiomatic for a native reader.`,
     `4. Keep numbers, prices, file sizes and counts unchanged (e.g. "120+", "1 GB", "10 MB").`,
@@ -135,6 +147,8 @@ function systemPrompt(langCode) {
     `   target language allows it. Headings stay headings; button labels stay short.`,
     `6. Do not add explanations, notes or quotes around the result.`,
     RTL.has(langCode) ? `7. ${name} is right-to-left. Write natural RTL text; do not insert directional marks.` : ``,
+    terminology,
+    context,
     ``,
     `Return a JSON array. For each input item return { "id": <same id>, "text": "<translation>" }.`,
   ]
@@ -180,23 +194,29 @@ function validate(source, translated) {
  * `usage` is normalised to { inTok, outTok } so the caller never sees a provider's
  * own field names.
  */
-async function callModel(langCode, items, attempt = 1, jsonMode = JSON_MODE) {
+async function callModel(langCode, items, attempt = 1, jsonMode = JSON_MODE, drop = new Set()) {
+  // Recomputed per call, not per run, so a batch that gets halved on a safety block or a
+  // truncation carries exactly the terms its own half contains.
+  const batchTerms = termsForBatch(GLOSSARY, items.map((i) => i.text), langCode);
+  const batchRoles = items.map((i) => i.el).filter(Boolean);
+
   const { url, headers, body } = PROVIDER.request({
     model: MODEL,
-    system: systemPrompt(langCode),
+    system: systemPrompt(langCode, batchTerms, batchRoles),
     items,
     temperature: attempt === 1 ? 0.2 : 0.4,
     key: KEY,
     baseUrl: API_BASE_URL,
     jsonMode,
+    drop,
   });
 
   const split = async (why, mode = jsonMode) => {
     const mid = Math.ceil(items.length / 2);
     process.stderr.write(`  ${why} on ${items.length} units — splitting\n`);
     const [a, b] = await Promise.all([
-      callModel(langCode, items.slice(0, mid), 1, mode),
-      callModel(langCode, items.slice(mid), 1, mode),
+      callModel(langCode, items.slice(0, mid), 1, mode, drop),
+      callModel(langCode, items.slice(mid), 1, mode, drop),
     ]);
     return {
       rows: [...a.rows, ...b.rows],
@@ -219,7 +239,7 @@ async function callModel(langCode, items, attempt = 1, jsonMode = JSON_MODE) {
         `  network error (${String(err.message ?? err).slice(0, 60)}), retry ${attempt} in ${wait}ms\n`
       );
       await new Promise((r) => setTimeout(r, wait));
-      return callModel(langCode, items, attempt + 1, jsonMode);
+      return callModel(langCode, items, attempt + 1, jsonMode, drop);
     }
     throw err;
   }
@@ -236,16 +256,26 @@ async function callModel(langCode, items, attempt = 1, jsonMode = JSON_MODE) {
         process.stderr.write(
           `  server rejected JSON mode "${jsonMode ?? 'schema'}" — retrying with "${next}"\n`
         );
-        return callModel(langCode, items, attempt, next);
+        return callModel(langCode, items, attempt, next, drop);
       }
     }
 
+    // The same idea one level down: a server that rejects ONE parameter is telling us
+    // about its capabilities, not about a broken run. Drop that parameter and retry.
+    // `drop` only ever grows, so each parameter is dropped at most once and this cannot
+    // loop. Adapters that do not implement the hook are unaffected.
+    const bad = PROVIDER.unsupportedParam?.(res.status, text);
+    if (bad && !drop.has(bad)) {
+      process.stderr.write(`  server rejected "${bad}" — retrying without it\n`);
+      return callModel(langCode, items, attempt, jsonMode, new Set(drop).add(bad));
+    }
+
     const retryable = res.status === 429 || res.status >= 500;
     if (retryable && attempt <= 5) {
       const wait = Math.min(2 ** attempt * 1000, 30000);
       process.stderr.write(`  HTTP ${res.status}, retry ${attempt} in ${wait}ms\n`);
       await new Promise((r) => setTimeout(r, wait));
-      return callModel(langCode, items, attempt + 1, jsonMode);
+      return callModel(langCode, items, attempt + 1, jsonMode, drop);
     }
     throw new Error(`${PROVIDER.label ?? PROVIDER.id} HTTP ${res.status}: ${text.slice(0, 300)}`);
   }
@@ -297,6 +327,53 @@ async function translateLang(langCode, units) {
   const tmFile = join(TM_DIR, `${langCode}${TAG}.json`);
   const tm = existsSync(tmFile) ? JSON.parse(readFileSync(tmFile, 'utf8')) : {};
 
+  // ── Glossary invalidation ──────────────────────────────────────────────────
+  // The memory is keyed by the source hash alone, so editing a glossary target used to
+  // change nothing: every affected unit was already in the memory and got skipped, and
+  // the new terminology silently never shipped. The sidecar records the fingerprint the
+  // memory was built against; when it moves, the units containing an affected term are
+  // dropped so they re-translate. Only those — a term change must not cost a full locale.
+  //
+  // It is a SIDECAR, not a key inside the memory, because README documents
+  // i18n/tm/{lang}.json as a hand-editable hash -> string map and three other scripts
+  // iterate it. A `__meta` key would have made every coverage count off by one.
+  const metaFile = join(TM_DIR, `${langCode}${TAG}.meta.json`);
+  const meta = existsSync(metaFile) ? JSON.parse(readFileSync(metaFile, 'utf8')) : {};
+  const fingerprint = glossaryFingerprint(GLOSSARY);
+
+  if (typeof meta.glossary === 'string' && meta.glossary !== fingerprint) {
+    const before = new Set(meta.glossary.split('\n').filter(Boolean));
+    const after = new Set(fingerprint.split('\n').filter(Boolean));
+    // A term whose line is missing from either side has been added, removed or edited.
+    const changed = GLOSSARY.filter((t) => {
+      const line = glossaryFingerprint([t]);
+      return !before.has(line) || !after.has(line);
+    });
+    // Removed terms are gone from GLOSSARY, so recover them from the old fingerprint to
+    // re-translate units that were constrained by a rule the user has just deleted.
+    const removedSources = [...before]
+      .filter((line) => !after.has(line))
+      .map((line) => line.split('|')[2])
+      .filter(Boolean);
+
+    let dropped = 0;
+    for (const [hash, unit] of units) {
+      if (!(hash in tm)) continue;
+      const hit =
+        changed.some((t) => containsTerm(unit.text, t)) ||
+        removedSources.some((src) => containsTerm(unit.text, { source: src, matchCase: false }));
+      if (hit) {
+        delete tm[hash];
+        dropped++;
+      }
+    }
+    if (dropped) {
+      process.stderr.write(
+        `  glossary changed — re-translating ${dropped.toLocaleString()} affected unit(s)\n`
+      );
+    }
+  }
+
   const pending = units.filter(([hash]) => !(hash in tm));
 
   // Re-run churn. The memory is keyed by source hash, so on an existing locale the
@@ -319,6 +396,11 @@ async function translateLang(langCode, units) {
 
   if (pending.length === 0) {
     console.log(`${langCode}: nothing to do (${Object.keys(tm).length} in memory)`);
+    // Nothing pending means nothing was dropped, so the memory on disk already matches
+    // this glossary — safe to record the fingerprint without a translation pass. The
+    // fingerprint is never written ahead of a TM flush: if a run dies mid-way, the next
+    // one must still see a stale fingerprint and re-drop the affected units.
+    writeFileSync(metaFile, JSON.stringify({ ...meta, glossary: fingerprint }, null, 2));
     return;
   }
 
@@ -341,6 +423,7 @@ async function translateLang(langCode, units) {
   let sinceFlush = 0;
   const flush = () => {
     writeFileSync(tmFile, JSON.stringify(tm, null, 2));
+    writeFileSync(metaFile, JSON.stringify({ ...meta, glossary: fingerprint }, null, 2));
     sinceFlush = 0;
   };
 
@@ -351,7 +434,12 @@ async function translateLang(langCode, units) {
       if (myIndex >= batches.length) return;
       const batch = batches[myIndex];
 
-      const items = batch.map(([, unit], i) => ({ id: i, text: unit.text }));
+      // `el` is omitted for ordinary prose rather than sent as null: a site of nothing but
+      // paragraphs then produces a byte-identical payload to 1.x and costs not one extra token.
+      const items = batch.map(([, unit], i) => {
+        const el = roleOf(unit);
+        return el ? { id: i, text: unit.text, el } : { id: i, text: unit.text };
+      });
 
       let rows;
       let usage;
@@ -380,7 +468,10 @@ async function translateLang(langCode, units) {
 
       for (const [hash, unit, problem] of retry) {
         try {
-          const solo = await callModel(langCode, [{ id: 0, text: unit.text }]);
+          const soloEl = roleOf(unit);
+          const solo = await callModel(langCode, [
+            soloEl ? { id: 0, text: unit.text, el: soloEl } : { id: 0, text: unit.text },
+          ]);
           const out = solo.rows.find((r) => r.id === 0)?.text;
           inTok += solo.usage.inTok;
           outTok += solo.usage.outTok;

package/scripts/verify.mjs

@@ -18,6 +18,14 @@
  *                        inLanguage / @id / url — the three sitewide defects the
  *                        2026-08-13 audit found on the proxy-served pages.
  *   5. Coverage          share of segments still in English, per locale.
+ *   6. Never offered     visible text the extractor never picked up. Coverage measures
+ *                        translated-of-EXTRACTED and is structurally blind to this.
+ *   7. Glossary          terms that were supposed to survive, or to be rendered a
+ *                        particular way, and were not. REPORTS by default; --strict
+ *                        makes it gate, because inflection makes strictness noisy.
+ *   8. Numeric integrity numbers that changed value between source and translation.
+ *                        Gates by default: a silently rewritten price is a commercial
+ *                        problem, and no other gate can see it.
  */
 
 import { readFileSync, readdirSync, existsSync } from 'fs';
@@ -27,11 +35,15 @@ import { parse } from 'parse5';
 
 import {
   BUILD_DIR as DIST, SEG_DIR, BASE_URL as BASE, LOCALES as LANG_ROWS,
-  BY_PATH, RTL, getPages, I18N_DIR, DNT,
+  BY_PATH, RTL, getPages, I18N_DIR, TM_DIR, SOURCE_FILE, ROOT_DIR, DNT, GLOSSARY,
 } from './config.mjs';
 import { creditBlock, markerBytes, GENERATOR_NAME, PRIOR_GENERATOR_NAMES } from './credit.mjs';
+import { checkCompliance } from './glossary.mjs';
 
-const ROOT = process.cwd();
+// ROOT_DIR honours $I18N_ROOT; process.cwd() did not, so a run from another
+// directory read the wrong tree. Paths under i18n/ come from config so that
+// `i18nDir` actually takes effect — it was imported here and then ignored.
+const ROOT = ROOT_DIR;
 
 /**
  * Format, protocol and standards tokens that are correct unchanged in every language.
@@ -54,6 +66,9 @@ const args = Object.fromEntries(
     .map(([k, ...v]) => [k, v.join(' ') || true])
 );
 
+/** Gate 7 reports by default; --strict makes a terminology violation fail the build. */
+const STRICT = Boolean(args.strict);
+
 
 const requested = String(args.lang ?? '').trim();
 if (!requested) {
@@ -238,7 +253,7 @@ if (identityBad.length) fail('identity', `${identityBad.length} pages`);
 console.log('\n[5] translation coverage');
 const totalSegments = pages.reduce((n, p) => n + p.segmentCount, 0);
 for (const lang of LANGS) {
-  const tmFile = join(ROOT, 'i18n/tm', `${lang}.json`);
+  const tmFile = join(TM_DIR, `${lang}.json`);
   if (!existsSync(tmFile)) {
     console.log(`      ${lang}: no memory`);
     continue;
@@ -331,8 +346,8 @@ function extractedBlob(slug) {
   return entry.segments.map((s) => (src[s.hash]?.text ?? '').replace(/<\/?\d+\/?>/g, ' ')).join(' 
 ');
 }
 
-const SOURCE = existsSync(join(ROOT, 'i18n/source.json'))
-  ? JSON.parse(readFileSync(join(ROOT, 'i18n/source.json'), 'utf8'))
+const SOURCE = existsSync(SOURCE_FILE)
+  ? JSON.parse(readFileSync(SOURCE_FILE, 'utf8'))
   : null;
 
 console.log('\n[6] text never offered for translation');
@@ -365,6 +380,99 @@ for (const lang of LANGS) {
   if (holes > 0) fail('extraction-hole', `${lang}: ${holes} strings never offered for translation`);
 }
 
+// ── Gate 7: glossary compliance ──────────────────────────────────────────────
+// Terminology was previously unverifiable. A brand could be translated away and every
+// gate still passed: gate 2 compares markup, gate 5 counts coverage, and gate 6 uses the
+// brand list only to SUPPRESS false alarms. Nothing asserted a term survived.
+//
+// Reports by default and gates only under --strict, on purpose. Target languages inflect
+// ("Panel de control" -> "del Panel de control"), compound ("Dashboard-Ansicht") and
+// decline, so a strict test flags correct work. references/quality-review.md is explicit
+// that a heuristic which over-flags is worse than none, and the remedy here —
+// purge-and-retranslate — costs real money.
+
+console.log('\n[7] glossary compliance');
+if (GLOSSARY.length === 0) {
+  console.log('      no glossary configured \u2014 skipped');
+} else {
+  for (const lang of LANGS) {
+    const tmFile = join(TM_DIR, `${lang}.json`);
+    if (!existsSync(tmFile)) {
+      console.log(`      ${lang}: no memory`);
+      continue;
+    }
+    const tm = JSON.parse(readFileSync(tmFile, 'utf8'));
+    const violations = [];
+    for (const [hash, unit] of Object.entries(SOURCE)) {
+      const translated = tm[hash];
+      if (typeof translated !== 'string') continue;
+      for (const v of checkCompliance(unit.text, translated, GLOSSARY, lang)) {
+        violations.push({ hash, ...v, source: unit.text.slice(0, 60) , term: v.source });
+      }
+    }
+    const checked = Object.keys(tm).length;
+    const pct = checked ? (violations.length * 100) / checked : 0;
+    console.log(
+      `      ${lang}: ${violations.length} violation(s) in ${checked.toLocaleString()} units (${pct.toFixed(2)}%)`
+    );
+    for (const v of violations.slice(0, 5)) {
+      console.log(`        "${v.term}" \u2192 expected "${v.expected}" in: ${v.source}\u2026`);
+    }
+    if (violations.length > 5) console.log(`        \u2026 and ${violations.length - 5} more`);
+    if (STRICT && violations.length) fail('glossary', `${lang}: ${violations.length} violation(s)`);
+  }
+  if (!STRICT) console.log('      (reporting only \u2014 pass --strict to gate on this)');
+}
+
+// ── Gate 8: numeric integrity ────────────────────────────────────────────────
+// A model that silently rewrites "$49/month" as "$39/month" passes every other gate:
+// the markup is identical, the placeholder count matches, the length is plausible and
+// the text is fluent target-language. Prices are commercial commitments, so this one
+// DOES gate by default.
+//
+// Compares multisets, not sequences: languages legitimately reorder ("2 of 3" ->
+// "3 dintre 2" never happens, but date and measurement order does move). Digit-group
+// separators are stripped first, because locale formatting is applied at build time and
+// is a correct difference, not a defect.
+
+const NUM_RE = /\d[\d.,\u00a0\u202f ]*\d|\d/g;
+
+/** Numbers reduced to a comparable form: separators stripped, trailing zeros normalised. */
+function numeralMultiset(text) {
+  const found = String(text).match(NUM_RE) ?? [];
+  return found
+    .map((n) => n.replace(/[.,\u00a0\u202f ]/g, ''))
+    .filter((n) => n.length > 0)
+    .map((n) => n.replace(/^0+(?=\d)/, ''))
+    .sort();
+}
+
+console.log('\n[8] numeric integrity');
+for (const lang of LANGS) {
+  const tmFile = join(TM_DIR, `${lang}.json`);
+  if (!existsSync(tmFile)) {
+    console.log(`      ${lang}: no memory`);
+    continue;
+  }
+  const tm = JSON.parse(readFileSync(tmFile, 'utf8'));
+  const drifted = [];
+  for (const [hash, unit] of Object.entries(SOURCE)) {
+    const translated = tm[hash];
+    if (typeof translated !== 'string') continue;
+    const a = numeralMultiset(unit.text);
+    const b = numeralMultiset(translated);
+    if (a.join('|') !== b.join('|')) {
+      drifted.push({ src: unit.text.slice(0, 70), out: translated.slice(0, 70), a, b });
+    }
+  }
+  console.log(`      ${lang}: ${drifted.length} unit(s) whose numbers changed`);
+  for (const d of drifted.slice(0, 5)) {
+    console.log(`        [${d.a.join(', ')}] \u2192 [${d.b.join(', ')}]  ${d.src}\u2026`);
+  }
+  if (drifted.length > 5) console.log(`        \u2026 and ${drifted.length - 5} more`);
+  if (drifted.length) fail('numeric-drift', `${lang}: ${drifted.length} unit(s)`);
+}
+
 // ── Result ───────────────────────────────────────────────────────────────────
 
 console.log('');

package/{SKILL.md → skills/translate-site/SKILL.md}

@@ -1,9 +1,9 @@
 ---
-name: claude-translator
+name: translate-site
 description: >
   Localize a static website into many languages by substituting translations into
-  already-built HTML, without re-rendering. Ships six proven scripts (extract,
-  translate, review, build, verify, SEO audit) plus the failure modes that cost real
+  already-built HTML, without re-rendering. Ships proven scripts (extract,
+  translate, review, build, verify, SEO audit, glossary, locale formatting, MQM quality scoring) plus the failure modes that cost real
   money to discover. Use when the user says "translate the site", "localize",
   "multi-language site", "i18n", "add languages", "translate all pages", or is
   replacing a translation proxy (Weglot, Bablic, Localize, TranslatePress) with self-hosted pages.
@@ -14,7 +14,7 @@ argument-hint: "[project-dir]"
 license: AGPL-3.0
 metadata:
   author: ConveyThis
-  version: "1.3.0"
+  version: "2.0.0"
   category: i18n
 ---
 
@@ -82,7 +82,7 @@ write; where that is missing, say so rather than spending the user's time and AP
 - **The user wants to edit translations in a UI, or needs human review** — there is neither
   here. Editing means hand-editing a hash in `i18n/tm/{lang}.json`.
 - **The user is wrapping a modified copy in a hosted service** — AGPL-3.0 §13 obliges them to
-  publish their modifications. See `LICENSING.md`; a commercial licence exists.
+  publish their modifications. See `${CLAUDE_PLUGIN_ROOT}/LICENSING.md`; a commercial licence exists.
 
 Running it unmodified, on their own sites, and shipping the output is unrestricted. Do not
 warn them about the licence in that case — it does not apply.
@@ -114,16 +114,22 @@ do not take the same parameters and guessing costs money.
 
 ```bash
 cd <project>
-node ~/.claude/skills/claude-translator/bin/claude-translator.mjs init
+npx claude-translator init               # works anywhere
 npm install                              # parse5, the only dependency
 ```
 
+Offline, or when the plugin is already installed, run the bundled copy instead of `npx`:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}"/bin/claude-translator.mjs init
+```
+
 That copies the pipeline into `scripts/i18n/`, writes `i18n.config.json`, declares
 `parse5` and adds the derived paths to `.gitignore`. It never overwrites without
 `--force`, so it is safe to re-run; `--dir <path>` puts the scripts elsewhere.
 
 Scripts run **from inside the project** so `parse5` and relative paths resolve. Edit
-`i18n.config.json` — five keys cover everything; see `i18n.config.example.json`.
+`i18n.config.json` — five keys cover everything; see `${CLAUDE_PLUGIN_ROOT}/i18n.config.example.json`.
 
 **Commit `i18n/tm/{lang}.json`.** The scaffolder deliberately does not ignore it: the
 memory is the asset, and losing it means paying for a full re-translation. Everything
@@ -133,12 +139,13 @@ else under `i18n/` is derived and is ignored for you. Add `i18n` to `.prettierig
 
 ```bash
 npm run build                                   # source language only
-node scripts/extract.mjs                   # → i18n/source.json + segments/
-node scripts/translate.mjs --lang es,fr    # → i18n/tm/{lang}.json  (needs a provider key)
-node scripts/review.mjs   --lang es        # quality flags
-node scripts/build-locales.mjs --lang all  # → dist/{lang}/…
-node scripts/verify.mjs   --lang all       # six gates
-node scripts/audit-seo.mjs                 # canonical/hreflang/JSON-LD/sitemaps
+node scripts/i18n/extract.mjs                   # → i18n/source.json + segments/
+node scripts/i18n/translate.mjs --lang es,fr    # → i18n/tm/{lang}.json  (needs a provider key)
+node scripts/i18n/review.mjs   --lang es        # quality flags
+node scripts/i18n/build-locales.mjs --lang all  # → dist/{lang}/…
+node scripts/i18n/verify.mjs   --lang all       # six gates
+node scripts/i18n/audit-seo.mjs                 # canonical/hreflang/JSON-LD/sitemaps
+node scripts/i18n/tqa.mjs      --lang es        # MQM quality score (optional, costs money)
 ```
 
 `finalize.sh <locales…>` collapses the per-locale cycle (gap-fill → review → purge →
@@ -163,6 +170,31 @@ matches and warn on zero. Attribute order is not guaranteed — `<link href="…
 rel="canonical">` is as valid as `rel` first — and an order-dependent regex silently
 matches nothing while reporting success.
 
+**Element context is a hint, never a constraint.** Units carry an `el` label (button,
+heading, form label, meta description...) so the model can pick the right register. There is
+deliberately no length enforcement: a unit that fails validation ships in the SOURCE
+language, so gating on length would replace a slightly-long German button with an English
+one. If a user asks for a character budget, explain that tradeoff first.
+
+**Never convert a currency, and never offer to.** `localeFormat` reformats amounts and
+the pipeline reports every one it saw to `i18n/locale-format.json`. Converting a price at
+a build-time rate is how a translation tool starts publishing wrong offers, and there is
+no config option for it. If the user asks for conversion, explain the report instead.
+
+**Gate 8 gates; gate 7 reports.** A changed numeric value fails the build, because a
+silently rewritten price passes every other check. Terminology only warns unless
+`--strict` is passed, because target languages inflect pinned terms and a strict check
+flags correct work — see `references/quality-review.md` on why over-flagging is worse
+than nothing.
+
+**This tool rewrites tags; it does not create them.** Every locale-identity rule replaces
+an attribute value on a tag the template already emits — the only thing ever inserted is the
+attribution marker. So the **full `hreflang` mesh and `sitemap.xml` must come from the user's
+own build**: `build-locales.mjs` rewrites only the `x-default` and source-language hrefs, and
+writes no sitemap at all. `audit-seo.mjs` checks both exhaustively, which is how a missing
+mesh surfaces. If the user's template lacks the alternates, say so plainly and point at
+`references/adapting-generators.md` — do not imply the pipeline will emit them.
+
 **Verify server-side state, not exit codes.** Especially with rsync on macOS
 (`openrsync` prints usage and exits **0** on an unsupported flag).
 

package/{references → skills/translate-site/references}/providers.md

@@ -18,7 +18,7 @@ talks through a small adapter. Three ship with the project; anything else is one
 | --- | --- | --- | --- |
 | `anthropic` | `claude-haiku-4-5` | `ANTHROPIC_API_KEY` | The default. |
 | `gemini` | `gemini-2.5-flash-lite` | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | Roughly a tenth the cost — see [throughput-and-cost.md](throughput-and-cost.md). |
-| `openai` | `gpt-4o-mini` | `OPENAI_API_KEY` | Any OpenAI-compatible endpoint, including local ones. |
+| `openai` | `gpt-5.6-luna` | `OPENAI_API_KEY` | Any OpenAI-compatible endpoint, including local ones. |
 | `./my-provider.mjs` | — | yours | A path is imported directly. See below. |
 
 `--provider` and `--model` on the command line override the config for one run.
@@ -98,7 +98,7 @@ export const envKeys = ['MY_PROVIDER_KEY'];  // checked in order, env then .env
 export const keyOptional = false;            // true for local servers
 
 /** Build one HTTP request. */
-export function request({ model, system, items, temperature, key, baseUrl, jsonMode }) {
+export function request({ model, system, items, temperature, key, baseUrl, jsonMode, drop }) {
   return {
     url: `${baseUrl ?? 'https://api.example.com/v1'}/translate`,
     headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json' },
@@ -121,6 +121,20 @@ export const unwrap = (parsed) => parsed.translations ?? parsed;
 
 /** Optional: USD per million tokens, [in, out]. Omit if unknown. */
 export function pricing(model) { return [0.5, 1.5]; }
+
+/**
+ * Optional: name ONE request parameter the server rejected, so translate.mjs can retry
+ * without it. Return null for anything else. The parameter is added to a `drop` set
+ * that is passed back into request(), and each one is dropped at most once.
+ *
+ * Set the bar high. The error must read as a capability complaint AND name a parameter
+ * you actually send; otherwise a genuine 400 gets mistaken for a recoverable one and the
+ * run quietly strips its own request instead of telling the user what is wrong.
+ */
+export function unsupportedParam(status, errText) {
+  if (status !== 400) return null;
+  return /unsupported.*\btemperature\b/i.test(errText) ? 'temperature' : null;
+}
 ```
 
 Then:

package/{references → skills/translate-site/references}/quality-review.md

@@ -71,6 +71,34 @@ are legitimate — postal addresses, image filenames used as alt text, proper no
 
 ---
 
+## Where TQA fits
+
+`review.mjs` finds *defects by shape* — a dropped placeholder, a wholesale source-language
+return, a truncated string. It is cheap, offline, and blind to whether the text is any good.
+
+`tqa.mjs` answers the other question, and costs money. It scores a seeded,
+frequency-stratified sample against the MQM typology using a second model as judge.
+
+| | `review.mjs` | `tqa.mjs` |
+| --- | --- | --- |
+| Cost | free | one API call per ~10 units |
+| Finds | mechanical defects | mistranslation, register, terminology, awkwardness |
+| Output | `{lang}.review.json` | `i18n/tqa/{lang}.json` + `scorecard.md` |
+| Gates a build | no | no |
+
+Run `review.mjs` on every locale, every time. Run `tqa.mjs` when you need a number to
+compare — between locales, between models, or before and after a prompt change.
+
+**The same over-flagging discipline applies to the score itself.** Three guards exist
+because each of them failed once during development:
+
+- the judge defaults to a *different provider* than the translator, since a model scores
+  its own work generously
+- `--repeat` reports the gap between two runs on the same sample, so nobody reads a
+  decimal place that is really noise
+- a unit the judge could not assess is **excluded**, never counted as clean. An early
+  version reported `100.00 / 100` from a sample where every unit had failed to parse
+
 ## Workflow
 
 ```bash