@copilot which plan is better? Especially considering we will be using AI to generate the translations later on, automatically, whenever a new slug is added.

@copilot which plan is better? Especially considering we will be using AI to generate the translations later on, automatically, whenever a new slug is added.

Plan B is the better fit for an AI-driven workflow. I've added a detailed breakdown in specs/i18n/recommendation.md (commit 318ffb1), but the key points are:

Plan A (overlay) is awkward for AI because the AI must know which fields to omit from the overlay (oldCode, modernCode, docs, related, prev/next). If the AI accidentally includes any of those, the build silently uses the AI value instead of the canonical English one — a subtle and hard-to-detect error.

Plan B (full replacement) is ideal because:

• The AI just translates the full JSON file — no special field-filtering rules in the prompt.
• The generator always overwrites oldCode/modernCode with the English values at build time, so even if the AI copies them verbatim (or hallucinates), the correct code still ships.
• Output validation is simple: run the same JSON schema checks used for English files.
• When a translation doesn't yet exist, the fallback is explicit (optional "not yet translated" banner) rather than silent.

The recommended automation loop is: detect new/changed English slug → AI translates → schema validation → commit to translations/content/{locale}/ → generator picks it up on next deploy.

@copilot ok let's get rid of Plan A, and focus on Plan B.

@copilot ok let's get rid of Plan A, and focus on Plan B.

Done (commit ce99798). plan-a-locale-keyed-content.md has been deleted. The Plan B spec and recommendation.md have been cleaned up to remove all Plan A cross-references and comparison tables — the specs/i18n/ folder now contains only plan-b-externalized-strings-full-translations.md and recommendation.md (which now documents the AI automation workflow directly).

@copilot rewrite Plan B as Internationalization Spec.

@copilot rewrite Plan B as Internationalization Spec.

Done (commit d301312). plan-b-externalized-strings-full-translations.md and recommendation.md have been replaced by a single specs/i18n/i18n-spec.md. It's written as an authoritative specification — no "plan" framing — and consolidates all sections: directory layout, string and content schemas, generator resolution order, template/HTML/JS changes, GitHub Actions setup, the AI-driven translation workflow, and the phased migration path.

@copilot

The specification suggests using the Python script, but the copilot-instructions.md in this repo are strictly pointing at the Java-based generator (triggered with jbang). If the instructions are not clear, make it so.

@copilot

The specification suggests using the Python script, but the copilot-instructions.md in this repo are strictly pointing at the Java-based generator (triggered with jbang). If the instruct...

Fixed in commit 9c2ff55. The spec now uses jbang html-generators/generate.java everywhere — in the directory layout comment, the GitHub Actions YAML block, and the explicit per-locale build examples.

@copilot I think that it is important to use the default english for a particular string if the translation doesn't have one. At least the page is rendered even with partial translation. As the generator finds cases where there is no translation, it should log with a warning, but proceed.

@copilot I think that it is important to use the default english for a particular string if the translation doesn't have one. At least the page is rendered even with partial translation. As the genera...

Done in commit 4b2330d. The spec now has an explicit key-level fallback rule: any key missing from a locale's strings file falls back to the English value, the generator emits a [WARN] for each such key, and the build always completes — no page is ever left with a blank string. The same rule is also called out in the Generator Resolution Order section (step 3).