jackwener/maka-agent

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

Open

#1,052 opened on Jul 15, 2026

View on GitHub
 (0 comments) (0 reactions) (0 assignees)TypeScript (0 forks)github user discovery
enhancementgood first issue

Repository metrics

Stars
 (1 star)
PR merge metrics
 (PR metrics pending)

Description

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]

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

Contributor guide

Research direction
Focus on PR 1: Reactive locale foundation. Consolidate locale types in @maka/core, add LocaleProvider and useUiLocale in @maka/ui, wire persisted preference into desktop React state, synchronize html lang and test overrides. Ensure runtime switching, persistence, and override precedence.
Tech stack
typescriptreact
Domain
desktopfrontend
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
GitTypeScriptReact
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
65