Skip to content

feat(desktop): make UI language selection coherent and complete #1052

Closed
#1238
Closed
feat(desktop): make UI language selection coherent and complete#1052
#1238
Labels
enhancementNew feature or request

Description

@Astro-Han
Astro-Han
opened on Jul 15, 2026

Problem

Settings exposes Follow system / 中文 / English, but localization is partial:

  • personalization.uiLocale is persisted, while the effective locale is only mirrored through DOM attributes.
  • Changing those attributes does not provide reactive locale state to the React tree.
  • Most desktop and @maka/ui copy remains inline Chinese.
  • English therefore produces a mixed-language interface.
  • Follow system currently falls back to Chinese instead of following the system.

The missing invariant is: one derived locale must drive all user-visible copy and locale-sensitive formatting.

Desired outcome

  • personalization.uiLocale remains the only persisted preference.
  • One derived zh | en locale drives React rendering, <html lang>, and Intl.
  • Explicit language changes apply immediately and survive restart.
  • Follow system selects a supported system language after desktop coverage is complete.
  • Desktop and @maka/ui copy comes from typed catalogs owned by the presenting layer.
  • Replaced hard-coded and DOM-reading paths are removed.

Use a small typed TypeScript catalog and React locale context. Do not introduce i18next until more locales, external translators, or a translation platform create that need.

Ownership

  • @maka/core: locale preference/type and pure resolution policy.
  • @maka/ui: locale provider and shared-component catalog.
  • Desktop renderer: desktop product catalog and root wiring.
  • CLI: unchanged; localization is a separate concern.

The resolved locale is derived and never persisted.

Delivery slices

flowchart LR
    I[Issue: coherent desktop localization] --> P1[PR 1<br/>Reactive locale foundation]
    P1 --> P2[PR 2<br/>Shell, onboarding, settings]
    P1 --> P3[PR 3<br/>Conversation, sessions, tools]
    P2 --> P4[PR 4<br/>Remaining coverage and completion gate]
    P3 --> P4
    P4 --> D[Complete desktop zh/en<br/>Enable Follow system]
Loading

PR 2 and PR 3 can proceed in parallel after PR 1.

PR 1: Reactive locale foundation

  • Consolidate locale types in @maka/core.
  • Add LocaleProvider / useUiLocale() to @maka/ui.
  • Wire the persisted preference into desktop React state.
  • Keep <html lang> and test overrides synchronized.
  • Preserve auto -> zh temporarily to avoid broadening mixed-language exposure.
  • Test runtime switching, persistence, and override precedence.

PR 2: Shell, onboarding, and settings

  • Migrate navigation, onboarding, Settings, shared controls, toasts, tooltips, placeholders, and accessibility labels used by this journey.
  • Ensure users can find the language setting, switch language, navigate, and switch back without untranslated shell controls.

PR 3: Conversation, sessions, and tools

  • Migrate the complete fake-backend conversation journey: empty state, composer, messages, permissions, session states, tool activity, errors, timestamps, counts, and accessibility copy.
  • Cover presentation helpers in both locales.

PR 4: Remaining coverage and completion gate

  • Migrate all remaining desktop and shared-UI surfaces.
  • Remove replaced localization paths and Chinese-only contracts.
  • Add CI enforcement against new inline user-visible copy in migrated source.
  • Make Follow system resolve from supported system languages.
  • Add representative zh/en E2E and visual coverage.

Completion criteria

  • Chinese and English each produce a coherent desktop renderer.
  • Runtime switching requires no reload.
  • Follow system behaves as labeled.
  • Catalog shapes match at compile time; missing English copy cannot silently fall back.
  • <html lang> and Intl use the resolved locale.
  • There is one persisted preference, one derived locale, and no parallel localization path.

Non-goals

  • CLI localization
  • Additional locales
  • i18next, ICU, remote catalogs, or translation-platform integration
  • Translating user content, model output, brands, code, commands, or generated content

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions