docs: rewrite Plan B as unified Internationalization Specification

Co-authored-by: brunoborges <129743+brunoborges@users.noreply.github.com>

Author: Copilot

…xternalized-strings-full-translations.md specs/i18n/i18n-spec.mdspecs/i18n/plan-b-externalized-strings-full-translations.md renamed to specs/i18n/i18n-spec.md specs/i18n/plan-b-externalized-strings-full-translations.md renamed to specs/i18n/i18n-spec.md

@@ -1,36 +1,37 @@
-# Plan B — Externalized UI Strings + Full Translation Files
+# Internationalization Specification
 
 ## Overview
 
-Separate concerns into two distinct layers:
+This document specifies how java.evolved supports multiple languages.
+Internationalization is implemented via two distinct layers:
 
 1. **UI strings layer** — every piece of hard-coded copy in the templates
-   (labels, button text, nav, footer, etc.) is moved into a per-locale
-   `strings/{locale}.json` file and injected at build time.
+   (labels, button text, nav, footer, etc.) is extracted into a per-locale
+   `translations/strings/{locale}.json` file and injected at build time.
 
-2. **Content translation layer** — translated pattern JSON files are
-   complete, stand-alone replacements (not overlays) stored next to the
-   English originals. The generator falls back to the English file for any
-   pattern that has not yet been translated.
+2. **Content translation layer** — translated pattern JSON files are complete,
+   stand-alone replacements stored under `translations/content/{locale}/`.
+   The generator falls back to the English file for any pattern that has not yet
+   been translated.
 
-This approach treats English as just another locale and unifies the build
-pipeline so all locales are first-class citizens.
+English is a first-class locale. All locales — including English — go through
+the same build pipeline.
 
 ---
 
 ## Directory Layout
 
 ```
-content/                              # Unchanged English content
+content/                              # English content (source of truth)
   language/
     type-inference-with-var.json
   collections/
     ...
 
-translations/                         # New top-level directory
+translations/                         # All i18n artefacts
   strings/
     en.json                           # English UI strings (extracted from templates)
-    pt-BR.json
+    pt-BR.json                        # Partial — missing keys fall back to en.json
     ja.json
   content/
     pt-BR/
@@ -42,17 +43,17 @@ translations/                         # New top-level directory
       language/
         ...
 
-templates/                            # Templates gain {{…}} tokens for every
-  slug-template.html                  # hard-coded UI string (no literal English left)
+templates/                            # Templates use {{…}} tokens for every UI string
+  slug-template.html
   index.html
   ...
 
 html-generators/
   locales.properties                  # Ordered list of supported locales + display names
-  generate.java / generate.py         # Rewritten to iterate all locales
+  generate.java / generate.py         # Extended to iterate all locales
 
 site/                                 # Generated output
-  index.html                          # English home (locale = en, path = /)
+  index.html                          # English home (path = /)
   language/
     type-inference-with-var.html
   data/
@@ -69,9 +70,26 @@ site/                                 # Generated output
 
 ---
 
-## `strings/{locale}.json` Schema
+## `locales.properties` — Supported Locales Registry
+
+```properties
+# html-generators/locales.properties
+# format: locale=Display name  (first entry is the default/primary locale)
+en=English
+pt-BR=Português (Brasil)
+ja=日本語
+```
+
+The generator reads this file to know which locales to build and what label
+to show in the language selector.
+
+---
+
+## `translations/strings/{locale}.json` Schema
 
-Every user-visible string in the templates is assigned a dot-separated key:
+Every user-visible string in the templates is assigned a dot-separated key.
+The English file is the complete reference; locale files are partial and only
+need to include keys that differ from English.
 
 ```json
 // translations/strings/en.json
@@ -130,8 +148,7 @@ Every user-visible string in the templates is assigned a dot-separated key:
 ```
 
 ```json
-// translations/strings/pt-BR.json
-// Strings files support partial translation: missing keys fall back to en.json at build time.
+// translations/strings/pt-BR.json  (partial — only translated keys required)
 {
   "site": {
     "tagline": "O Java evoluiu. Seu código também pode.",
@@ -151,22 +168,15 @@ Every user-visible string in the templates is assigned a dot-separated key:
 }
 ```
 
-Missing keys in a locale's strings file fall back to the `en.json` value —
-strings files are partial by design and only require the keys that need
-translation.
-
-> **Note**: This partial-fallback behaviour applies to `strings/{locale}.json`
-> **only**. Translated *content* files (see next section) are always complete
-> replacements, not overlays.
+Missing keys fall back to `en.json` at build time.
 
 ---
 
-## Full-Replacement Content Files
+## Content Translation Files
 
-Unlike Plan A's overlay approach, translated content files are **complete**
-copies of the pattern JSON with every field in the target language. This
-avoids partial-merge edge cases and lets translators work with a self-contained
-file.
+Translated content files are **complete** copies of the English pattern JSON
+with translatable fields rendered in the target language. This avoids
+partial-merge edge cases and makes each file self-contained.
 
 ```json
 // translations/content/pt-BR/language/type-inference-with-var.json
@@ -181,8 +191,8 @@ file.
   "modernLabel": "Java 10+",
   "oldApproach": "Tipos explícitos",
   "modernApproach": "Palavra-chave var",
-  "oldCode": "String nome = \"Alice\";\nString saudacao = \"Olá, \" + nome + \"!\";",
-  "modernCode": "var nome = \"Alice\";\nvar saudacao = \"Olá, %s!\".formatted(nome);",
+  "oldCode": "...",
+  "modernCode": "...",
   "summary": "Use var para deixar o compilador inferir o tipo local.",
   "explanation": "...",
   "whyModernWins": [
@@ -201,50 +211,33 @@ file.
 }
 ```
 
-`oldCode` and `modernCode` are always copied from the English file at build
-time; translators must not provide them (or they are silently ignored). This
-keeps code snippets language-neutral.
+`oldCode` and `modernCode` are **always overwritten** with the English values at
+build time, regardless of what appears in the translation file. Translators may
+leave those fields empty or copy the English values verbatim — neither causes
+any harm.
 
 ---
 
-## `locales.properties` — Supported Locales Registry
+## Generator — Resolution Order
 
-```properties
-# html-generators/locales.properties
-# format: locale=Display name  (first entry is the default/primary locale)
-en=English
-pt-BR=Português (Brasil)
-ja=日本語
-```
-
-The generator reads this file to know which locales to build and what label
-to show in the language selector.
-
----
-
-## Generator Changes
-
-### Resolution Order
-
-For each pattern the generator:
+For each pattern and locale the generator:
 
 1. Loads the English baseline from `content/<cat>/<slug>.json`.
-2. Checks if `translations/content/<locale>/<cat>/<slug>.json` exists.
-   - If **yes**: use the translated file but override `oldCode`/`modernCode`
+2. Checks whether `translations/content/<locale>/<cat>/<slug>.json` exists.
+   - **Yes** → use the translated file, then overwrite `oldCode`/`modernCode`
      with the English values.
-   - If **no**: use the English file and optionally mark the page with a
-     banner ("This pattern has not yet been translated").
-3. Loads `translations/strings/<locale>.json`, deep-merged over
-   `translations/strings/en.json`.
-4. Renders the template, substituting both content tokens (`{{title}}`, …)
-   and UI-string tokens (`{{nav.allPatterns}}`, …).
-5. Writes the output to `site/<locale>/<cat>/<slug>.html`
-   (or `site/<cat>/<slug>.html` for `en`).
+   - **No** → use the English file and inject an "untranslated" banner
+     (see next section).
+3. Loads `translations/strings/<locale>.json` deep-merged over `en.json`.
+4. Renders the template, substituting content tokens (`{{title}}`, …) and
+   UI-string tokens (`{{nav.allPatterns}}`, …).
+5. Writes output to `site/<locale>/<cat>/<slug>.html`
+   (or `site/<cat>/<slug>.html` for English).
 
-### Untranslated Pattern Banner (optional)
+### Untranslated Pattern Banner
 
 When falling back to English content for a non-English locale, the generator
-can inject a `<div class="untranslated-notice">` banner:
+injects:
 
 ```html
 <div class="untranslated-notice" lang="en">
@@ -259,8 +252,8 @@ The banner is suppressed when the locale is `en` or a translation file exists.
 
 ## Template Changes
 
-Every hard-coded English string in the templates is replaced with a token.
-The token naming convention mirrors the key path in `strings/{locale}.json`:
+Every hard-coded English string in the templates is replaced with a token whose
+name mirrors the dot-separated key path in `strings/{locale}.json`:
 
 | Before | After |
 |---|---|
@@ -272,7 +265,7 @@ The token naming convention mirrors the key path in `strings/{locale}.json`:
 | `Copied!` | `{{copy.copied}}` |
 | `Search patterns…` | `{{search.placeholder}}` |
 
-The `<html>` tag becomes `<html lang="{{locale}}">`.
+The `<html>` opening tag becomes `<html lang="{{locale}}">`.
 
 ---
 
@@ -281,8 +274,8 @@ The `<html>` tag becomes `<html lang="{{locale}}">`.
 `hreflang` alternate links are generated for every supported locale:
 
 ```html
-<link rel="alternate" hreflang="en"       href="https://javaevolved.github.io/language/type-inference-with-var.html">
-<link rel="alternate" hreflang="pt-BR"    href="https://javaevolved.github.io/pt-BR/language/type-inference-with-var.html">
+<link rel="alternate" hreflang="en"        href="https://javaevolved.github.io/language/type-inference-with-var.html">
+<link rel="alternate" hreflang="pt-BR"     href="https://javaevolved.github.io/pt-BR/language/type-inference-with-var.html">
 <link rel="alternate" hreflang="x-default" href="https://javaevolved.github.io/language/type-inference-with-var.html">
 ```
 
@@ -295,18 +288,19 @@ The list of locales is rendered at build time from `locales.properties`:
 
 ```html
 <select id="localePicker" aria-label="Select language">
-  <option value="en"    >English</option>
+  <option value="en">English</option>
   <option value="pt-BR" selected>Português (Brasil)</option>
 </select>
 ```
 
-`app.js` handles path-rewriting when the user picks a different locale.
+`app.js` rewrites the current URL path to the equivalent page in the selected
+locale when the user changes the selection.
 
 ---
 
 ## `app.js` Changes
 
-The search index path and the locale picker rewrite must both be locale-aware:
+The search index path and locale picker must both be locale-aware:
 
 ```js
 // Detect current locale from path prefix
@@ -320,8 +314,8 @@ const indexPath = locale === 'en'
   : `/${locale}/data/snippets.json`;
 ```
 
-Localised strings needed by JavaScript (search placeholder, "no results"
-message, "Copied!") are embedded as a `<script>` block by the generator:
+Localised strings consumed by JavaScript are embedded as a `<script>` block by
+the generator so `app.js` doesn't need to fetch them separately:
 
 ```html
 <script>
@@ -333,51 +327,85 @@ message, "Copied!") are embedded as a `<script>` block by the generator:
 </script>
 ```
 
-`app.js` reads from `window.i18n` instead of hard-coded strings.
+`app.js` reads from `window.i18n` instead of hard-coded literals.
 
 ---
 
 ## GitHub Actions Changes
 
-The deploy workflow builds the English site first, then iterates every entry
-in `locales.properties` (skipping `en`) to build locale subtrees:
+The deploy workflow iterates all entries in `locales.properties`:
+
+```yaml
+- name: Build site
+  run: python3 html-generators/generate.py --all-locales
+```
+
+Or explicitly, to support incremental locale addition:
 
 ```yaml
 - name: Build site
   run: |
-    python3 html-generators/generate.py            # English
+    python3 html-generators/generate.py
     python3 html-generators/generate.py --locale pt-BR
     python3 html-generators/generate.py --locale ja
 ```
 
-Or, with a build-all mode added to the generator:
+---
 
-```yaml
-- name: Build site
-  run: python3 html-generators/generate.py --all-locales
+## AI-Driven Translation Workflow
+
+When a new slug is added, AI generates translations automatically:
+
+```
+New English slug  →  AI prompt  →  Translated JSON file  →  Schema validation  →  Commit
 ```
 
+### Why this architecture suits AI translation
+
+- The AI receives the full English JSON and returns a complete translated JSON —
+  no special field-filtering rules in the prompt.
+- `oldCode`/`modernCode` are overwritten by the build tooling, so AI can copy
+  them verbatim without risk of hallucinated code shipping to users.
+- The translated file passes the same JSON schema validation as English files —
+  no separate validation logic needed.
+- If the AI file does not exist yet, the fallback is an explicit "untranslated"
+  banner rather than a silent gap.
+
+### Automation steps
+
+1. **Trigger** — GitHub Actions detects a new or modified
+   `content/<cat>/<slug>.json` (push event or workflow dispatch).
+2. **Translate** — For each supported locale, call the translation model with:
+   ```
+   Translate the following Java pattern JSON from English to {locale}.
+   - Keep unchanged: slug, id, category, difficulty, jdkVersion, oldLabel,
+     modernLabel, oldCode, modernCode, docs, related, prev, next, support.state
+   - Translate: title, summary, explanation, oldApproach, modernApproach,
+     whyModernWins[*].title, whyModernWins[*].desc, support.description
+   - Return valid JSON only.
+   ```
+3. **Validate** — Run JSON schema validation (same rules as English content).
+4. **Commit** — Write the output to
+   `translations/content/{locale}/<cat>/<slug>.json` and commit.
+5. **Deploy** — The generator picks it up on next build; the "untranslated"
+   banner disappears automatically.
+
+### Keeping translations in sync
+
+When an English file is **modified**, the same automation regenerates the
+translated file or opens a PR flagging the diff for human review. A CI check
+can compare `id`, `slug`, and `jdkVersion` between the English and translated
+files to detect stale translations.
+
 ---
 
 ## Migration Path
 
 | Phase | Work |
 |---|---|
-| 1 | Create `translations/strings/en.json` by extracting every hard-coded string from templates; replace literals with `{{…}}` tokens; verify English output is byte-identical |
-| 2 | Add `locales.properties`; extend generator to load strings, support `--locale`, fall back gracefully |
-| 3 | Add language selector to nav + `app.js` locale detection and path rewrite |
+| 1 | Extract every hard-coded string from templates into `translations/strings/en.json`; replace literals with `{{…}}` tokens; verify English output is unchanged |
+| 2 | Add `locales.properties`; extend generator to load strings, support `--locale`, and fall back gracefully |
+| 3 | Add language selector to nav; implement `app.js` locale detection and path rewrite |
 | 4 | Translate `strings/pt-BR.json` and 2–3 content files as a proof-of-concept; verify fallback banner |
 | 5 | Update GitHub Actions; add `hreflang` alternate links |
-| 6 | Open translation contribution guide; document `translations/` schema |
-
----
-
-## Trade-offs
-
-| Pros | Cons |
-|---|---|
-| English is a first-class locale — no special-cased code paths | Larger initial refactor (all template strings must be extracted) |
-| Complete translation files are easy for translators to understand | Full content files are larger and harder to keep in sync with English originals |
-| 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 |
+| 6 | Wire up AI translation automation; add `translations/` schema documentation |