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.
41 lines
2.2 KiB
Markdown
41 lines
2.2 KiB
Markdown
# 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"`
|
||
or `data-language-content="pt"` on its outer element. English is visible in
|
||
server HTML; the toggle uses the native `hidden` attribute for the inactive
|
||
locale.
|
||
- Add `<LanguageToggle />` to the guide top bar. Astro's `client:idle` directive
|
||
is only valid for framework components; this `.astro` island defers its
|
||
browser setup with `requestIdleCallback` (and a timeout fallback) instead. Do
|
||
not hydrate the page or use `client:load`; the control is deliberately
|
||
idle-priority.
|
||
- The island owns the `ai-for-dummies-language` localStorage key. Every read and
|
||
write remains inside `try`/`catch`, because previews may disable storage.
|
||
- On each selection the island sets `<html lang>` to `en` or `pt-BR`, updates
|
||
its `[data-lang]` buttons' `.active` class and `aria-pressed` state, updates
|
||
`[data-language-content]`, then dispatches `ai-for-dummies:languagechange` on
|
||
`window`. The event detail is `{ language: 'en' | 'pt' }`.
|
||
- The guide selector island (15a) must read `document.documentElement.lang` when
|
||
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’s `applyLanguage` behaviour 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.
|