i18n: partial translation files, difficultyDisplay, YAML support

- Translation files now contain only translatable fields (title, summary,
  explanation, oldApproach, modernApproach, whyModernWins, support.description).
  The generator overlays them onto the English base, preventing divergence.
- Add difficultyDisplay token: CSS class stays as enum value, display text
  resolved from UI strings (difficulty.beginner/intermediate/advanced).
- Generator loadStrings and resolveSnippet now support .json/.yaml/.yml
  translation files via findWithExtensions/readAuto helpers.
- Update i18n spec with field translation reference table and partial-file
  approach.
- Trim existing pt-BR translation files to translatable fields only.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: brunoborges

html-generators/generate.java

@@ -76,20 +76,37 @@ static Map<String, String> flattenJson(JsonNode node, String prefix) {
     return map;
 }
 
+/** Find a file by base path, trying .json, .yaml, .yml extensions */
+static Optional<Path> findWithExtensions(Path dir, String baseName) {
+    for (var ext : List.of("json", "yaml", "yml")) {
+        var p = dir.resolve(baseName + "." + ext);
+        if (Files.exists(p)) return Optional.of(p);
+    }
+    return Optional.empty();
+}
+
+/** Read a file using the appropriate mapper based on its extension */
+static JsonNode readAuto(Path path) throws IOException {
+    var name = path.getFileName().toString();
+    var ext = name.substring(name.lastIndexOf('.') + 1);
+    return MAPPERS.getOrDefault(ext, JSON_MAPPER).readTree(path.toFile());
+}
+
 /** Load UI strings for a locale, falling back to en.json for missing keys */
 static Map<String, String> loadStrings(String locale) throws IOException {
-    var enPath = Path.of(TRANSLATIONS_DIR, "strings", "en.json");
-    var enStrings = flattenJson(JSON_MAPPER.readTree(enPath.toFile()), "");
+    var enFile = findWithExtensions(Path.of(TRANSLATIONS_DIR, "strings"), "en")
+            .orElseThrow(() -> new IOException("No English strings file found"));
+    var enStrings = flattenJson(readAuto(enFile), "");
 
     if (locale.equals("en")) return enStrings;
 
-    var localePath = Path.of(TRANSLATIONS_DIR, "strings", locale + ".json");
-    if (!Files.exists(localePath)) {
-        IO.println("[WARN] strings/%s.json not found — using all English strings".formatted(locale));
+    var localeFile = findWithExtensions(Path.of(TRANSLATIONS_DIR, "strings"), locale);
+    if (localeFile.isEmpty()) {
+        IO.println("[WARN] strings/%s.{json,yaml,yml} not found — using all English strings".formatted(locale));
         return enStrings;
     }
 
-    var localeStrings = flattenJson(JSON_MAPPER.readTree(localePath.toFile()), "");
+    var localeStrings = flattenJson(readAuto(localeFile.get()), "");
     var merged = new LinkedHashMap<>(enStrings);
     for (var entry : localeStrings.entrySet()) {
         if (enStrings.containsKey(entry.getKey())) {
@@ -313,6 +330,10 @@ String supportBadge(String state, Map<String, String> strings) {
     };
 }
 
+String difficultyDisplay(String difficulty, Map<String, String> strings) {
+    return strings.getOrDefault("difficulty." + difficulty, difficulty);
+}
+
 String supportBadgeClass(String state) {
     return switch (state) {
         case "preview" -> "preview";
@@ -363,6 +384,7 @@ String renderRelatedCard(String tpl, Snippet rel, String locale, Map<String, Str
     return replaceTokens(tpl, Map.ofEntries(
             Map.entry("category", rel.category()), Map.entry("slug", rel.slug()),
             Map.entry("catDisplay", rel.catDisplay()), Map.entry("difficulty", rel.difficulty()),
+            Map.entry("difficultyDisplay", difficultyDisplay(rel.difficulty(), strings)),
             Map.entry("title", escape(rel.title())),
             Map.entry("oldLabel", escape(rel.oldLabel())), Map.entry("oldCode", escape(rel.oldCode())),
             Map.entry("modernLabel", escape(rel.modernLabel())), Map.entry("modernCode", escape(rel.modernCode())),
@@ -403,6 +425,7 @@ String generateHtml(Templates tpl, Snippet s, Map<String, Snippet> all, Map<Stri
             Map.entry("title", escape(s.title())), Map.entry("summary", escape(s.summary())),
             Map.entry("slug", s.slug()), Map.entry("category", s.category()),
             Map.entry("categoryDisplay", s.catDisplay()), Map.entry("difficulty", s.difficulty()),
+            Map.entry("difficultyDisplay", difficultyDisplay(s.difficulty(), extraTokens)),
             Map.entry("jdkVersion", s.jdkVersion()),
             Map.entry("oldLabel", escape(s.oldLabel())), Map.entry("modernLabel", escape(s.modernLabel())),
             Map.entry("oldCode", escape(s.oldCode())), Map.entry("modernCode", escape(s.modernCode())),
@@ -423,22 +446,46 @@ String generateHtml(Templates tpl, Snippet s, Map<String, Snippet> all, Map<Stri
     return replaceTokens(tpl.page(), tokens);
 }
 
-/** Load translated content or fall back to English; overwrite code fields from English */
+/** Translatable field names — only these are merged from translation files */
+static final Set<String> TRANSLATABLE_FIELDS = Set.of(
+    "title", "summary", "explanation", "oldApproach", "modernApproach", "whyModernWins", "support"
+);
+
+/**
+ * Overlay translated content onto the English base.
+ * Translation files contain only translatable fields; everything else
+ * (id, slug, category, difficulty, code, navigation, docs, etc.)
+ * is always taken from the English source of truth.
+ */
 Snippet resolveSnippet(Snippet englishSnippet, String locale) {
     if (locale.equals("en")) return englishSnippet;
 
-    var translatedPath = Path.of(TRANSLATIONS_DIR, "content", locale,
-            englishSnippet.category(), englishSnippet.slug() + ".json");
-    if (!Files.exists(translatedPath)) return englishSnippet;
+    var translatedDir = Path.of(TRANSLATIONS_DIR, "content", locale, englishSnippet.category());
+    var translatedFile = findWithExtensions(translatedDir, englishSnippet.slug());
+    if (translatedFile.isEmpty()) return englishSnippet;
 
     try {
-        var translatedNode = (com.fasterxml.jackson.databind.node.ObjectNode) JSON_MAPPER.readTree(translatedPath.toFile());
-        // Overwrite code fields with English values
-        translatedNode.put("oldCode", englishSnippet.oldCode());
-        translatedNode.put("modernCode", englishSnippet.modernCode());
-        return new Snippet(translatedNode);
+        var translatedNode = (com.fasterxml.jackson.databind.node.ObjectNode) readAuto(translatedFile.get());
+        // Start from a copy of the English node
+        var merged = englishSnippet.node().deepCopy();
+        // Overlay only translatable fields from the translation file
+        for (var field : TRANSLATABLE_FIELDS) {
+            if (translatedNode.has(field)) {
+                if (field.equals("support") && translatedNode.get("support").isObject()) {
+                    // For support, only merge "description" — keep "state" from English
+                    var translatedSupport = translatedNode.get("support");
+                    if (translatedSupport.has("description")) {
+                        ((com.fasterxml.jackson.databind.node.ObjectNode) merged.get("support"))
+                                .put("description", translatedSupport.get("description").asText());
+                    }
+                } else {
+                    ((com.fasterxml.jackson.databind.node.ObjectNode) merged).set(field, translatedNode.get(field));
+                }
+            }
+        }
+        return new Snippet(merged);
     } catch (IOException e) {
-        IO.println("[WARN] Failed to load %s — using English".formatted(translatedPath));
+        IO.println("[WARN] Failed to load %s — using English".formatted(translatedFile.get()));
         return englishSnippet;
     }
 }

specs/i18n/i18n-spec.md

@@ -197,25 +197,50 @@ is purely informational and does **not** abort the build.
 
 ## Content Translation Files
 
-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.
+Translated content files are **partial** — they contain **only** the
+translatable fields. The generator overlays them onto the English base at build
+time. This prevents translators from diverging structural data (code,
+navigation, metadata) from the English source of truth.
+
+### Field Translation Reference
+
+Every field in a slug definition file falls into one of three categories:
+
+| Category | Fields | Rule |
+|---|---|---|
+| **Translate** (include in translation file) | `title`, `summary`, `explanation`, `oldApproach`, `modernApproach`, `whyModernWins` (full array), `support.description` | These are the **only** fields present in a translation file |
+| **English source of truth** (never in translation file) | `id`, `slug`, `category`, `difficulty`, `jdkVersion`, `oldLabel`, `modernLabel`, `oldCode`, `modernCode`, `prev`, `next`, `related`, `docs` | Always taken from the English content file; any values in the translation file are ignored |
+| **Translated via UI strings** | `difficulty`, `support.state` | Enum values stay in English; display names resolved from `translations/strings/{locale}.json` at build time |
+
+**Why enum fields use UI strings instead of content translation:**
+
+Fields like `difficulty` (`beginner`, `intermediate`, `advanced`) and
+`support.state` (`available`, `preview`, `experimental`) are enum values used
+programmatically as CSS classes, filter keys, and data attributes. Their
+**display names** are resolved at build time from the UI strings layer:
+
+- `difficulty` → `difficulty.beginner`, `difficulty.intermediate`, `difficulty.advanced`
+- `support.state` → `support.available`, `support.preview`, `support.experimental`
+- `category` → display name from `categories.properties`
+
+This separation ensures enum values remain stable across locales while display
+text is centrally managed and consistently translated.
+
+**Other non-translated fields:**
+
+- `whyModernWins[*].icon` — emoji; typically kept as-is across locales
+- `docs[*].title` — kept in English since the linked documentation is English
+
+### Example Translated File
+
+Translation files contain **only** translatable fields — no structural data:
 
 ```json
 // translations/content/pt-BR/language/type-inference-with-var.json
 {
-  "id": 1,
-  "slug": "type-inference-with-var",
   "title": "Inferência de tipo com var",
-  "category": "language",
-  "difficulty": "beginner",
-  "jdkVersion": "10",
-  "oldLabel": "Java 8",
-  "modernLabel": "Java 10+",
   "oldApproach": "Tipos explícitos",
   "modernApproach": "Palavra-chave var",
-  "oldCode": "...",
-  "modernCode": "...",
   "summary": "Use var para deixar o compilador inferir o tipo local.",
   "explanation": "...",
   "whyModernWins": [
@@ -224,31 +249,22 @@ partial-merge edge cases and makes each file self-contained.
     { "icon": "🔒", "title": "Seguro", "desc": "..." }
   ],
   "support": {
-    "state": "available",
     "description": "Amplamente disponível desde o JDK 10 (março de 2018)"
-  },
-  "prev": "language/...",
-  "next": "language/...",
-  "related": ["..."],
-  "docs": [{ "title": "...", "href": "..." }]
+  }
 }
 ```
 
-`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.
-
 ---
 
 ## Generator — Resolution Order
 
 For each pattern and locale the generator:
 
-1. Loads the English baseline from `content/<cat>/<slug>.json`.
-2. Checks whether `translations/content/<locale>/<cat>/<slug>.json` exists.
-   - **Yes** → use the translated file, then overwrite `oldCode`/`modernCode`
-     with the English values.
+1. Loads the English baseline from `content/<cat>/<slug>.json` (or `.yaml`/`.yml`).
+2. Checks whether `translations/content/<locale>/<cat>/<slug>.{json,yaml,yml}` exists.
+   - **Yes** → deep-copies the English node, then overlays only the translatable
+     fields (`title`, `summary`, `explanation`, `oldApproach`, `modernApproach`,
+     `whyModernWins`, `support.description`) from the translation file.
    - **No** → use the English file and inject an "untranslated" banner
      (see next section).
 3. Loads `translations/strings/<locale>.json` deep-merged over `en.json`.
@@ -414,14 +430,17 @@ New English slug  →  AI prompt  →  Translated JSON file  →  Schema validat
    `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.
+   Translate the following Java pattern from English to {locale}.
+   Return a JSON file containing ONLY these translated fields:
+   - title, summary, explanation, oldApproach, modernApproach
+   - whyModernWins (full array with icon, title, desc)
+   - support.description (inside a "support" object)
+   Do NOT include: slug, id, category, difficulty, jdkVersion, oldLabel,
+   modernLabel, oldCode, modernCode, docs, related, prev, next, support.state.
+   Return valid JSON only.
    ```
-3. **Validate** — Run JSON schema validation (same rules as English content).
+   See the **Field Translation Reference** table above for the full rationale.
+3. **Validate** — Verify the output contains only translatable fields.
 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"
@@ -430,9 +449,10 @@ New English slug  →  AI prompt  →  Translated JSON file  →  Schema validat
 ### 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.
+translated file or opens a PR flagging the diff for human review. Since
+translation files only contain translatable text, structural changes to the
+English file (code, navigation, metadata) take effect immediately without
+needing to update the translation.
 
 ---
 

templates/related-card.html

@@ -3,7 +3,7 @@
             <div class="tip-card-header">
               <div class="tip-badges">
                 <span class="badge {{category}}">{{catDisplay}}</span>
-                <span class="badge {{difficulty}}">{{difficulty}}</span>
+                <span class="badge {{difficulty}}">{{difficultyDisplay}}</span>
               </div>
             </div>
             <h3>{{title}}</h3>

templates/slug-template.html

@@ -123,7 +123,7 @@
     <div class="tip-header">
       <div class="tip-meta">
         <span class="badge {{category}}">{{categoryDisplay}}</span>
-        <span class="badge {{difficulty}}">{{difficulty}}</span>
+        <span class="badge {{difficulty}}">{{difficultyDisplay}}</span>
       </div>
       <h1>{{title}}</h1>
       <p>{{summary}}</p>
@@ -175,7 +175,7 @@ <h1>{{title}}</h1>
       </div>
       <div class="info-card">
         <div class="info-label">{{sections.difficulty}}</div>
-        <div class="info-value blue">{{difficulty}}</div>
+        <div class="info-value blue">{{difficultyDisplay}}</div>
       </div>
     </div>
 

translations/content/pt-BR/collections/immutable-list-creation.json

@@ -1,17 +1,8 @@
 {
-  "id": 19,
-  "slug": "immutable-list-creation",
-  "title": "Criação de listas imutáveis",
-  "category": "collections",
-  "difficulty": "beginner",
-  "jdkVersion": "9",
-  "oldLabel": "Java 8",
-  "modernLabel": "Java 9+",
-  "oldApproach": "Encapsulamento verboso",
   "modernApproach": "List.of()",
-  "oldCode": "",
-  "modernCode": "",
   "summary": "Crie listas imutáveis em uma expressão limpa.",
+  "title": "Criação de listas imutáveis",
+  "oldApproach": "Encapsulamento verboso",
   "explanation": "List.of() cria uma lista verdadeiramente imutável — sem encapsulamento, sem cópia defensiva. Rejeita elementos nulos (null-hostile) e é estruturalmente imutável. O modo antigo exigia três chamadas aninhadas.",
   "whyModernWins": [
     {
@@ -31,24 +22,6 @@
     }
   ],
   "support": {
-    "state": "available",
     "description": "Amplamente disponível desde o JDK 9 (setembro de 2017)"
-  },
-  "prev": "language/exhaustive-switch",
-  "next": "collections/immutable-map-creation",
-  "related": [
-    "collections/immutable-map-creation",
-    "collections/immutable-set-creation",
-    "collections/sequenced-collections"
-  ],
-  "docs": [
-    {
-      "title": "List.of()",
-      "href": "https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/List.html#of()"
-    },
-    {
-      "title": "Collections Factory Methods (JEP 269)",
-      "href": "https://openjdk.org/jeps/269"
-    }
-  ]
+  }
 }

translations/content/pt-BR/language/records-for-data-classes.json

@@ -1,17 +1,8 @@
 {
-  "id": 5,
-  "slug": "records-for-data-classes",
-  "title": "Records para classes de dados",
-  "category": "language",
-  "difficulty": "beginner",
-  "jdkVersion": "16",
-  "oldLabel": "Java 8",
-  "modernLabel": "Java 16+",
-  "oldApproach": "POJO verboso",
   "modernApproach": "record",
-  "oldCode": "",
-  "modernCode": "",
   "summary": "Uma linha substitui mais de 30 linhas de boilerplate para portadores de dados imutáveis.",
+  "title": "Records para classes de dados",
+  "oldApproach": "POJO verboso",
   "explanation": "Records geram automaticamente o construtor, acessores (x(), y()), equals(), hashCode() e toString(). São imutáveis por design e ideais para DTOs, objetos de valor e pattern matching.",
   "whyModernWins": [
     {
@@ -31,24 +22,6 @@
     }
   ],
   "support": {
-    "state": "available",
     "description": "Amplamente disponível desde o JDK 16 (março de 2021)"
-  },
-  "prev": "language/pattern-matching-instanceof",
-  "next": "language/sealed-classes",
-  "related": [
-    "language/flexible-constructor-bodies",
-    "language/private-interface-methods",
-    "language/pattern-matching-switch"
-  ],
-  "docs": [
-    {
-      "title": "Records (JEP 395)",
-      "href": "https://openjdk.org/jeps/395"
-    },
-    {
-      "title": "Record class",
-      "href": "https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Record.html"
-    }
-  ]
+  }
 }