30 lines
1.8 KiB
Markdown
30 lines
1.8 KiB
Markdown
|
# ADR-005: Localization Framework and App-Language Preference
|
||
|
|
|
||
|
|
## Status
|
||
|
|
|
||
|
|
Accepted
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
Atlas for Mac needed a real multilingual foundation rather than scattered hard-coded English strings. The user requirement was to support Chinese and English first, default to Chinese, and keep the language choice aligned across the app shell, settings, and worker-generated summaries.
|
||
|
|
|
||
|
|
## Decision
|
||
|
|
|
||
|
|
- Add a package-scoped localization layer with structured resources in `AtlasDomain` so the Swift package graph can share one localization source.
|
||
|
|
- Persist the app-language preference in `AtlasSettings` and default it to `zh-Hans`.
|
||
|
|
- Inject the selected locale at the app shell while also using the persisted setting to localize worker-generated summaries and settings-derived copy.
|
||
|
|
- Keep localized legal copy derived from the selected language rather than treating it as ad hoc free text.
|
||
|
|
|
||
|
|
## Consequences
|
||
|
|
|
||
|
|
- The app now supports `简体中文` and `English` with Chinese as the default user experience.
|
||
|
|
- Settings persistence, protocol payloads, and local workspace state now include the app-language preference.
|
||
|
|
- UI automation needs stable identifiers rather than relying only on visible text, because visible labels can now change by language.
|
||
|
|
- Future languages can be added by extending the shared localization resources rather than editing each screen in isolation.
|
||
|
|
|
||
|
|
## Alternatives Considered
|
||
|
|
|
||
|
|
- Use system language only and skip an in-app switch — rejected because the requirement explicitly needed in-app Chinese/English switching.
|
||
|
|
- Store language only in app-local UI state — rejected because worker-generated summaries and persisted settings copy would drift from the selected language.
|
||
|
|
- Localize each feature independently without a shared resource layer — rejected because it would create duplication and drift across the package graph.
|