docs: remove Plan A, clean up Plan B and recommendation for single-plan focus

Copilot · brunoborges · Copilot · commit ce997984c4ac · 2026-02-20T21:50:35.000Z
Co-authored-by: brunoborges &lt;129743+brunoborges@users.noreply.github.com&gt;
diff --git a/specs/i18n/plan-a-locale-keyed-content.md b/specs/i18n/plan-a-locale-keyed-content.md
diff --git a/specs/i18n/plan-b-externalized-strings-full-translations.md b/specs/i18n/plan-b-externalized-strings-full-translations.md
@@ -290,7 +290,7 @@ The `<html>` tag becomes `<html lang="{{locale}}">`.
 
 ## Navigation — Language Selector
 
-Same user-facing design as Plan A (a `<select>` or dropdown in the nav bar).
+A `<select>` dropdown in the nav bar lets users switch locales.
 The list of locales is rendered at build time from `locales.properties`:
 
 ```html
@@ -300,7 +300,7 @@ The list of locales is rendered at build time from `locales.properties`:
 </select>
 ```
 
-`app.js` path-rewrite logic is identical to Plan A.
+`app.js` handles path-rewriting when the user picks a different locale.
 
 ---
 
@@ -381,17 +381,3 @@ Or, with a build-all mode added to the generator:
 | Untranslated-page fallback is explicit and user-visible | `translations/` directory adds a new top-level location to learn |
 | UI strings fall back to English automatically — no silent gaps | `app.js` must be updated to consume `window.i18n` instead of literals |
 | Scales cleanly to many locales | Build time grows linearly with locale count × pattern count |
-
----
-
-## Comparison with Plan A
-
-| | Plan A | Plan B |
-|---|---|---|
-| Translation file format | Overlay (partial JSON) | Full replacement JSON |
-| UI strings | `content/i18n/{locale}/ui.json` | `translations/strings/{locale}.json` |
-| Content location | `content/i18n/{locale}/…` | `translations/content/{locale}/…` |
-| English templates | Keep some literals | Extract all literals to `en.json` |
-| Fallback behaviour | Silent (English shown without notice) | Optional "not yet translated" banner |
-| Generator complexity | Medium — deep-merge algorithm needed | Higher — full resolution pipeline |
-| Translator experience | Must understand overlay semantics | Self-contained files, easier to translate |
diff --git a/specs/i18n/recommendation.md b/specs/i18n/recommendation.md
@@ -1,10 +1,10 @@
-# i18n Architecture Recommendation
+# i18n Architecture: AI-Driven Translation Workflow
 
-## TL;DR — **Plan B is recommended** for an AI-driven translation workflow.
+The i18n architecture is based on **externalized UI strings and full-replacement content files** (see `plan-b-externalized-strings-full-translations.md`).
 
 ---
 
-## Why Plan B wins when translations are AI-generated
+## Why this approach works well with AI-generated translations
 
 When a new slug is added and AI generates the translations automatically, the
 pipeline becomes:
@@ -13,23 +13,10 @@ pipeline becomes:
 New English slug  →  AI prompt  →  Translated JSON file  →  Commit to repo
 ```
 
-### Plan A (overlay) is awkward for AI
+Key properties that make this AI-friendly:
 
-- AI must know *which fields to include* in the overlay and which to omit
-  (`oldCode`, `modernCode`, `docs`, `related`, `prev`, `next` must all be
-  absent).
-- If the AI accidentally includes any of those fields the build silently uses
-  the AI value instead of the canonical English one — hard to detect.
-- Prompt engineering must explicitly say "only output these seven fields":
-  `title`, `summary`, `explanation`, `oldApproach`, `modernApproach`,
-  `whyModernWins`, `support.description`.
-- The overlay schema is a non-standard concept; every new contributor (human
-  or AI) needs to learn it.
-
-### Plan B (full replacement) is ideal for AI
-
-- AI receives the full English JSON and outputs a complete translated JSON.
-  No special field-filtering rules.
+- AI receives the full English JSON and outputs a complete translated JSON —
+  no special field-filtering rules in the prompt.
 - `oldCode` and `modernCode` are simply copied verbatim from the English file
   at build time, regardless of what the AI wrote — the generator always
   overwrites them. Zero prompt-engineering required to handle this case.
@@ -63,33 +50,16 @@ New English slug  →  AI prompt  →  Translated JSON file  →  Commit to repo
 5. **Build**: The generator picks it up on the next deployment and removes the
    "untranslated" banner automatically.
 
-> **Note**: Even though Plan B asks translators to provide `oldCode` and
-> `modernCode`, the build tooling always overwrites those fields with the
-> English values. So AI can safely copy them verbatim — no risk of translated
-> or hallucinated code leaking into the site.
-
----
-
-## Addressing Plan B's main risk
-
-Plan B's biggest concern is keeping translated content files in sync when the
-English original changes (e.g. a corrected explanation). The AI workflow
-mitigates this:
-
-- When a `content/<cat>/<slug>.json` file is **modified**, the same automation
-  can regenerate the translated file, or flag the diff for human review.
-- A simple CI check can compare the `jdkVersion`, `id`, and `slug` in the
-  English file with the translated file to catch stale translations.
+> **Note**: Even though the full JSON asks for `oldCode` and `modernCode`, the
+> build tooling always overwrites those fields with the English values. So AI
+> can safely copy them verbatim — no risk of translated or hallucinated code
+> leaking into the site.
 
 ---
 
-## Summary
+## Keeping translations in sync
 
-| Criterion | Plan A | Plan B |
-|---|---|---|
-| AI prompt complexity | Higher (must specify excluded fields) | Lower (translate whole file; build ignores code fields) |
-| Risk of AI error slipping through | Higher (wrong field inclusion is silent) | Lower (code fields are always overwritten) |
-| Validation of AI output | Schema + overlay semantics | Schema only |
-| Fallback visibility | Silent (English shown without notice) | Explicit banner |
-| Human translator experience | Must understand overlay contract | Self-contained file |
-| **Overall for AI workflow** | ⚠️ Workable but fragile | ✅ Recommended |
+When an English `content/<cat>/<slug>.json` file is **modified**, the same
+automation can regenerate the translated file, or flag the diff for human
+review. A simple CI check can compare `jdkVersion`, `id`, and `slug` in the
+English file with the translated file to catch stale translations.
