baldart 4.51.0 → 4.52.0

package/framework/agents/i18n-protocol.md

@@ -0,0 +1,120 @@
+# i18n Protocol
+
+## Purpose
+
+Define how agents/skills handle **user-facing text** when a project has opted
+into the internationalization layer. The contract is: **no user-facing string is
+ever hardcoded** — every label goes through the stack's translation function
+(`t('key')` / `<FormattedMessage>` / equivalent), the key is recorded in the
+**context registry** (`paths.i18n_registry`) with a *hyper-brief usage context*,
+and translation into the maintained languages is **context-aware** (the LLM sees
+*what the label is for and where it appears*, not just the source string). The
+2026 best-practice this encodes: "the void of context" is the #1 threat to
+translation quality — so context travels with every key.
+
+## Scope
+
+**In**: externalizing strings; the registry schema + naming convention; ICU usage;
+the BLOCKING anti-hardcoded cascade; the drift/coherence codes; who owns what.
+**Out**: installing the lint/extract tooling (that is `baldart configure` /
+`baldart doctor` / the toolchain `eslint-i18next` adapter — see
+`framework/docs/I18N-LAYER.md`); the actual translation mechanics (the
+`i18n-translator` agent + the `/i18n` skill).
+
+## Gating
+
+Conditional on `features.has_i18n: true` in `baldart.config.yml`. When the flag
+is `false`/missing, **every rule below is a no-op** — identical to pre-i18n
+behavior. Never block a task because the registry file or a lint command is
+missing; surface gaps through `baldart doctor`, not mid-task.
+
+## Authority model (avoid the sidecar drift)
+
+- **Code + native locale files** are authoritative for **WHICH keys exist** and
+  for **the translations**.
+- **The registry** (`paths.i18n_registry`, default `docs/i18n/registry.yml`) is
+  authoritative ONLY for the per-key **`context` + `domain`** (the context layer).
+- Reconciliation is **registry ⟷ `t()` calls / source-language file**: the
+  registry mirrors keys, it never invents them.
+
+## Registry schema (`paths.i18n_registry`, YAML)
+
+```yaml
+schema_version: 1
+keys:
+  checkout.summary.apply_coupon_cta:
+    source: "Apply coupon"          # in i18n.source_language
+    context: "Primary CTA in cart summary; applies the entered discount code"
+    domain: "checkout"
+    char_limit: 18                  # optional — UI constraint (verbose langs, e.g. DE)
+    icu: false                      # true when the string uses ICU plural/select
+    status: active                  # active | deprecated
+```
+
+Translations are NOT stored here — they live in the native locale files.
+
+## Naming convention (default; overridable via `.baldart/overlays/`)
+
+- **dot-notation** `namespace.domain.key` (e.g. `forms.buttons.login`, `errors.email_invalid`).
+- **Semantic, not literal**: `welcoming_message`, never the text itself nor a
+  generic `heading` — keys must survive copy changes.
+- **`global.*`** namespace for genuinely reused strings (`global.ok`, `global.cancel`);
+  do NOT force reuse when the context differs (a "god key" mistranslates).
+- **No concatenation** — use **ICU MessageFormat** for plurals/gender/select/number
+  in a single string. Concatenating `actor + " shared " + count + " files"` is
+  wrong in any inflected language.
+
+## BLOCKING anti-hardcoded cascade
+
+1. **Deterministic gate (primary)** — a BALDART-owned **standalone ESLint config**
+   (`eslint.i18n.config.mjs`, `eslint-plugin-i18next` `no-literal-string`) that
+   `baldart configure` / `baldart doctor` write and install. The gate command is
+   `i18n.lint_command` (default `npx eslint --config eslint.i18n.config.mjs .`),
+   resolved by the runners as: `i18n.lint_command` → the standalone config by
+   convention when the file exists → SKIP (never a silent pass). It is a dedicated
+   ESLint run **independent of the project's main lint** (so it works even on a
+   Biome-only toolchain) and **never touches the user's config**. The default rule
+   mode is `jsx-only`: it deterministically blocks **JSX text nodes AND user-facing
+   JSX attributes** (`title`/`placeholder`/`alt`/`aria-label`) — verified to FAIL on
+   a hardcoded label and PASS on `t()`. Runners: `qa-sentinel` (for `/new`, `/qa`),
+   the classic `/new` Phase-2 gate, the `new2` Phase-2 gate, and the `i18n-align`
+   routine (pre-commit). This is the HARD enforcement for JSX-rendered strings.
+2. **Semantic backstop (review)** — non-JSX imperative strings are OUTSIDE the
+   linter's deterministic reach, so `code-reviewer` flags them as **HIGH**,
+   **syntactically scoped**:
+   - *In scope (backstop's job)*: non-JSX user-facing strings — `toast(...)` /
+     imperative call args, thrown user-facing errors, strings built by
+     concatenation. (JSX text + attributes are already hard-blocked by the linter;
+     a linter pass is confirmation there, not a reason to re-flag.)
+   - *Excluded*: log lines, dev-facing errors, test files, enum/const keys,
+     `className`, internal identifiers, URLs, technical values.
+
+## Post-intervention coherence (drift codes)
+
+Whenever a change adds/edits `t()` keys, reconcile the registry in the SAME change:
+
+- `I18N_REGISTRY_DRIFT` — a key referenced in `t()` has no registry entry.
+- `I18N_KEY_ORPHANED` — a registry entry has no corresponding `t()` call.
+- `I18N_CONTEXT_MISSING` — a registry entry has an empty/placeholder `context`.
+
+Three enforcement layers (mirrors the design-system discipline): **per-task**
+(`coder` STEP 9 writes the stub entry) → **per-merge** (`doc-reviewer` curates
+context/orphans on new keys) → **weekly** (`i18n-align` routine audits + aligns
+target languages). The on-demand `/i18n audit` covers off-cadence checks.
+
+## Ownership (strict specialization)
+
+- **`coder`** — externalizes strings + writes the registry STUB (`source`+`context`+`domain`).
+  Does NOT translate.
+- **`doc-reviewer`** — curates the registry (context quality, dedup, orphan/missing).
+  Does NOT translate, does NOT write app code.
+- **`i18n-translator`** (`model: sonnet`, `effort: low`) — produces context-aware
+  translations into the native locale files. Does NOT touch the registry or code;
+  flags anomalies (`needs-attention`) instead of guessing.
+
+## Consumers
+
+`coder` (STEP 9), `code-reviewer` (anti-hardcoded backstop), `doc-reviewer`
+(registry curation), the `/i18n` skill, the `/i18n-adopt` migration skill, the
+`i18n-align` routine, `/prd` + `/new` (declare/inherit the constraint). All gate
+on `features.has_i18n`.

package/framework/agents/index.md

@@ -25,6 +25,7 @@ Route agents to the right module with minimal reading.
 - If touching workflow/process/commits/backlog -> read `agents/workflows.md`.
 - If CREATING or MUTATING a backlog card (any prefix — `FEAT`/`CHORE`/`BUG`/`DOC`/`PERF`/`UI`), or consuming one type-blind (`/new`, `/new2`) -> read `agents/card-schema.md` (the universal, profile-aware baseline) before writing/validating fields.
 - If running MECHANICAL GATES (lint, format, type-check, test, build, audit) and `features.has_toolchain: true` -> read `agents/toolchain-protocol.md` and run the command from `toolchain.commands.<gate>` verbatim, falling back to the project-standard default when a key is unset. A configured command that FAILS is a real gate failure (do not fall back).
+- If writing/reviewing ANY user-facing text (labels, copy, messages) and `features.has_i18n: true` -> read `agents/i18n-protocol.md`: never hardcode strings, route every label through `t()` with a key recorded in `paths.i18n_registry` (`context`+`domain`), use ICU (no concatenation). The anti-hardcoded linter is the BLOCKING gate; translation is the `i18n-translator` agent / `/i18n` skill. When the flag is `false`, no-op.
 - If touching testing or QA issues -> read `agents/testing.md` (also documents the scope-aware,
   profile-driven test-selection strategy consumed by `qa-sentinel`).
 - If touching GitHub issues or issue workflow -> read `agents/github-issue-subagent.md`.
@@ -67,6 +68,7 @@ When adding or updating agents, update REGISTRY.md — not this file.
 - `agents/code-search-protocol.md` — Retrieval hierarchy for code search: LSP → Grep → Git (since v3.10.0, gated on `features.has_lsp_layer`)
 - `agents/code-graph-protocol.md` — Structural/relational retrieval via the Graphify code knowledge graph (since v4.21.0, gated on `features.has_code_graph`)
 - `agents/toolchain-protocol.md` — Mechanical-gate command resolution (lint/format/typecheck/test/build/audit) from `toolchain.commands.*` with silent project-standard fallback (since v4.41.0, gated on `features.has_toolchain`)
+- `agents/i18n-protocol.md` — Internationalization discipline: no hardcoded user-facing strings, context registry (`paths.i18n_registry`) + ICU + context-aware translation; BLOCKING anti-hardcoded lint gate (since v4.52.0, gated on `features.has_i18n`)
 - `agents/design-system-protocol.md` — Registry-first discipline for UI work: BLOCKING cascade on `INDEX.md` + `tokens-reference.md` + `components/<Name>.md` (since v3.11.0, gated on `features.has_design_system`)
 - `agents/card-schema.md` — Atomic Card Baseline Schema: the universal, profile-aware (epic/child/standalone) field contract every backlog card satisfies, plus the consumer HALT/BACK-FILL/WARN contract (since v4.35.0)
 

package/framework/docs/I18N-LAYER.md

@@ -0,0 +1,89 @@
+# i18n Layer — Operator Guide
+
+> Since v4.52.0. Opt-in, gated on `features.has_i18n`. The **runtime protocol**
+> (how agents handle user-facing text) lives in
+> [`framework/agents/i18n-protocol.md`](../agents/i18n-protocol.md); this document
+> covers the *plumbing* — config, lifecycle, the moving parts, fallback.
+
+## 1. Why this exists
+
+Multi-language products fail on translation quality when the translator (human or
+LLM) sees only the source string. The 2026 best-practice consensus calls this
+"the void of context" — the #1 quality threat. BALDART's i18n layer makes
+internationalization a first-class discipline: **no user-facing string is ever
+hardcoded**, and every key carries a **hyper-brief context** so translation is
+context-aware, not blind.
+
+## 2. What BALDART adds vs what the stack already ships
+
+BALDART does NOT reimplement i18n. It **wraps** the consumer's existing framework
+(next-intl / i18next / react-intl / lingui / vue-i18n) and best-in-class OSS:
+
+- **Anti-hardcoded gate** — `eslint-plugin-i18next` (`no-literal-string`; the most
+  adopted, ~550k weekly downloads) or `i18nGuard` (multi-framework, SARIF).
+- **Key extraction** — `i18next-cli` / `lingui extract` / `formatjs extract`
+  (detection-only; BALDART never installs the extractor).
+- **Bulk translation (optional)** — `lingo.dev` / `languine` the `i18n-translator`
+  agent may delegate volume to, then review.
+
+BALDART's proprietary value is the **context registry** (`paths.i18n_registry`) and
+the agentic orchestration around it.
+
+## 3. The moving parts
+
+| Part | Where | Role |
+|---|---|---|
+| Feature flag + block | `baldart.config.yml` | `features.has_i18n` + `paths.i18n_registry` + the `i18n:` block (`framework`, `source_language`, `target_languages`, `locales_root`, `extract_command`, `bulk_translator`, `lint_command`) |
+| Context registry | `${paths.i18n_registry}` (default `docs/i18n/registry.yml`) | stack-agnostic YAML SSOT for per-key `source`+`context`+`domain` (NOT the translations) |
+| Protocol module | `framework/agents/i18n-protocol.md` | authority model, naming/ICU rules, drift codes, ownership |
+| Translator agent | `framework/.claude/agents/i18n-translator.md` | `model: sonnet`, `effort: low` — context-aware translation into native locale files; flag-not-guess |
+| On-demand skill | `framework/.claude/skills/i18n/SKILL.md` | `/i18n audit` + `/i18n translate` |
+| Adoption skill | `framework/.claude/skills/i18n-adopt/SKILL.md` | `/i18n-adopt` — one-shot migration of an existing codebase (find → replace → register → translate → verify); dedicated branch, idempotent, never auto-merges |
+| Weekly routine | `framework/routines/i18n-align.routine.yml` | translates target languages, lints, commits direct to trunk |
+| Anti-hardcoded gate | BALDART-owned standalone `eslint.i18n.config.mjs` (run via `i18n.lint_command`) + `src/utils/i18n-gate.js` | BLOCKING — literal user-facing strings fail; works on Biome projects; never touches the user's lint config |
+| Consumers | `coder` (STEP 9), `code-reviewer` (backstop), `doc-reviewer` (registry curation), `/prd` (HARD RULE 20), `/new` (briefing) | all gate on `features.has_i18n` |
+
+## 4. Install lifecycle
+
+```
+features.has_i18n: true
+        │
+        ├─ baldart configure (INTERACTIVE) ── detect framework (package.json)
+        │      → prompt source / target languages / locales_root
+        │      → populate i18n.extract_command default
+        │      → set i18n.lint_command (standalone gate)
+        │      → offer gate setup: devDeps + write eslint.i18n.config.mjs
+        │      → hint: npx baldart routines install i18n-align
+        │
+        ├─ baldart configure --yes / CI ──→ writes the flag + block ONLY; doctor backfills
+        │
+        ├─ baldart doctor ─────────────────→ i18n-gate-setup (deps/config missing)
+        │                                     i18n-registry-missing (registry absent)
+        │
+        └─ /i18n (on demand) ──────────────→ audit + translate
+```
+
+## 5. Authority + drift (3 tiers)
+
+Code/native files own *which keys exist* + the translations; the registry owns
+*context/domain*. Drift is contained continuously:
+
+1. **Per-task** — `coder` STEP 9 writes the registry stub at key creation.
+2. **Per-merge** — `doc-reviewer` curates context/orphans on new keys in `/new`.
+3. **Weekly** — `i18n-align` translates target languages and commits to trunk.
+
+On-demand `/i18n audit` covers off-cadence checks. Drift codes:
+`I18N_REGISTRY_DRIFT`, `I18N_KEY_ORPHANED`, `I18N_CONTEXT_MISSING`.
+
+## 6. Invariants
+
+- **Gate on `features.has_i18n`** — every rule is a no-op when false. Never assume.
+- **Silent fallback** — never block a task because the registry/lint is missing;
+  surface gaps via `baldart doctor`.
+- **Translations live in native files** — the registry never stores them.
+- **Strict specialization** — coder populates, doc-reviewer curates, i18n-translator
+  translates; none crosses lanes.
+- **Schema-change propagation** applies to `features.has_i18n` + `paths.i18n_registry`
+  + the `i18n.*` block (template + configure + update detector + doctor + CHANGELOG).
+- **No PR for the routine** — translation files are low-risk; direct commit to the
+  trunk (`git.trunk_branch`).

package/framework/routines/i18n-align.routine.yml

@@ -0,0 +1,61 @@
+name: i18n-align
+description: Weekly i18n alignment — translates labels missing/stale in the maintained target languages, using the per-key registry context. Direct commit (no PR).
+since_version: 4.52.0
+
+schedule:
+  cron: "0 4 * * 1"            # Monday 04:00 UTC
+  timezone: UTC
+  jitter_minutes: 0
+  cadence_label: weekly
+
+agent: i18n-translator
+
+prompt: |
+  Run the weekly i18n alignment (only when `features.has_i18n: true` in
+  `baldart.config.yml` AND `i18n.target_languages` is non-empty — exit cleanly
+  otherwise). Read `framework/agents/i18n-protocol.md` first. You are the
+  context-aware translator; you keep the maintained target languages in sync
+  with the source language. You do NOT curate the registry (that is
+  doc-reviewer's nightly job) and you do NOT touch application code.
+
+  1. **Enumerate keys**: run `i18n.extract_command` if set (e.g.
+     `npx i18next-cli extract`); otherwise `rg` the codebase for `t('…')` calls.
+     Read the source-language locale file under `i18n.locales_root` and the
+     context registry at `${paths.i18n_registry}`.
+  2. **Find gaps**: for each language in `i18n.target_languages`, list keys that
+     are present in the source language but **missing or stale** (source changed
+     since last translation) in that language's native locale file.
+  3. **Translate with context**: for each gap, translate using the registry
+     `context` + `domain` (+ `char_limit`, glossary if present). Preserve ICU
+     constructs and placeholders EXACTLY. On any anomaly (empty/ambiguous
+     context, impossible char_limit, unmappable ICU, technical source) DO NOT
+     guess — leave the label untranslated and record a `needs-attention` entry.
+  4. **Write + verify**: write the translations into the native locale files,
+     then run the anti-hardcoded / validate gate — `i18n.lint_command` if set,
+     else the standalone `eslint.i18n.config.mjs` by convention
+     (`npx eslint --config eslint.i18n.config.mjs .`) — so no malformed
+     ICU/placeholder or hardcoded string is committed.
+  5. **Report**: write `docs/reports/{{YYYYMMDD}}-i18n-align.md` listing keys
+     translated per language and all `needs-attention` records.
+
+  Commit directly to the current branch (the integration trunk, `${git.trunk_branch}`)
+  — these are translation files only, blast radius is minimal, NO pull request.
+  The `needs-attention` records go into the commit message and the report.
+
+output:
+  path: docs/reports/{{YYYYMMDD}}-i18n-align.md
+  commit:
+    enabled: true
+    prefix: "[I18N-ALIGN]"
+    branch: ${git.trunk_branch}
+
+required_artifacts:
+  - ${paths.i18n_registry}
+  - .claude/agents/i18n-translator.md
+
+optional: true   # routine is silently skipped when artifacts missing / feature off
+
+backend_hints:
+  - claude-code-cloud
+  - github-actions
+  - cron

package/framework/routines/index.yml

@@ -78,3 +78,14 @@ routines:
       Weekly full SSOT sweep — runs the project's full audit suite
       (frontmatter, errors, perms, env, imports, etc.) and writes a
       consolidated drift report.
+
+  - name: i18n-align
+    file: i18n-align.routine.yml
+    cadence: weekly
+    since_version: 4.52.0
+    summary: |
+      Weekly i18n alignment — translates labels missing/stale in the
+      maintained target languages (i18n.target_languages) using the per-key
+      registry context, runs lint, and commits directly to the trunk (no PR).
+      Optional (only runs when features.has_i18n is true and target languages
+      are configured).

package/framework/templates/baldart.config.template.yml

@@ -43,6 +43,12 @@ paths:
   references_dir: ""          # e.g. docs/references
   wiki_dir: ""                # e.g. docs/wiki   (LLM-wiki overlay)
 
+  # i18n context registry (since v4.52.0). Stack-agnostic YAML SSOT for the
+  # per-key TRANSLATION CONTEXT (source + hyper-brief usage note + domain) — NOT
+  # the translations themselves (those live in the stack's native locale files).
+  # Set features.has_i18n: true to enable. Default convention "docs/i18n/registry.yml".
+  i18n_registry: ""           # e.g. docs/i18n/registry.yml
+
   # Test infrastructure.
   e2e_tests_dir: ""           # e.g. tests/e2e
 
@@ -233,6 +239,18 @@ features:
   # and framework/docs/TOOLCHAIN-LAYER.md.
   has_toolchain: false
 
+  # Internationalization layer (since v4.52.0). When true, all user-facing
+  # strings MUST be externalized through a translation function (never
+  # hardcoded), keys are recorded in paths.i18n_registry with a hyper-brief
+  # CONTEXT note so LLM translation is context-aware (not blind), and the
+  # anti-hardcoded gate (eslint-plugin-i18next via the toolchain lint command)
+  # blocks literal strings. The `/i18n` skill audits + translates on demand; the
+  # weekly `i18n-align` routine keeps target languages aligned. coder STEP 9
+  # populates the registry; doc-reviewer curates it. Falls back SILENTLY to a
+  # no-op everywhere when false. See framework/agents/i18n-protocol.md and
+  # framework/docs/I18N-LAYER.md.
+  has_i18n: false
+
 # ─── E2E REVIEW ──────────────────────────────────────────────────────────
 # Tuning for the /e2e-review skill (only consulted when has_e2e_review: true).
 e2e_review:
@@ -321,6 +339,47 @@ toolchain:
   # restores any missing default config. Disable on CI if too noisy.
   auto_verify: true
 
+# ─── I18N ──────────────────────────────────────────────────────────────────
+# State of the internationalization layer. Populated by `baldart configure` /
+# the `/i18n` skill. Only meaningful when `features.has_i18n: true`. The
+# translations themselves live in the stack's NATIVE locale files; this block
+# only describes the stack + the maintained languages + the on-demand tooling.
+i18n:
+  # Canonical i18n framework / library in use. Autodetected from package.json by
+  # `baldart configure`. Recognized: "next-intl" | "i18next" | "react-intl" |
+  # "lingui" | "vue-i18n" | "custom" | "".
+  framework: ""
+
+  # Source/default language (BCP-47 tag, e.g. "en", "en-US"). The locale the
+  # source strings are authored in — the registry `source` field is in this lang.
+  source_language: ""
+
+  # Target languages BALDART MAINTAINS (BCP-47 tags). The weekly `i18n-align`
+  # routine and the `/i18n` skill translate missing/stale keys into each of
+  # these. Empty = no automated translation (audit still works).
+  target_languages: []
+
+  # Locale files root (e.g. src/locales, public/locales, locales). Autodetected.
+  locales_root: ""
+
+  # Key-extraction command (detection-only — BALDART does NOT install it). Run by
+  # `/i18n` + the routine to enumerate t() keys for registry↔code reconciliation.
+  # Empty → the skill falls back to an rg-based scan. e.g. "npx i18next-cli extract".
+  extract_command: ""
+
+  # Optional bulk machine-translation backend the i18n-translator agent may
+  # delegate VOLUME to (then reviews its output). "" | "lingo.dev" | "languine".
+  bulk_translator: ""
+
+  # Deterministic anti-hardcoded gate command. `baldart configure` / `baldart
+  # doctor` set this to a STANDALONE ESLint run BALDART owns
+  # (`npx eslint --config eslint.i18n.config.mjs .`) — it works on Biome projects
+  # too (a dedicated ESLint invocation just for this gate, never touching your main
+  # lint config). The gate runners (qa-sentinel, /new2, the i18n-align routine) run
+  # it verbatim; a non-zero exit FAILS the gate. Empty + no config file present →
+  # the gate reports SKIP (never a silent pass).
+  lint_command: ""
+
 # ─── GIT ─────────────────────────────────────────────────────────────────
 # Controls how worktree-manager (`/mw`) integrates a worktree's feature
 # branch back into the integration trunk.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.51.0",
+  "version": "4.52.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/configure.js

@@ -8,6 +8,7 @@ const lspAdapters = require('../utils/lsp-adapters');
 const GraphifyInstaller = require('../utils/graphify-installer');
 const ToolchainInstaller = require('../utils/toolchain-installer');
 const toolchainAdapters = require('../utils/toolchain-adapters');
+const I18nGate = require('../utils/i18n-gate');
 
 const CONFIG_FILE = 'baldart.config.yml';
 // The subtree pull copies the entire BALDART repo (which itself has a
@@ -168,6 +169,25 @@ function detect(cwd = process.cwd()) {
   const hasDep = (name) => Object.keys(deps).some((d) => d === name || d.startsWith(`${name}/`));
   const hasAnyDep = (...names) => names.some(hasDep);
 
+  // ---- i18n layer autodetection (since v4.52.0) --------------------------
+  // Detection-only: BALDART does not install the i18n framework, it reads which
+  // one the consumer already uses to populate the `i18n:` config block.
+  const detectI18nFramework = () => {
+    if (hasDep('next-intl')) return 'next-intl';
+    if (hasDep('react-intl') || hasDep('@formatjs/intl')) return 'react-intl';
+    if (hasDep('@lingui/core') || hasDep('@lingui/react')) return 'lingui';
+    if (hasDep('vue-i18n')) return 'vue-i18n';
+    if (hasDep('i18next')) return 'i18next';
+    return '';
+  };
+  const detectLocalesRoot = () => {
+    for (const cand of ['src/locales', 'public/locales', 'locales', 'src/i18n/locales', 'i18n/locales', 'app/locales']) {
+      if (exists(cand)) return cand;
+    }
+    return '';
+  };
+  const detectedI18nFramework = detectI18nFramework();
+
   // ---- Monorepo awareness ------------------------------------------------
   const monorepoMarkers = ['pnpm-workspace.yaml', 'lerna.json', 'nx.json', 'turbo.json', 'rush.json'];
   const isMonorepo = monorepoMarkers.some(exists) || Array.isArray(pkg?.workspaces) ||
@@ -480,6 +500,9 @@ function detect(cwd = process.cwd()) {
       // Drives the prompt default; install side effects only run interactively.
       has_toolchain: toolchainAdapters.detectAll(cwd).length > 0
         && toolchainAdapters.detectIncumbents(cwd).length === 0,
+      // i18n recommended when the project already uses a known i18n framework.
+      // Drives the prompt default; the config block is populated interactively.
+      has_i18n: Boolean(detectedI18nFramework),
     },
     tools: {
       enabled: toolAdapters.defaultEnabled(cwd)
@@ -650,6 +673,7 @@ async function interactivePrompts(merged, detected) {
     ['has_code_graph', 'Enable Graphify code-knowledge-graph layer? (structural queries + wiki feed; recommended for large codebases)'],
     ['has_toolchain', 'Enable curated dev toolchain? (Biome format+lint+import; agents run it in the quality gates — recommended for JS/TS)'],
     ['has_e2e_review', 'Enable BLOCKING end-to-end review (Phase 2.6 of /new invokes /e2e-review — functional + visual fidelity gate)?'],
+    ['has_i18n', 'Enable i18n layer? (no hardcoded labels + context registry + context-aware translation — recommended for multi-language products)'],
   ]) {
     const [key, question] = flag;
     const currentVal = merged.features[key];
@@ -1004,6 +1028,85 @@ async function interactivePrompts(merged, detected) {
     merged.toolchain.installed_tools = [];
   }
 
+  // ---- i18n layer (since v4.52.0) ---------------------------------------
+  // Detection-first, install-light. We detect the i18n framework, ask which
+  // languages to maintain, populate the on-demand tooling commands, and OFFER
+  // (interactive only) to install the anti-hardcoded lint plugin + the weekly
+  // i18n-align routine. Translations + key extraction are NOT installed by
+  // BALDART — the i18n framework is the consumer's choice; we wrap it.
+  merged.i18n = merged.i18n || {
+    framework: '', source_language: '', target_languages: [],
+    locales_root: '', extract_command: '', bulk_translator: '', lint_command: '',
+  };
+  if (merged.features.has_i18n === true) {
+    UI.section('i18n layer (context registry + context-aware translation)');
+    merged.i18n.framework = await promptForKey(
+      'i18n framework (next-intl | i18next | react-intl | lingui | vue-i18n | custom)',
+      merged.i18n.framework || detectedI18nFramework || ''
+    );
+    merged.i18n.source_language = await promptForKey(
+      'Source language (BCP-47 tag, e.g. en, en-US)',
+      merged.i18n.source_language || (merged.identity && merged.identity.language) || 'en'
+    );
+    const targetDefault = (merged.i18n.target_languages || []).join(', ');
+    const targetInput = await promptForKey(
+      'Target languages to MAINTAIN (comma-separated BCP-47, e.g. it, es, fr — empty = audit only)',
+      targetDefault
+    );
+    merged.i18n.target_languages = targetInput
+      .split(',').map((l) => l.trim()).filter(Boolean);
+    merged.i18n.locales_root = await promptForKey(
+      'Native locale files root (e.g. src/locales, public/locales)',
+      merged.i18n.locales_root || detectLocalesRoot() || ''
+    );
+    // Sensible default for the on-demand key-extraction command (detection-only).
+    if (!merged.i18n.extract_command) {
+      const fw = merged.i18n.framework;
+      merged.i18n.extract_command =
+        fw === 'i18next' ? 'npx i18next-cli extract'
+          : fw === 'lingui' ? 'npx lingui extract'
+            : fw === 'react-intl' ? 'npx formatjs extract' : '';
+    }
+    merged.i18n.bulk_translator = await promptForKey(
+      'Optional bulk machine-translation backend the i18n-translator may delegate to (empty | lingo.dev | languine)',
+      merged.i18n.bulk_translator || ''
+    );
+    // Default the i18n_registry path when unset.
+    if (!merged.paths.i18n_registry) {
+      merged.paths.i18n_registry = await promptForKey(
+        'i18n context registry path (key+context SSOT)', 'docs/i18n/registry.yml'
+      );
+    }
+    // Anti-hardcoded gate: a BALDART-owned STANDALONE ESLint config (works on
+    // Biome projects too — a dedicated ESLint run just for this gate, never
+    // touching the user's lint config). i18n.lint_command points at it so the
+    // gate runners (qa-sentinel, new2, the routine) execute it deterministically.
+    const gateCwd = process.cwd();
+    const gateDeps = I18nGate.depsFor(gateCwd);
+    const gateConfigFile = I18nGate.configFilename(gateCwd);
+    merged.i18n.lint_command = I18nGate.commandForCwd(gateCwd);
+    const wantGate = await UI.confirm(
+      `Install the deterministic anti-hardcoded gate now (devDeps ${gateDeps.join(', ')} + a standalone ${gateConfigFile})?`, true
+    );
+    if (wantGate) {
+      const res = I18nGate.setup(gateCwd);
+      if (res.error) {
+        UI.warning(`i18n gate setup incomplete: ${res.error}. Run \`baldart doctor\` to retry.`);
+      } else {
+        if (res.installed) UI.success(`Installed ${gateDeps.join(', ')}.`);
+        if (res.config && res.config.status === 'written') UI.success(`Wrote ${res.config.file} (${res.era} ESLint config — standalone, edit freely, never overwritten).`);
+        else if (res.config && res.config.status === 'exists') UI.info(`Kept existing ${res.config.file}.`);
+        UI.success(`Anti-hardcoded gate wired: \`${merged.i18n.lint_command}\` runs in the quality gates.`);
+      }
+    } else {
+      UI.info('Skipping. The gate stays unwired (qa-sentinel reports i18n-lint SKIP) until you run `baldart doctor`.');
+    }
+    UI.info('To enable weekly auto-alignment of target languages, run: `npx baldart routines install i18n-align`.');
+  } else {
+    merged.i18n.framework = '';
+    merged.i18n.target_languages = [];
+  }
+
   UI.section('Stack (autodetected from package.json — confirm or override)');
   const charting = merged.stack.charting;
   const chartingCanonical = await promptForKey(

package/src/commands/doctor.js

@@ -34,6 +34,7 @@ const GitHooks = require('../utils/githooks');
 const LspInstaller = require('../utils/lsp-installer');
 const GraphifyInstaller = require('../utils/graphify-installer');
 const ToolchainInstaller = require('../utils/toolchain-installer');
+const I18nGate = require('../utils/i18n-gate');
 const ToolCurrency = require('../utils/tool-currency');
 const CodexOrphans = require('../utils/codex-orphans');
 const UpdateNotifier = require('../utils/update-notifier');
@@ -425,6 +426,29 @@ async function detectState(cwd, opts = {}) {
       }
     } catch (_) { /* never block doctor on toolchain probe */ }
 
+    // ---- i18n layer (since v4.52.0) ------------------------------------
+    // Detection-only backfill: the i18n framework is the consumer's, so doctor
+    // never installs it — it flags a missing context registry and a missing
+    // anti-hardcoded lint plugin (the only thing BALDART offers to install).
+    state.i18nEnabled = false;
+    state.i18nRegistryMissing = false;
+    state.i18nGateMissing = false;
+    try {
+      if (config && !config.__malformed && config.features && config.features.has_i18n === true) {
+        state.i18nEnabled = true;
+        const regPath = (config.paths && config.paths.i18n_registry) || '';
+        if (regPath && !fs.existsSync(path.join(cwd, regPath))) {
+          state.i18nRegistryMissing = true;
+        }
+        // Deterministic anti-hardcoded gate present? (standalone config + deps).
+        // Only meaningful for a JS/TS project — skip the gate check otherwise.
+        if (I18nGate.hasPackageJson(cwd)
+          && (!I18nGate.isConfigPresent(cwd) || !I18nGate.depsInstalled(cwd))) {
+          state.i18nGateMissing = true;
+        }
+      }
+    } catch (_) { /* never block doctor on i18n probe */ }
+
     // ---- External-tool version currency (since v4.38.0) ----------------
     // BALDART pins none of the external tools it installs (graphifyy via pipx,
     // language servers via npm/system) — pipx/npm never auto-upgrade, so a
@@ -885,6 +909,40 @@ function planActions(state) {
     });
   }
 
+  // ---- i18n layer backfill (since v4.52.0) ----------------------------
+  // Detection-only: BALDART never installs the consumer's i18n framework. It
+  // offers to install the anti-hardcoded lint plugin and flags a missing
+  // context registry (which `/i18n` or the consumer scaffolds).
+  if (state.i18nEnabled && state.i18nGateMissing) {
+    const gateDeps = I18nGate.depsFor(state.cwd);
+    const gateFile = I18nGate.configFilename(state.cwd);
+    actions.push({
+      key: 'i18n-gate-setup',
+      label: `Set up the anti-hardcoded gate (${gateDeps.join(', ')} + ${gateFile})`,
+      why: `features.has_i18n is true but the deterministic anti-hardcoded gate is not fully set up (missing devDeps or ${gateFile}), so hardcoded user-facing strings are not blocked. Installs the gate dependencies and writes a STANDALONE ESLint config (era-matched to your ESLint; works on Biome projects; never touches your main lint config).`,
+      autoOk: false, // installs devDependencies; confirm
+      run: async () => {
+        const res = I18nGate.setup(state.cwd);
+        if (res.error) { UI.warning(`Gate setup incomplete: ${res.error}.`); return; }
+        if (res.installed) UI.success(`Installed ${gateDeps.join(', ')}.`);
+        if (res.config && res.config.status === 'written') UI.success(`Wrote ${res.config.file} (${res.era} ESLint config).`);
+        UI.success(`Anti-hardcoded gate ready: \`${I18nGate.commandForCwd(state.cwd)}\`.`);
+        UI.info('If i18n.lint_command is unset in baldart.config.yml, the gate runs by convention via the config file; `baldart configure` records it explicitly.');
+      },
+    });
+  }
+  if (state.i18nEnabled && state.i18nRegistryMissing) {
+    actions.push({
+      key: 'i18n-registry-missing',
+      label: 'i18n context registry not found — scaffold it with /i18n',
+      why: `features.has_i18n is true but the context registry at paths.i18n_registry does not exist yet. It is the SSOT for per-key translation context. Run the /i18n skill (or create the YAML) to start populating it; coder STEP 9 fills it as keys are added.`,
+      autoOk: false, // informational — no safe auto-create without project context
+      run: async () => {
+        UI.info('Run `/i18n` in your editor to audit + scaffold the registry, or create the YAML at the configured path. See framework/docs/I18N-LAYER.md.');
+      },
+    });
+  }
+
   // External-tool version currency (since v4.38.0). One non-blocking upgrade
   // action per managed tool confirmed behind upstream — the tool-dependency
   // analogue of the `baldart` CLI's own UpdateNotifier. `unknown`/`current`

package/src/commands/update.js

@@ -1312,6 +1312,11 @@ async function update(options = {}, unknownArgs = []) {
             const missingToolchainCmds = Object.keys((tpl.toolchain && tpl.toolchain.commands) || {})
               .filter((k) => !(k in ((cur2.toolchain && cur2.toolchain.commands) || {})))
               .map((k) => `toolchain.commands.${k}`);
+            // `i18n:` (since v4.52.0) — same nested-block contract as `graph:` /
+            // `toolchain:`. Diff its own scalar keys so a new option surfaces.
+            const missingI18n = Object.keys(tpl.i18n || {})
+              .filter((k) => !(k in (cur2.i18n || {})))
+              .map((k) => `i18n.${k}`);
             const allMissing = [
               ...missingPaths,
               ...missingFeatures,
@@ -1320,6 +1325,7 @@ async function update(options = {}, unknownArgs = []) {
               ...missingGraph.map((k) => `graph.${k}`),
               ...missingToolchain,
               ...missingToolchainCmds,
+              ...missingI18n,
             ];
             if (allMissing.length) {
               UI.newline();