claude-translator 1.4.0 → 2.0.0

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.4.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}/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