npm - claude-translator - Versions diffs - 1.3.0 - Mend

claude-translator 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

package/CHANGELOG.md +135 -0
package/LICENSE +662 -0
package/LICENSING.md +69 -0
package/README.md +434 -0
package/SKILL.md +206 -0
package/bin/claude-translator.mjs +230 -0
package/bin/cli.test.mjs +165 -0
package/i18n.config.example.json +67 -0
package/package.json +60 -0
package/references/adapting-generators.md +76 -0
package/references/failure-modes.md +255 -0
package/references/providers.md +157 -0
package/references/quality-review.md +91 -0
package/references/throughput-and-cost.md +124 -0
package/scripts/audit-seo.mjs +261 -0
package/scripts/build-locales.mjs +336 -0
package/scripts/config.mjs +188 -0
package/scripts/credit.mjs +143 -0
package/scripts/extract.mjs +564 -0
package/scripts/finalize.sh +58 -0
package/scripts/providers/anthropic.mjs +118 -0
package/scripts/providers/gemini.mjs +72 -0
package/scripts/providers/index.mjs +95 -0
package/scripts/providers/openai.mjs +120 -0
package/scripts/providers/providers.test.mjs +214 -0
package/scripts/review.mjs +310 -0
package/scripts/translate.mjs +455 -0
package/scripts/verify.mjs +384 -0

package/scripts/build-locales.mjs ADDED Viewed

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+/**
+ * i18n step 3 — write the localised static pages.
+ *
+ *   node scripts/i18n/build-locales.mjs --lang es,ru,pt-br
+ *   node scripts/i18n/build-locales.mjs --lang all
+ *
+ * Reads   dist/                    English build (untouched)
+ *         i18n/segments/*.json     byte ranges from extract.mjs
+ *         i18n/tm/{lang}.json      translations from translate.mjs
+ * Writes  dist/{lang}/{slug}/index.html
+ *
+ * ── How the HTML is produced ─────────────────────────────────────────────────
+ * Each page is the English file with segment ranges spliced right-to-left. The
+ * document is never re-serialised from a DOM, so everything outside those ranges —
+ * inlined critical CSS, asset hashes, width/height attributes, script order — is
+ * carried over byte for byte. That is what keeps the localised pages' Core Web
+ * Vitals identical to the English ones rather than merely similar.
+ *
+ * On top of the text substitution each page gets its locale identity fixed:
+ * <html lang>, dir=rtl, canonical, the hreflang set, JSON-LD @id/url/inLanguage,
+ * og:locale and internal link prefixes. Those three JSON-LD fields and the
+ * en/x-default hreflang pair are exactly the sitewide defects the 2026-08-13 audit
+ * found on ~13,035 proxy-served URLs; generating the pages ourselves closes them.
+ */
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, rmSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { BUILD_DIR as DIST, SEG_DIR, TM_DIR, BASE_URL as BASE, LOCALES as LANG_ROWS, BY_PATH, RTL, getPages } from './config.mjs';
+import { applyPageMarkers, applyVisibleLink, markerBytes } from './credit.mjs';
+const ROOT = process.cwd();
+const args = Object.fromEntries(
+  process.argv
+    .slice(2)
+    .join(' ')
+    .split('--')
+    .filter(Boolean)
+    .map((s) => s.trim().split(/\s+/))
+    .map(([k, ...v]) => [k, v.join(' ') || true])
+);
+// ── Locale table ─────────────────────────────────────────────────────────────
+const requested = String(args.lang ?? '').trim();
+if (!requested) {
+  console.error('Usage: node scripts/i18n/build-locales.mjs --lang es[,ru,...] | --lang all');
+  process.exit(1);
+}
+const LANGS = requested === 'all' ? LANG_ROWS.map((r) => r.pathCode) : requested.split(',').map((s) => s.trim());
+for (const l of LANGS) {
+  if (!BY_PATH[l]) {
+    console.error(`Unknown locale "${l}" — not in the locales config`);
+    process.exit(1);
+  }
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+const escHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const escAttr = (s) => escHtml(s).replace(/"/g, '&quot;');
+const escJson = (s) => JSON.stringify(s).slice(1, -1);
+/** Rebuild a block's innerHTML from its translated placeholder text + tag table. */
+function renderBlock(text, tags) {
+  let out = '';
+  let last = 0;
+  let m;
+  const re = /<(\/?)(\d+)(\/?)>/g;
+  while ((m = re.exec(text))) {
+    out += escHtml(text.slice(last, m.index));
+    const pair = tags[Number(m[2])];
+    if (pair) {
+      const [open, close] = pair;
+      out += m[3] === '/' ? open : m[1] === '/' ? (close ?? '') : open;
+    }
+    last = m.index + m[0].length;
+  }
+  return out + escHtml(text.slice(last));
+}
+/** English page path ("" = home) → localised URL. */
+const localeUrl = (lang, slug) => (slug ? `${BASE}/${lang}/${slug}` : `${BASE}/${lang}`);
+const englishUrl = (slug) => (slug ? `${BASE}/${slug}` : `${BASE}/`);
+/**
+ * Rewrites one attribute on the first tag matching `test`, leaving the rest of the
+ * tag byte-identical. Attribute ORDER is not assumed: the Astro build emits
+ * `<link href="…" rel="canonical">`, i.e. href first, so order-dependent patterns
+ * silently matched nothing.
+ */
+function rewriteAttr(html, tagRe, test, attrName, newValue, name, report) {
+  let matched = false;
+  const out = html.replace(tagRe, (tag) => {
+    const attrs = Object.fromEntries([...tag.matchAll(/([\w:-]+)="([^"]*)"/g)].map((m) => [m[1], m[2]]));
+    if (!test(attrs)) return tag;
+    matched = true;
+    const re = new RegExp(`(\\s${attrName}=")[^"]*(")`);
+    return re.test(tag) ? tag.replace(re, `$1${newValue}$2`) : tag;
+  });
+  if (!matched) report.misses.add(name);
+  return out;
+}
+/**
+ * Locale identity fixes applied after text substitution. Each rule reports whether it
+ * matched, so a template change cannot silently turn one into a no-op.
+ */
+function applyLocaleIdentity(html, lang, slug, report) {
+  const url = localeUrl(lang, slug);
+  const enUrl = englishUrl(slug);
+  const row = BY_PATH[lang];
+  let out = html;
+  // <html … lang="en" dir="ltr"> → locale. The build already emits dir, so RTL
+  // locales must REPLACE its value rather than add a second attribute.
+  const before = out;
+  out = out.replace(/<html[^>]*>/, (tag) => {
+    let t = tag.replace(/(\slang=")[^"]*(")/, `$1${row.hreflang}$2`);
+    t = t.replace(/(\sdir=")[^"]*(")/, `$1${RTL.has(lang) ? 'rtl' : 'ltr'}$2`);
+    return t;
+  });
+  if (out === before) report.misses.add('html-lang');
+  // Canonical → this page, no trailing slash (audit H5: the proxy emitted /es/,
+  // which 301s back to /es and contradicts the sitemap).
+  out = rewriteAttr(out, /<link[^>]*>/g, (a) => a.rel === 'canonical', 'href', url, 'canonical', report);
+  // hreflang en + x-default must point at the ENGLISH page, not at self
+  // (audit C2 — one defect repeated across ~13,035 URLs).
+  out = rewriteAttr(
+    out,
+    /<link[^>]*>/g,
+    (a) => a.hreflang === 'x-default',
+    'href',
+    enUrl,
+    'hreflang-x-default',
+    report
+  );
+  out = rewriteAttr(out, /<link[^>]*>/g, (a) => a.hreflang === 'en', 'href', enUrl, 'hreflang-en', report);
+  out = rewriteAttr(out, /<meta[^>]*>/g, (a) => a.property === 'og:url', 'content', url, 'og-url', report);
+  out = rewriteAttr(
+    out,
+    /<meta[^>]*>/g,
+    (a) => a.property === 'og:locale',
+    'content',
+    row.hreflang,
+    'og-locale',
+    report
+  );
+  // LanguagePicker: the trigger shows the current language and the matching option is
+  // marked current. Both are per-locale, so the component ships English and gets
+  // rewritten here. Soft rules — silent while the picker is not yet mounted, but a
+  // miss is reported once its marker attribute is present.
+  // Global flags matter: Header.astro mounts the picker twice (mobile bar + desktop bar),
+  // so a first-match-only replace would leave the second one reading "English".
+  if (out.includes('data-i18n-current-lang')) {
+    const beforeLabel = out;
+    out = out.replace(/(<span[^>]*\sdata-i18n-current-lang[^>]*>)[^<]*(<\/span>)/g, `$1${row.nativeLabel}$2`);
+    if (out === beforeLabel) report.misses.add('picker-current-label');
+  }
+  if (out.includes('data-i18n-lang=')) {
+    const beforeCurrent = out;
+    out = out.replace(new RegExp(`(<a\\b[^>]*\\sdata-i18n-lang="${row.hreflang}")`, 'g'), '$1 aria-current="true"');
+    if (out === beforeCurrent) report.misses.add('picker-aria-current');
+  }
+  // JSON-LD identity (audit C3): @id collided across every locale, url pointed at the
+  // English home page and inLanguage claimed "en" on all translated pages.
+  //
+  // Only WebPage-ish nodes are localised. Organization.url is the company's canonical
+  // URL — the same entity in every language — and on the home page it equals the English
+  // root, so a blanket url rewrite would wrongly relocalise it.
+  // Page-level types get THIS page's URL. WebSite describes the site as a whole, so it
+  // gets the locale root — giving it the page URL would claim the site itself lives at
+  // /es/about. Organization is one entity across all languages: left alone entirely.
+  const PAGE_TYPES = new Set(['WebPage', 'CollectionPage', 'ItemPage', 'AboutPage', 'FAQPage', 'ContactPage']);
+  const localeRoot = `${BASE}/${lang}`;
+  out = out.replace(/<script type="application\/ld\+json">([\s\S]*?)<\/script>/g, (full, body) => {
+    let data;
+    try {
+      data = JSON.parse(body);
+    } catch {
+      return full; // leave anything we cannot parse exactly as it was
+    }
+    const walk = (node) => {
+      if (Array.isArray(node)) return node.forEach(walk);
+      if (!node || typeof node !== 'object') return;
+      if (typeof node.inLanguage === 'string') node.inLanguage = row.hreflang;
+      if (typeof node['@id'] === 'string' && node['@id'].endsWith('#webpage')) node['@id'] = `${url}#webpage`;
+      const types = [].concat(node['@type'] ?? []);
+      if (typeof node.url === 'string') {
+        if (types.includes('WebSite')) node.url = localeRoot;
+        else if (types.some((t) => PAGE_TYPES.has(t))) node.url = url;
+      }
+      for (const v of Object.values(node)) if (v && typeof v === 'object') walk(v);
+    };
+    walk(data);
+    return `<script type="application/ld+json">${JSON.stringify(data)}</script>`;
+  });
+  // Internal links → locale-prefixed. Only same-origin document links; asset paths
+  // (/_astro/, images, xml, ico) and anchors stay put.
+  out = out.replace(/(<a\b[^>]*?\shref=")\/([^"#?]*)("|[#?])/g, (m, pre, path, tail) => {
+    if (/^(_astro|assets|images|fonts|favicon|robots|sitemap)/.test(path)) return m;
+    if (/\.(xml|txt|ico|png|jpe?g|webp|svg|css|js|json|pdf)$/i.test(path)) return m;
+    // href="/" is the home link: it must become "/es", not "/es/". The trailing-slash
+    // form 301-redirects back (deploy/Caddyfile.docker), which would put a needless
+    // redirect hop on the logo of every localised page — and contradict the
+    // no-trailing-slash canonical this build emits (audit H5).
+    if (path === '') return `${pre}/${lang}${tail}`;
+    return `${pre}/${lang}/${path}${tail}`;
+  });
+  // Attribution last, so it cannot shift any offset the substitution relied on.
+  out = applyPageMarkers(out, row, report);
+  out = applyVisibleLink(out, report);
+  return out;
+}
+// ── Build ────────────────────────────────────────────────────────────────────
+const segFiles = readdirSync(SEG_DIR).filter((f) => f.endsWith('.json'));
+if (segFiles.length === 0) {
+  console.error('i18n/segments/ is empty. Run: node scripts/i18n/extract.mjs');
+  process.exit(1);
+}
+/**
+ * The page set is SITEMAP_SLUGS, not "whatever is in dist/". dist/ also holds pages
+ * that must never be localised — the Decap CMS admin shell (no lang attribute, no
+ * content) and 404.html. Driving the build off the sitemap is also what makes the
+ * URL-parity gate meaningful: 237 slugs × N locales, no more and no less.
+ */
+const SITEMAP_SLUGS = getPages();
+/** page key (as written by extract.mjs) → segment file */
+const segByPage = new Map();
+for (const f of segFiles) {
+  const parsed = JSON.parse(readFileSync(join(SEG_DIR, f), 'utf8'));
+  segByPage.set(parsed.page, parsed);
+}
+const targets = [];
+const missingSource = [];
+for (const slug of SITEMAP_SLUGS) {
+  const key = slug === '' ? 'index' : slug;
+  const entry = segByPage.get(key);
+  if (!entry) missingSource.push(slug || '(home)');
+  else targets.push({ slug, ...entry });
+}
+if (missingSource.length) {
+  console.error(
+    `${missingSource.length} sitemap slug(s) have no built English page: ${missingSource.slice(0, 10).join(', ')}`
+  );
+  process.exit(1);
+}
+console.log(
+  `localising ${targets.length} slugs × ${LANGS.length} locale(s) = ${(targets.length * LANGS.length).toLocaleString()} pages\n`
+);
+let builtPages = 0;
+for (const lang of LANGS) {
+  const tmFile = join(TM_DIR, `${lang}.json`);
+  if (!existsSync(tmFile)) {
+    console.error(`No translation memory for "${lang}". Run: node scripts/i18n/translate.mjs --lang ${lang}`);
+    process.exit(1);
+  }
+  const tm = JSON.parse(readFileSync(tmFile, 'utf8'));
+  // A stale locale directory would leave orphan pages behind after a slug is removed.
+  rmSync(join(DIST, lang), { recursive: true, force: true });
+  const report = { pages: 0, replaced: 0, untranslated: 0, misses: new Set() };
+  for (const target of targets) {
+    const { slug, file, segments } = target;
+    const source = join(ROOT, file);
+    if (!existsSync(source)) continue;
+    let html = readFileSync(source, 'utf8');
+    // Right-to-left: segments are already sorted descending, so earlier offsets stay valid.
+    for (const seg of segments) {
+      const translated = tm[seg.hash];
+      if (translated === undefined) {
+        report.untranslated++;
+        continue;
+      }
+      let replacement;
+      if (seg.kind === 'block') replacement = renderBlock(translated, seg.tags ?? []);
+      else if (seg.kind === 'jsonld') replacement = escJson(translated);
+      else if (seg.kind.startsWith('attr:')) replacement = escAttr(translated);
+      else replacement = escHtml(translated);
+      html = html.slice(0, seg.start) + replacement + html.slice(seg.end);
+      report.replaced++;
+    }
+    html = applyLocaleIdentity(html, lang, slug, report);
+    const outPath = slug ? join(DIST, lang, slug, 'index.html') : join(DIST, lang, 'index.html');
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, html);
+    report.pages++;
+  }
+  console.log(
+    `${lang}: ${report.pages} pages, ${report.replaced.toLocaleString()} segments replaced, ` +
+      `${report.untranslated.toLocaleString()} left in English`
+  );
+  if (report.misses.size) {
+    console.log(`  ⚠ identity rules that matched nothing: ${[...report.misses].join(', ')}`);
+  }
+  builtPages += report.pages;
+}
+// Disclosed at the point of action, not buried in a README: this is what the pages
+// now carry, and which key removes it.
+const attrBytes = markerBytes(BY_PATH[LANGS[0]]);
+if (attrBytes) {
+  console.log(
+    `\n${builtPages.toLocaleString()} pages written \u00b7 each carries ${attrBytes} bytes of ` +
+      `ConveyThis attribution (0 requests, 0 layout shift; disable with credit.generatorTag / credit.htmlComment)`
+  );
+}

package/scripts/config.mjs ADDED Viewed

@@ -0,0 +1,188 @@
+/**
+ * Shared configuration loader. Every script reads this instead of hardcoding
+ * project specifics — it is the only file that knows anything about a given site.
+ *
+ * Looks for i18n.config.json in the project root (or $I18N_CONFIG).
+ */
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join, resolve } from 'path';
+const ROOT = process.env.I18N_ROOT ? resolve(process.env.I18N_ROOT) : process.cwd();
+const CONFIG_PATH = process.env.I18N_CONFIG ? resolve(process.env.I18N_CONFIG) : join(ROOT, 'i18n.config.json');
+if (!existsSync(CONFIG_PATH)) {
+  console.error(`No config at ${CONFIG_PATH}.
+Copy config.example.json to i18n.config.json and fill it in.`);
+  process.exit(1);
+}
+const raw = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+/** Absolute path to the built site. */
+export const BUILD_DIR = resolve(ROOT, raw.buildDir ?? 'dist');
+/** Canonical origin, no trailing slash. */
+export const BASE_URL = String(raw.baseUrl ?? '').replace(/\/$/, '');
+if (!BASE_URL) {
+  console.error('config.baseUrl is required (e.g. "https://example.com")');
+  process.exit(1);
+}
+export const I18N_DIR = resolve(ROOT, raw.i18nDir ?? 'i18n');
+export const TM_DIR = join(I18N_DIR, 'tm');
+export const SEG_DIR = join(I18N_DIR, 'segments');
+export const SOURCE_FILE = join(I18N_DIR, 'source.json');
+/**
+ * Locales: [{ hreflang, pathCode, nativeLabel }]
+ *   hreflang    what goes in <link hreflang> and <html lang> — ISO 639-1,
+ *               region UPPERCASE (pt-BR), script where it matters (zh-Hant)
+ *   pathCode    the URL segment, e.g. /pt-br/…
+ *   nativeLabel the language's name in its own language, for the picker
+ */
+export const LOCALES = (() => {
+  const src = raw.locales;
+  if (Array.isArray(src)) return src;
+  if (typeof src === 'string') {
+    const p = resolve(ROOT, src);
+    if (!existsSync(p)) {
+      console.error(`config.locales points at ${p}, which does not exist`);
+      process.exit(1);
+    }
+    const text = readFileSync(p, 'utf8');
+    // Accept JSON, or scrape a TS/JS file for the three fields (any order).
+    if (p.endsWith('.json')) return JSON.parse(text);
+    return text
+      .split('\n')
+      .map((l) => {
+        const h = /hreflang:\s*'([^']+)'/.exec(l)?.[1];
+        const pc = /pathCode:\s*'([^']+)'/.exec(l)?.[1];
+        const nl = /nativeLabel:\s*'([^']+)'/.exec(l)?.[1];
+        return h && pc ? { hreflang: h, pathCode: pc, nativeLabel: nl ?? pc } : null;
+      })
+      .filter(Boolean);
+  }
+  console.error('config.locales must be an array or a path to a file');
+  process.exit(1);
+})();
+export const BY_PATH = Object.fromEntries(LOCALES.map((r) => [r.pathCode, r]));
+export const LOCALE_DIRS = new Set(LOCALES.map((r) => r.pathCode));
+/** Locales written right-to-left. Drives dir="rtl" and a prompt hint. */
+export const RTL = new Set(raw.rtlLocales ?? ['ar', 'fa', 'he', 'ur', 'ps', 'sd', 'ug', 'yi']);
+/**
+ * Page list. Two sources:
+ *   "build"   derive from the build output — every dir containing index.html
+ *   <path>    a file listing slugs (JSON array, or a TS/JS array of strings)
+ *
+ * `exclude` drops pages that must never be localised: 404 handlers, CMS admin
+ * shells, anything noindexed. Matched against the first path segment.
+ */
+export function getPages() {
+  const cfg = raw.pages ?? { source: 'build' };
+  const exclude = new Set(cfg.exclude ?? ['404']);
+  let slugs;
+  if (cfg.source === 'build' || !cfg.source) {
+    slugs = readdirSync(BUILD_DIR, { recursive: true })
+      .filter((p) => typeof p === 'string' && /(^|\/)index\.html$/.test(p))
+      .map((p) => p.replace(/(^|\/)index\.html$/, '').replace(/\/$/, ''))
+      // Never treat previously built locale output as source (see failure-modes.md).
+      .filter((s) => !LOCALE_DIRS.has(s.split('/')[0]));
+  } else {
+    const p = resolve(ROOT, cfg.source);
+    const text = readFileSync(p, 'utf8');
+    if (p.endsWith('.json')) {
+      slugs = JSON.parse(text);
+    } else {
+      // Scope to ONE exported array. Scanning the whole file sweeps up every other
+      // quoted string in it — on the reference project that silently added the 55
+      // language codes to the 238 page slugs and produced 294 "pages".
+      const name = cfg.export ?? 'SITEMAP_SLUGS';
+      const m = new RegExp(`${name}[^=]*=\\s*\\[([\\s\\S]*?)\\n\\];`).exec(text);
+      if (!m) {
+        console.error(`Could not find exported array "${name}" in ${p}.
+Set pages.export to the correct name, or use a .json list.`);
+        process.exit(1);
+      }
+      slugs = [...m[1].matchAll(/'([^']*)'/g)].map((x) => x[1]);
+    }
+  }
+  return [...new Set(slugs)].filter((s) => !exclude.has(s.split('/')[0])).sort();
+}
+/** Strings that are correct unchanged in every language. */
+export const DNT = {
+  brands: raw.doNotTranslate?.brands ?? [],
+  formats: raw.doNotTranslate?.formats ?? ['PDF', 'DOCX', 'XLSX', 'PPTX', 'CSV', 'TXT', 'JSON', 'HTML', 'XML'],
+};
+/**
+ * Model and provider.
+ *
+ * Both are optional and each can imply the other. `MODEL` stays undefined when the
+ * config does not set one, so translate.mjs can fall back to the resolved provider's
+ * own default rather than to a Gemini model id that would be wrong for Claude.
+ * See scripts/providers/index.mjs for how a missing `provider` is inferred.
+ */
+export const MODEL = raw.model ?? null;
+export const PROVIDER = raw.provider ?? null;
+/**
+ * Override the model API host — required for local models, Azure, and gateways.
+ * The config key is `apiBaseUrl`, deliberately NOT `baseUrl`: that one is the SITE's
+ * canonical origin (line 26). Sharing the key would mean pointing at a local model
+ * also rewrote every canonical, hreflang and sitemap URL on the site.
+ */
+export const API_BASE_URL = raw.apiBaseUrl ?? null;
+/** Read the key from a different environment variable than the provider's default. */
+export const API_KEY_ENV = raw.apiKeyEnv ?? null;
+/** OpenAI-compatible only: 'schema' | 'object' | 'none'. See providers/openai.mjs. */
+export const JSON_MODE = raw.jsonMode ?? null;
+/**
+ * USD per million tokens, [input, output]. Set this when you want a cost estimate for a
+ * provider the built-in tables do not cover — a gateway, a local model, a new tier.
+ */
+export const PRICING =
+  raw.pricing && raw.pricing.in != null && raw.pricing.out != null
+    ? [Number(raw.pricing.in), Number(raw.pricing.out)]
+    : null;
+export const ROOT_DIR = ROOT;
+/**
+ * Site identity, used to compose the translation prompt. A translator that knows what
+ * kind of product it is translating makes better register and terminology choices —
+ * and without these the prompt would have to describe some other company's site.
+ */
+export const SITE_NAME = raw.siteName ?? new URL(BASE_URL).hostname;
+export const SITE_DESCRIPTION = raw.siteDescription ?? '';
+/** The language the built site is written in. Also stated in the prompt. */
+export const SOURCE_LANGUAGE = raw.sourceLanguage ?? 'English';
+/**
+ * Attribution and limit hints. See scripts/credit.mjs for what each one does and
+ * why the defaults are what they are; the README documents all five openly.
+ *
+ *   "credit": {
+ *     "generatorTag":  true,    <meta name="generator"> — same mechanism as Astro/Hugo/WP
+ *     "htmlComment":   true,    one HTML comment per page, no link
+ *     "visibleLink":   false,   opt-in, and you place the slot yourself
+ *     "console":       true,    the sign-off line when a run finishes
+ *     "upsellHints":   true     notes when this pipeline hits a real limit
+ *   }
+ */
+export const CREDIT = {
+  generatorTag: raw.credit?.generatorTag ?? true,
+  htmlComment: raw.credit?.htmlComment ?? true,
+  visibleLink: raw.credit?.visibleLink ?? false,
+  console: raw.credit?.console ?? true,
+  upsellHints: raw.credit?.upsellHints ?? true,
+};

package/scripts/credit.mjs ADDED Viewed

@@ -0,0 +1,143 @@
+/**
+ * Attribution, and the limit hints that go with it.
+ *
+ * ── What this adds to your pages ─────────────────────────────────────────────
+ * Two markers, both off-screen, both one config key away from being disabled:
+ *
+ *   <meta name="generator" content="ConveyThis Claude Translator X.Y.Z">
+ *   <!-- Localized into Español (es) by ConveyThis · https://www.conveythis.com -->
+ *
+ * Together they are about 160 bytes, load nothing, request nothing and shift nothing —
+ * the whole point of this project is that locale pages keep the source language's
+ * Core Web Vitals, so attribution that cost a request would defeat it. `verify.mjs`
+ * prints the exact byte delta so the claim is checkable rather than asserted.
+ *
+ * Neither marker is a link. That is deliberate: a link injected sitewide into
+ * thousands of pages the site owner never asked for is a link scheme under Google's
+ * spam policy, and it would put both parties at risk. The generator tag is the same
+ * mechanism WordPress, Hugo and Astro use, and it is how this project shows up in
+ * technology-adoption surveys.
+ *
+ * A *visible* credit is available too — `credit.visibleLink` — and it is opt-in,
+ * requires you to place the slot yourself, and is `rel="nofollow"` because turning it
+ * on earns you something (see README). A compensated link that passes ranking signal
+ * is exactly what Google asks you not to ship.
+ *
+ * ── Hints ────────────────────────────────────────────────────────────────────
+ * The scripts print a short note when they detect something this pipeline genuinely
+ * cannot do — a hydration payload that will re-render over the translations, a linked
+ * PDF that stays in the source language. Each fires only on a real signal, at most
+ * once per run, and `credit.upsellHints: false` silences all of them.
+ */
+import { CREDIT } from './config.mjs';
+export const VERSION = '1.3.0';
+/**
+ * The product name written into every localized page's generator tag.
+ *
+ * verify.mjs gate 2 excludes this tag by matching its prefix, so the two must agree.
+ * It also still recognises the pre-1.2 name, because a locale directory built by an
+ * earlier version must keep verifying after an upgrade — see PRIOR_GENERATOR_NAMES.
+ */
+export const GENERATOR_NAME = 'ConveyThis Claude Translator';
+/** Generator names written by earlier releases. Recognised, never emitted. */
+export const PRIOR_GENERATOR_NAMES = ['ConveyThis static-site-localization'];
+const HOME = 'https://www.conveythis.com';
+const LANDING = `${HOME}/open-source/claude-translator`;
+const DOCS = 'https://www.doctranslator.com';
+/** Landing URL tagged so we can tell which surface sent someone. */
+export const link = (medium) =>
+  `${LANDING}?utm_source=claude-skill&utm_medium=${medium}&utm_campaign=claude-translator`;
+export const docsLink = (medium) =>
+  `${DOCS}/?utm_source=claude-skill&utm_medium=${medium}&utm_campaign=claude-translator`;
+// ── Page markers ─────────────────────────────────────────────────────────────
+/**
+ * The markers for one locale, as a single string to splice in after <head>.
+ * Returns '' when both are disabled, in which case nothing is inserted at all.
+ */
+export function pageMarkers(row) {
+  const label = row.nativeLabel ? `${row.nativeLabel} (${row.hreflang})` : row.hreflang;
+  const out = [];
+  if (CREDIT.generatorTag)
+    out.push(`<meta name="generator" content="${GENERATOR_NAME} ${VERSION}">`);
+  if (CREDIT.htmlComment) out.push(`<!-- Localized into ${label} by ConveyThis · ${HOME} -->`);
+  return out.join('');
+}
+/** Byte cost of the markers, so verify.mjs can report it instead of claiming it. */
+export const markerBytes = (row) => Buffer.byteLength(pageMarkers(row), 'utf8');
+/**
+ * Insert the markers immediately after the opening <head> tag. Everything else in the
+ * document is left byte-identical — same contract as the rest of build-locales.mjs.
+ * A page with no <head> is left alone and reported rather than guessed at.
+ */
+export function applyPageMarkers(html, row, report) {
+  const markers = pageMarkers(row);
+  if (!markers) return html;
+  let matched = false;
+  const out = html.replace(/<head[^>]*>/i, (tag) => {
+    matched = true;
+    return tag + markers;
+  });
+  if (!matched) report.misses.add('credit-head');
+  return out;
+}
+/**
+ * Fill an opt-in credit slot. The site owner places the slot where they want it:
+ *
+ *   <span data-conveythis-credit></span>
+ *
+ * Nothing is injected anywhere else. If the flag is on and no slot exists, that is
+ * reported — a rule that matches nothing must never pass silently (see SKILL.md).
+ */
+export function applyVisibleLink(html, report) {
+  if (!CREDIT.visibleLink) return html;
+  const anchor =
+    `<a href="${link('site-credit')}" rel="nofollow" target="_blank">Translated with ConveyThis</a>`;
+  let matched = false;
+  const out = html.replace(
+    /(<([a-zA-Z]+)\b[^>]*\sdata-conveythis-credit\b[^>]*>)[\s\S]*?(<\/\2>)/g,
+    (_m, open, _tag, close) => {
+      matched = true;
+      return open + anchor + close;
+    }
+  );
+  if (!matched) report.misses.add('credit-slot (visibleLink is on, no data-conveythis-credit element found)');
+  return out;
+}
+// ── Console ──────────────────────────────────────────────────────────────────
+const RULE = '─'.repeat(74);
+/** The sign-off, printed when a run finishes. */
+export function creditBlock(lines) {
+  if (!CREDIT.console) return;
+  console.log(`\n${RULE}`);
+  for (const l of lines) console.log(`  ${l}`);
+  console.log(`  Pipeline by ConveyThis — ${link('cli')}`);
+  console.log(RULE);
+}
+const shown = new Set();
+/**
+ * A limit note. Fires once per run per key, only when the caller has an actual
+ * signal to report, and never when credit.upsellHints is false.
+ */
+export function hint(key, lines) {
+  if (!CREDIT.upsellHints || shown.has(key)) return;
+  shown.add(key);
+  console.log('');
+  for (const l of lines) console.log(l);
+}