@techninja/clearstack 0.4.0 → 0.4.3

package/bin/cli.js

@@ -62,7 +62,7 @@ async function run(action) {
   } else if (action === 'check') {
     const subs = args.filter((a) => a !== cmd && !a.startsWith('-'));
     const { check } = await import('../lib/check.js');
-    await check(process.cwd(), subs.join(' ') || undefined);
+    await check(process.cwd(), subs.join(' ') || undefined, { verbose: !!flags.verbose });
   } else if (action === 'report') {
     const { report } = await import('../lib/report.js');
     report(process.cwd(), { json: !!flags.json });

package/docs/I18N.md

@@ -4,12 +4,18 @@
 
 Hardcoding UI strings is a foot gun. Retrofitting i18n into an existing app
 requires touching every component — a painful, error-prone refactor. Starting
-with `t('key')` from day one costs almost nothing and keeps the door open while
-also clearly separating UI and exact wording concerns.
+with `t('key')` or `msg\`` from day one costs almost nothing and keeps the door
+open while also clearly separating UI copy from component logic.
 
-## The Pattern
+## Two Patterns — Use Both
 
-A 4-layer message cascade. Last layer wins:
+Clearstack supports two complementary approaches. They are not mutually
+exclusive; most apps will use both.
+
+### Pattern A — `t()` cascade (non-template strings)
+
+A 4-layer message cascade resolved at call time. Best for strings outside
+Hybrids templates: error messages, queue status, validators, utility functions.
 
 ```
 1. App defaults     → DEFAULTS in utils/i18n.js (English, ships with app)
@@ -18,91 +24,174 @@ A 4-layer message cascade. Last layer wins:
 4. Locale overrides → /locales/overrides.<lang>.json (project customizes locale)
 ```
 
-This means:
+```js
+import { t, loadLocale } from '#utils/i18n.js';
+
+// Call once at app init
+await loadLocale(navigator.language);
+
+t('general.loading')                    // → 'Loading…'
+t('task.empty')                         // → 'No tasks yet.'
+t('greeting', { name: 'James' })        // → 'Hello, James!'
+t('missing.key')                        // → 'missing.key' (never throws)
+```
 
-- The platform ships sensible English defaults
-- Projects override just what they need in `overrides.json`
-- Adding a new language only requires a `<lang>.json` file
-- No build step, no external dependency
+### Pattern B — `localize` + `msg\`` (Hybrids-native, template strings)
 
-## Usage
+Hybrids has first-class i18n built in. Template text content is **translated
+automatically** — no source changes needed for simple strings. Use `msg\`` for
+dynamic values, plural forms, and attribute content.
 
 ```js
-import { t, loadLocale } from '#utils/i18n.js';
+import { html, define, localize, msg } from 'hybrids';
 
-// Call once at app init (router or top-level component connect)
-await loadLocale(navigator.language);
+// Simple static text — translated automatically, no code change needed
+html`<button>Save</button>`
 
-// Simple key
-t('general.loading')              // → 'Loading…'
+// Dynamic value in a template
+html`<div>${msg`${count} variants scored`}</div>`
 
-// With interpolation
-t('order.thanks', { name: 'James' })  // → 'Thanks, James!'
+// As an attribute
+html`<my-button label="${msg`Submit`}"></my-button>`
 
-// Falls back to key if not found — never throws
-t('missing.key')                  // → 'missing.key'
+// Load translations once before first render (router/index.js or app init)
+import { localize } from 'hybrids';
+const msgs = await fetch('/locales/es.json').then(r => r.json());
+localize('es', msgs);
 ```
 
-## Key Naming Convention
+#### Plural Forms
+
+The `msg\`` helper uses`Intl.PluralRules` automatically when the dictionary
+entry is an object with plural keys:
 
-`domain.action` or `component.concept` — dot-separated, lowercase, no spaces.
+```js
+// In a template:
+html`<p>${msg`${count} variants matched`}</p>`
 
+// In locales/es.json (or via localize()):
+{
+  "${0} variants matched": {
+    "message": {
+      "one": "${0} variante encontrada",
+      "other": "${0} variantes encontradas",
+      "zero": "Ninguna variante encontrada"
+    }
+  }
+}
 ```
-general.loading     general.error      general.back
-nav.home            nav.signIn         nav.signOut
-cart.add            cart.empty         cart.checkout
-product.inStock     product.outOfStock
-error.notFound      error.offline
+
+For English-only apps with irregular plurals, use `msg\`` with a`localize('default', ...)` entry:
+
+```js
+// Avoids inline ternaries like: `${n} trait${n !== 1 ? 's' : ''}`
+html`<p>${msg`${n} traits scored`}</p>`
+
+localize('default', {
+  '${0} traits scored': {
+    message: { one: '${0} trait scored', other: '${0} traits scored' }
+  }
+});
 ```
 
-Avoid generic keys like `button1` or `label`. Keys should be readable as
-documentation.
+## Which Pattern to Use
+
+| Situation | Pattern |
+|---|---|
+| String inside `html\`` template | B — auto-translated or `msg\`` |
+| Plural form | B — `msg\`` + plural object |
+| String outside a template (util, queue, validator) | A — `t()` |
+| Attribute value on a component | B — `msg\`` in expression |
+| Brand voice / English overrides | A — `overrides.json` |
+| Adding a full language | B — `localize(lang, msgs)` |
 
 ## App Init
 
-Call `loadLocale()` once before rendering. In a Hybrids app, the router's
-`connect` is the right place:
+Call `loadLocale()` (Pattern A) and/or `localize()` (Pattern B) once before
+first render. The router's `connect` is the right place in a Hybrids app:
 
 ```js
 // router/index.js
 import { loadLocale } from '#utils/i18n.js';
+import { localize } from 'hybrids';
 
-await loadLocale(navigator.language);
+// Pattern A — cascade for non-template strings
+loadLocale(navigator.language);
+
+// Pattern B — load a locale file for template auto-translation
+const lang = navigator.language.split('-')[0];
+if (lang !== 'en') {
+  fetch(`/locales/${lang}.json`)
+    .then(r => r.ok ? r.json() : {})
+    .then(msgs => localize(lang, msgs));
+}
 ```
 
-For SSR/static sites, call it in the page's `connect` handler instead.
+## Key Naming Convention (Pattern A)
 
-## Adding a Language
+`domain.concept` — dot-separated, lowercase, no spaces. Keys should read as
+documentation.
+
+```
+general.loading     general.error      general.save       general.cancel
+nav.home            nav.back           nav.signIn
+error.notFound      error.offline
+task.empty          task.addTask       task.deleteConfirm
+```
 
-1. Create `/locales/<lang>.json` with translated keys
-2. Only include keys that differ from English — missing keys fall back to defaults
-3. Optionally add `/locales/overrides.<lang>.json` for project-specific overrides
+Avoid `button1`, `label`, or anything that doesn't describe the content.
+
+## Extracting Keys (Pattern B)
+
+Hybrids ships a CLI extractor that scans source files and generates a
+translation-ready JSON file:
+
+```bash
+npx hybrids extract ./src ./locales/en.json
+npx hybrids extract --include-path ./src ./locales/en.json
+```
+
+Wire it as a script so translators always have a fresh key file:
 
 ```json
-// locales/es.json
-{
-  "general.loading": "Cargando…",
-  "general.error": "Algo salió mal.",
-  "nav.home": "Inicio"
-}
+{ "scripts": { "i18n:extract": "hybrids extract ./src ./locales/en.json" } }
 ```
 
-## Project Overrides
+The extractor is optional — use it when you're ready to hand off to a
+translator or add a second language.
 
-To customize English strings (e.g. brand voice) without touching `i18n.js`:
+## Adding a Language
 
-```json
-// locales/overrides.json
-{
-  "general.loading": "Analyzing your DNA…",
-  "error.offline": "Check your connection and try again."
-}
+1. Run `npm run i18n:extract` to get the current key list
+2. Translate into `locales/<lang>.json` — only include keys that differ
+3. Load it at init via `localize(lang, msgs)`
+4. For Pattern A overrides: add `locales/overrides.<lang>.json`
+
+## Spec Check
+
+`npm run spec code i18n` reports readiness without blocking the build:
+
+```
+✅ i18n readiness (12ms)
+   Pattern:   t() ×9, msg` ×3
+   Init:      yes · Overrides: yes · Languages: es, fr
+   Unwrapped: ~4 prose strings across 2 template files
 ```
 
+- **Pattern** — which i18n calls are present and how many files use them
+- **Init** — whether `loadLocale` or `localize` is called at startup
+- **Overrides** — whether `locales/overrides.json` exists
+- **Languages** — locale files found beyond English
+- **Unwrapped** — estimated prose strings in templates not yet wrapped in
+  `t()`/`msg\`` (heuristic, not exhaustive)
+
+The check always passes — it surfaces gaps, not failures.
+
 ## Rules
 
-- **Always use `t()`** for any user-visible string in components
-- **Never hardcode UI strings** in component render functions
-- **Keys fall back to themselves** — `t('missing')` returns `'missing'`, never crashes
+- **Always use `t()` or `msg\`** for any user-visible string in components
+- **Never hardcode UI strings** directly in render functions
+- **Plural forms belong in the dictionary**, not inline ternaries
 - **`loadLocale()` is safe to call multiple times** — last call wins
 - **Locale files are optional** — English-only apps just use `overrides.json`
+- **Keys fall back to themselves** — `t('missing')` returns `'missing'`, never throws

package/lib/check.js

@@ -7,12 +7,14 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { checkFileLines, runCmd, countFiles, checkImports } from './spec-utils.js';
+import { checkI18n } from './spec-i18n.js';
 import { loadConfig, buildCmds, detectRunner } from './spec-config.js';
 
 export { checkFileLines, runCmd, countFiles, findFiles, elapsed, checkImports } from './spec-utils.js';
+export { checkI18n } from './spec-i18n.js';
 export { loadConfig, buildCmds, detectRunner } from './spec-config.js';
 
-/** @typedef {{ key: string, name: string, parent?: string, run: () => boolean }} Check */
+/** @typedef {{ key: string, name: string, parent?: string, run: (opts?: object) => boolean }} Check */
 
 /** Find all jsconfig.json files — main config + subdirectories. */
 function findTypeConfigs(dir, runner) {
@@ -48,8 +50,10 @@ export function buildChecks(dir, cfg, cmds) {
       run: () => runCmd('Markdown', cmds.mdlint, dir, `${md()} files`).pass },
     { key: 'prettier', name: 'Prettier', parent: 'format',
       run: () => runCmd('Prettier', cmds.prettier, dir, `${js()} files`).pass },
-    { key: 'code', name: `Code (max ${cfg.codeMax} lines)`,
+    { key: 'lines', name: `Code (max ${cfg.codeMax} lines)`, parent: 'code',
       run: () => checkFileLines(dir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`, { exclude: cfg.testPattern }).pass },
+    { key: 'i18n', name: 'i18n readiness', parent: 'code',
+      run: (runOpts) => checkI18n(dir, cfg.ignore, 'i18n readiness', runOpts).pass },
     { key: 'tests', name: `Tests (max ${cfg.testMax} lines)`,
       run: () => checkFileLines(dir, cfg.codeExt, cfg.testMax, cfg.ignore, `Tests (max ${cfg.testMax} lines)`, { include: cfg.testPattern }).pass },
     { key: 'docs', name: `Docs (max ${cfg.docsMax} lines)`,
@@ -81,7 +85,7 @@ export function parentKeys(checks) {
 }
 
 /** Run the full spec compliance check (used by clearstack CLI and scripts/spec.js). */
-export async function check(projectDir, scope) {
+export async function check(projectDir, scope, opts) {
   const cfg = loadConfig(projectDir);
   const cmds = buildCmds(projectDir);
   const checks = buildChecks(projectDir, cfg, cmds);
@@ -94,13 +98,13 @@ export async function check(projectDir, scope) {
       console.log(`Available: ${[...tops, ...parentKeys(checks)].join(', ')}`);
       process.exit(1);
     }
-    const ok = matched.every((c) => c.run());
+    const ok = matched.every((c) => c.run(opts));
     if (!ok) process.exit(1);
     return;
   }
 
   console.log('🔍 Clearstack compliance checking now... 💙\n');
-  const results = checks.map((c) => c.run());
+  const results = checks.map((c) => c.run(opts));
   const passed = results.filter(Boolean).length;
   console.log(`\n${'='.repeat(40)}`);
   console.log(`${passed}/${results.length} checks passed.`);

package/lib/spec-i18n.js

@@ -0,0 +1,119 @@
+/**
+ * i18n readiness check — detects patterns, locale files, hardcoded prose density.
+ * Always passes (informational). Surfaces coverage gaps without blocking the build.
+ * @module lib/spec-i18n
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { findFiles, elapsed } from './spec-utils.js';
+
+/** @typedef {import('./spec-utils.js').CheckResult} CheckResult */
+
+const PROSE_RE = />\s*[A-Z][a-z]{2,}[^<$`\\]{3,}\s*[<$]/g;
+const T_RE = /\bt\s*\(/;
+const MSG_RE = /\bmsg`/;
+const LOC_RE = /\blocalize\s*\(/;
+const INIT_RE = /loadLocale|localize\s*\(/;
+const TPL_RE = /html`[\s\S]*?`/g;
+
+/** Strip leading > and trailing <$ from a prose match, trim. */
+const cleanHit = (h) => h.replace(/^>\s*/, '').replace(/\s*[<$]$/, '').trim();
+
+/**
+ * Check i18n readiness — informational, always passes.
+ * @param {string} root
+ * @param {string[]} ignoreDirs
+ * @param {string} label
+ * @param {{ quiet?: boolean, verbose?: boolean }} [opts]
+ * @returns {CheckResult}
+ */
+export function checkI18n(root, ignoreDirs, label, opts) {
+  const start = performance.now();
+  const srcFiles = findFiles(root, ['.js'], ignoreDirs, root).filter(
+    (f) =>
+      f.startsWith('src/') &&
+      !f.includes('vendor/') &&
+      !f.includes('deps/') &&
+      !f.endsWith('.test.js'),
+  );
+
+  let usesT = 0,
+    usesMsg = 0,
+    usesLocalize = 0,
+    hasInit = false,
+    hardcodedHits = 0,
+    templateFiles = 0;
+  /** @type {Array<{file: string, text: string, line: number}>} */
+  const verboseHits = [];
+
+  for (const file of srcFiles) {
+    const src = readFileSync(resolve(root, file), 'utf-8');
+    if (T_RE.test(src)) usesT++;
+    if (MSG_RE.test(src)) usesMsg++;
+    if (LOC_RE.test(src)) usesLocalize++;
+    if (/router\/index|app.*init|main\.js/.test(file) && INIT_RE.test(src)) hasInit = true;
+    const templates = src.match(TPL_RE);
+    if (templates) {
+      templateFiles++;
+      for (const tpl of templates) {
+        const hits = tpl.match(PROSE_RE);
+        if (hits) {
+          hardcodedHits += hits.length;
+          if (opts?.verbose) {
+            for (const h of hits) {
+              const text = cleanHit(h);
+              const idx = src.indexOf(text);
+              const line = idx >= 0 ? src.slice(0, idx).split('\n').length : 0;
+              verboseHits.push({ file, text, line });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  const localesDir = existsSync(resolve(root, 'src/locales'))
+    ? resolve(root, 'src/locales')
+    : existsSync(resolve(root, 'locales'))
+      ? resolve(root, 'locales')
+      : null;
+
+  const localeFiles = localesDir
+    ? readdirSync(localesDir).filter((f) => f.endsWith('.json') && f !== 'overrides.json')
+    : [];
+  const languages = localeFiles.map((f) => f.replace(/\.json$/, '').replace(/^overrides\./, ''));
+  const hasOverrides = localesDir ? existsSync(resolve(localesDir, 'overrides.json')) : false;
+
+  const patternParts = [
+    usesT ? `t() \u00d7${usesT}` : '',
+    usesMsg ? `msg\` \u00d7${usesMsg}` : '',
+    usesLocalize ? `localize() \u00d7${usesLocalize}` : '',
+  ].filter(Boolean);
+
+  const time = elapsed(start);
+  if (!opts?.quiet) {
+    const icon = patternParts.length ? '\u2705' : '\u26a0\ufe0f ';
+    const pattern = patternParts.length ? patternParts.join(', ') : 'none detected';
+    const langs = languages.length ? languages.join(', ') : 'en only';
+    const init = `${hasInit ? 'yes' : 'not detected'} \u00b7 Overrides: ${hasOverrides ? 'yes' : 'no'} \u00b7 Languages: ${langs}`;
+    const unwrapped = hardcodedHits > 0 ? `\n     Unwrapped: ~${hardcodedHits} prose strings across ${templateFiles} template files` : '';
+    console.log(`  ${icon} ${label} (${time})\n     Pattern:   ${pattern}\n     Init:      ${init}${unwrapped}`);
+    if (opts?.verbose && verboseHits.length) {
+      console.log('');
+      const byFile = {};
+      for (const v of verboseHits) {
+        (byFile[v.file] ||= []).push(v);
+      }
+      for (const [file, entries] of Object.entries(byFile)) {
+        console.log(`     ${file}`);
+        for (const e of entries) {
+          const truncated = e.text.length > 60 ? e.text.slice(0, 60) + '\u2026' : e.text;
+          console.log(`       L${e.line || '?'} ${truncated}`);
+        }
+      }
+    }
+  }
+
+  return { pass: true, label, time };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.4.0",
+  "version": "0.4.3",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {

package/templates/shared/docs/clearstack/I18N.md

@@ -4,12 +4,18 @@
 
 Hardcoding UI strings is a foot gun. Retrofitting i18n into an existing app
 requires touching every component — a painful, error-prone refactor. Starting
-with `t('key')` from day one costs almost nothing and keeps the door open while
-also clearly separating UI and exact wording concerns.
+with `t('key')` or `msg\`` from day one costs almost nothing and keeps the door
+open while also clearly separating UI copy from component logic.
 
-## The Pattern
+## Two Patterns — Use Both
 
-A 4-layer message cascade. Last layer wins:
+Clearstack supports two complementary approaches. They are not mutually
+exclusive; most apps will use both.
+
+### Pattern A — `t()` cascade (non-template strings)
+
+A 4-layer message cascade resolved at call time. Best for strings outside
+Hybrids templates: error messages, queue status, validators, utility functions.
 
 ```
 1. App defaults     → DEFAULTS in utils/i18n.js (English, ships with app)
@@ -18,91 +24,174 @@ A 4-layer message cascade. Last layer wins:
 4. Locale overrides → /locales/overrides.<lang>.json (project customizes locale)
 ```
 
-This means:
+```js
+import { t, loadLocale } from '#utils/i18n.js';
+
+// Call once at app init
+await loadLocale(navigator.language);
+
+t('general.loading')                    // → 'Loading…'
+t('task.empty')                         // → 'No tasks yet.'
+t('greeting', { name: 'James' })        // → 'Hello, James!'
+t('missing.key')                        // → 'missing.key' (never throws)
+```
 
-- The platform ships sensible English defaults
-- Projects override just what they need in `overrides.json`
-- Adding a new language only requires a `<lang>.json` file
-- No build step, no external dependency
+### Pattern B — `localize` + `msg\`` (Hybrids-native, template strings)
 
-## Usage
+Hybrids has first-class i18n built in. Template text content is **translated
+automatically** — no source changes needed for simple strings. Use `msg\`` for
+dynamic values, plural forms, and attribute content.
 
 ```js
-import { t, loadLocale } from '#utils/i18n.js';
+import { html, define, localize, msg } from 'hybrids';
 
-// Call once at app init (router or top-level component connect)
-await loadLocale(navigator.language);
+// Simple static text — translated automatically, no code change needed
+html`<button>Save</button>`
 
-// Simple key
-t('general.loading')              // → 'Loading…'
+// Dynamic value in a template
+html`<div>${msg`${count} variants scored`}</div>`
 
-// With interpolation
-t('order.thanks', { name: 'James' })  // → 'Thanks, James!'
+// As an attribute
+html`<my-button label="${msg`Submit`}"></my-button>`
 
-// Falls back to key if not found — never throws
-t('missing.key')                  // → 'missing.key'
+// Load translations once before first render (router/index.js or app init)
+import { localize } from 'hybrids';
+const msgs = await fetch('/locales/es.json').then(r => r.json());
+localize('es', msgs);
 ```
 
-## Key Naming Convention
+#### Plural Forms
+
+The `msg\`` helper uses`Intl.PluralRules` automatically when the dictionary
+entry is an object with plural keys:
 
-`domain.action` or `component.concept` — dot-separated, lowercase, no spaces.
+```js
+// In a template:
+html`<p>${msg`${count} variants matched`}</p>`
 
+// In locales/es.json (or via localize()):
+{
+  "${0} variants matched": {
+    "message": {
+      "one": "${0} variante encontrada",
+      "other": "${0} variantes encontradas",
+      "zero": "Ninguna variante encontrada"
+    }
+  }
+}
 ```
-general.loading     general.error      general.back
-nav.home            nav.signIn         nav.signOut
-cart.add            cart.empty         cart.checkout
-product.inStock     product.outOfStock
-error.notFound      error.offline
+
+For English-only apps with irregular plurals, use `msg\`` with a`localize('default', ...)` entry:
+
+```js
+// Avoids inline ternaries like: `${n} trait${n !== 1 ? 's' : ''}`
+html`<p>${msg`${n} traits scored`}</p>`
+
+localize('default', {
+  '${0} traits scored': {
+    message: { one: '${0} trait scored', other: '${0} traits scored' }
+  }
+});
 ```
 
-Avoid generic keys like `button1` or `label`. Keys should be readable as
-documentation.
+## Which Pattern to Use
+
+| Situation | Pattern |
+|---|---|
+| String inside `html\`` template | B — auto-translated or `msg\`` |
+| Plural form | B — `msg\`` + plural object |
+| String outside a template (util, queue, validator) | A — `t()` |
+| Attribute value on a component | B — `msg\`` in expression |
+| Brand voice / English overrides | A — `overrides.json` |
+| Adding a full language | B — `localize(lang, msgs)` |
 
 ## App Init
 
-Call `loadLocale()` once before rendering. In a Hybrids app, the router's
-`connect` is the right place:
+Call `loadLocale()` (Pattern A) and/or `localize()` (Pattern B) once before
+first render. The router's `connect` is the right place in a Hybrids app:
 
 ```js
 // router/index.js
 import { loadLocale } from '#utils/i18n.js';
+import { localize } from 'hybrids';
 
-await loadLocale(navigator.language);
+// Pattern A — cascade for non-template strings
+loadLocale(navigator.language);
+
+// Pattern B — load a locale file for template auto-translation
+const lang = navigator.language.split('-')[0];
+if (lang !== 'en') {
+  fetch(`/locales/${lang}.json`)
+    .then(r => r.ok ? r.json() : {})
+    .then(msgs => localize(lang, msgs));
+}
 ```
 
-For SSR/static sites, call it in the page's `connect` handler instead.
+## Key Naming Convention (Pattern A)
 
-## Adding a Language
+`domain.concept` — dot-separated, lowercase, no spaces. Keys should read as
+documentation.
+
+```
+general.loading     general.error      general.save       general.cancel
+nav.home            nav.back           nav.signIn
+error.notFound      error.offline
+task.empty          task.addTask       task.deleteConfirm
+```
 
-1. Create `/locales/<lang>.json` with translated keys
-2. Only include keys that differ from English — missing keys fall back to defaults
-3. Optionally add `/locales/overrides.<lang>.json` for project-specific overrides
+Avoid `button1`, `label`, or anything that doesn't describe the content.
+
+## Extracting Keys (Pattern B)
+
+Hybrids ships a CLI extractor that scans source files and generates a
+translation-ready JSON file:
+
+```bash
+npx hybrids extract ./src ./locales/en.json
+npx hybrids extract --include-path ./src ./locales/en.json
+```
+
+Wire it as a script so translators always have a fresh key file:
 
 ```json
-// locales/es.json
-{
-  "general.loading": "Cargando…",
-  "general.error": "Algo salió mal.",
-  "nav.home": "Inicio"
-}
+{ "scripts": { "i18n:extract": "hybrids extract ./src ./locales/en.json" } }
 ```
 
-## Project Overrides
+The extractor is optional — use it when you're ready to hand off to a
+translator or add a second language.
 
-To customize English strings (e.g. brand voice) without touching `i18n.js`:
+## Adding a Language
 
-```json
-// locales/overrides.json
-{
-  "general.loading": "Analyzing your DNA…",
-  "error.offline": "Check your connection and try again."
-}
+1. Run `npm run i18n:extract` to get the current key list
+2. Translate into `locales/<lang>.json` — only include keys that differ
+3. Load it at init via `localize(lang, msgs)`
+4. For Pattern A overrides: add `locales/overrides.<lang>.json`
+
+## Spec Check
+
+`npm run spec code i18n` reports readiness without blocking the build:
+
+```
+✅ i18n readiness (12ms)
+   Pattern:   t() ×9, msg` ×3
+   Init:      yes · Overrides: yes · Languages: es, fr
+   Unwrapped: ~4 prose strings across 2 template files
 ```
 
+- **Pattern** — which i18n calls are present and how many files use them
+- **Init** — whether `loadLocale` or `localize` is called at startup
+- **Overrides** — whether `locales/overrides.json` exists
+- **Languages** — locale files found beyond English
+- **Unwrapped** — estimated prose strings in templates not yet wrapped in
+  `t()`/`msg\`` (heuristic, not exhaustive)
+
+The check always passes — it surfaces gaps, not failures.
+
 ## Rules
 
-- **Always use `t()`** for any user-visible string in components
-- **Never hardcode UI strings** in component render functions
-- **Keys fall back to themselves** — `t('missing')` returns `'missing'`, never crashes
+- **Always use `t()` or `msg\`** for any user-visible string in components
+- **Never hardcode UI strings** directly in render functions
+- **Plural forms belong in the dictionary**, not inline ternaries
 - **`loadLocale()` is safe to call multiple times** — last call wins
 - **Locale files are optional** — English-only apps just use `overrides.json`
+- **Keys fall back to themselves** — `t('missing')` returns `'missing'`, never throws