Language switch

i18n specs/i18n/contract.kmd

Step diagram

User picks a new locale
User
From the language switcher in the top nav or Settings.
SDK persists the choice
SDK
Saves under the canonical key (locale on web, SharedPreferences on Flutter).
ICU resources reload
SDK
Pending strings re-resolve from the new locale's bundle; en-US fallback fills any gap.
App rebuilds in place
App
No reload required: every string consumer subscribed to the locale change updates synchronously.

Common pitfalls

Reloading the whole page on web instead of using the in-app subscription — loses scroll position and form state.
Hardcoding strings somewhere off the ICU pipeline — those strings stay English forever.