Add i18n specification

[Copilot]

• Create specs/i18n/ directory with initial i18n proposals
• Add recommendation explaining why the full-replacement approach suits AI-driven translation
• Remove Plan A per review feedback
• Rewrite Plan B and recommendation as a single unified specs/i18n/i18n-spec.md (Internationalization Specification)
• Replace all python3 html-generators/generate.py references in the spec with jbang html-generators/generate.java to match the project's canonical build tooling
• Specify per-key English fallback for missing UI string keys: the generator logs a [WARN] for each missing key and always completes the build — no page is ever left with a blank string
• Replace <select> language picker with a 🌐 globe icon button placed next to the theme toggle in .nav-right, opening an accessible dropdown list of locales (persisted to localStorage)
• List all 11 content categories (language, collections, strings, streams, concurrency, io, errors, datetime, security, tooling, enterprise) in the directory layout section

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Plan architectural change for i18n</issue_title>
<issue_description>Propose two plans for an update to the architecture of the website, to support internationalization.

Add the plans to ./specs/i18n</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Plan architectural change for i18n #74

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[brunoborges]

@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]

@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.

[brunoborges]

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

[Copilot]

@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).

[brunoborges]

@copilot rewrite Plan B as Internationalization Spec.

[Copilot]

@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.

[brunoborges]

@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]

@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]

@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).

[Copilot]

Pull request overview

This PR introduces a comprehensive internationalization (i18n) specification for the java.evolved static site. The specification defines a two-layer architecture for supporting multiple languages: UI strings with per-key fallback and full-replacement translated content files.

Changes:

• Added specs/i18n/i18n-spec.md documenting the complete i18n architecture, including directory layout, translation file schemas, generator resolution order, template changes, navigation updates, and an AI-driven translation workflow
• Specification uses jbang html-generators/generate.java as the canonical build command throughout
• Defined per-key English fallback mechanism for missing UI string keys with warning-only behavior (no build failures)

Comments suppressed due to low confidence (1)

specs/i18n/i18n-spec.md:328

• Use "Localized" instead of "Localised" to maintain consistency with American English spelling used throughout the codebase.

Localised strings consumed by JavaScript are embedded as a `<script>` block by

[brunoborges]

@copilot is this specification covering how language selector will be displayed on the website? My preference is a globe/world icon next to the dark/light theme selector button, where a dropdown list shows up and allows the user to change the language.

[Copilot]

@copilot is this specification covering how language selector will be displayed on the website? My preference is a globe/world icon next to the dark/light theme selector button, where a dropdown list ...

The old spec used a plain <select> and didn't describe the visual placement. Updated in commit add7dec — the "Navigation — Language Selector" section now specifies a 🌐 globe icon button placed immediately next to the theme toggle inside .nav-right. Clicking it opens an accessible role="listbox" dropdown (hidden by default, closed on outside-click or Escape), with the active locale highlighted via aria-selected. The choice is persisted to localStorage so it survives page navigation.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

specs/i18n/i18n-spec.md:345

• The Portuguese example shows "Buscar padrões..." (line 345) but to be consistent with the English "Search snippets..." terminology actually used in the site (templates/index.html:290), this should be "Buscar snippets..." or "Buscar trechos..." instead.

    searchPlaceholder: "Buscar padrões...",