Marcos Paulo
59bbff0ad9
Document the client-side, dual-rendered locale contract and dispatch a narrow language-change event for guide selector panels.\n\nDo not assemble the full-guide page or change its content collections; task 15d owns that integration.
2.2 KiB
2.2 KiB
Context: full-guide language switching
Decision
The Astro full guide keeps the current client-side language switch on its
existing /full-guide/ URL. It server-renders both locale variants and the
language-toggle island shows the selected variant after client:idle hydration.
This deliberately preserves the current no-URL-change contract, including links shared without a locale segment, and avoids a route/redirect and publishing change. The cost is duplicated localized HTML and both locales in the response. That is acceptable for this small guide and avoids sending duplicated string data through every interactive island.
Markup and island contract for task 15d
- Render each static localized fragment twice. Put
data-language-content="en"ordata-language-content="pt"on its outer element. English is visible in server HTML; the toggle uses the nativehiddenattribute for the inactive locale. - Add
<LanguageToggle />to the guide top bar. Astro'sclient:idledirective is only valid for framework components; this.astroisland defers its browser setup withrequestIdleCallback(and a timeout fallback) instead. Do not hydrate the page or useclient:load; the control is deliberately idle-priority. - The island owns the
ai-for-dummies-languagelocalStorage key. Every read and write remains insidetry/catch, because previews may disable storage. - On each selection the island sets
<html lang>toenorpt-BR, updates its[data-lang]buttons'.activeclass andaria-pressedstate, updates[data-language-content], then dispatchesai-for-dummies:languagechangeonwindow. The event detail is{ language: 'en' | 'pt' }. - The guide selector island (15a) must read
document.documentElement.langwhen it hydrates and listen for that event. On receipt it must re-render the currently active phase and all active selector panels from their collection data. This preserves today’sapplyLanguagebehaviour without coupling the toggle to page selectors.
This is a page-local contract: the existing /rules/ toggle continues using its
own rules-language key and must not be changed as part of full-guide
migration.