feat(i18n-ko): core — add ko to UiLocale model

[me2seeks]

Problem

UiLocale will ship ['zh-CN','zh-TW','en'] after #3853. ko/ko-KR system languages fall back to en. There is no type-safe slot for Korean, so catalog entries cannot be added.

Desired outcome

• UI_LOCALES includes ko, isUiLocale/isUiLocalePreference accept ko
• resolveSystemUiLocale recognizes ko, ko-KR, ko_KR (case-insensitive, ko prefix) and maps auto → ko correctly
• uiLocaleToIntlLocale maps ko → ko-KR
• Existing zh-CN/zh-TW/en behavior unchanged; persisted auto preference preserved
• Tests cover resolveSystemUiLocale(['ko','ko-KR','en']) and resolveUiLocale('auto', ko); missing ko entry in any UiCatalog<T> fails typecheck

Alternatives or workarounds

Keep English fallback for Korean systems.

Scope

packages/core/src/ui-locale.ts + tests (desktop-locale-authority, e2e-fixture-locale). Reuses #3853 pattern for zh-TW. No catalog content in this slice.

Delivery note (2026-08-27 audit): This slice must not land alone with Partial<Record<UiLocale,T>> widening. Per notes/pr-3853-feature-audit.md — widening would make the already-enabled zh-CN/zh-TW optional as well and force every getter to add undefined fallback/assertion, then require a second global tighten. Instead, keep dictionaries off the enabled union in the domain slices (#3977-#3980) and enable ko atomically (or on a stacked integration branch), as UiCatalog<T> = Record<UiLocale,T> requires all catalogs to carry the key at once. See audit § Global follow-up.

Acceptance criteria

• resolveSystemUiLocale(['ko-KR']) === 'ko', ['en','ko'] === 'en' (order respected)
• uiLocaleToIntlLocale('ko') === 'ko-KR'
• npm --workspace @maka/core test green with new cases
• This issue does not merge to main alone — it lands together with the catalog slices via atomic vertical or stacked integration branch, keeping UiCatalog strict

Parent: #3974

[heeoneie]

I'd like to take #3975.

One thing I'd like to settle before starting, since it affects the other five slices too.

UiCatalog<T> is Record<UiLocale, T>, so adding ko to UI_LOCALES makes every catalog require a ko entry. I count 38 of them — 34 declared with satisfies UiCatalog<T> and 4 annotated directly — across apps/desktop, packages/ui, packages/cli and packages/core. The acceptance criteria name that as intended ("missing ko entry in any UiCatalog<T> fails typecheck"), which is the right property to want, but it does mean #3975 on its own lands main with a failing typecheck until the catalog slices follow. Branch protection requires a passing test check, so the PR would sit red on its own.

How would you like to sequence it? A few options I can see:

• stack all six on one integration branch and merge them together
• land feat(i18n-ko): core — add ko to UiLocale model #3975 last, after the catalog slices are staged behind the current type
• widen UiCatalog so ko is optional first, then tighten it in a final PR once the catalogs are filled

Happy to go with whichever you prefer — I just don't want to be the one who puts red CI on main. If the third option is the one you want, I can fold the widening into #3975 so it stays a single self-contained change.

On the translation slices: I'd rather not claim one yet. #3977 alone is around 2,900 lines of copy, and I'd like to run the app in ko after this slice lands before committing to wording at that volume — tone is easier to get right against a real screen than against a diff.

[me2seeks]

Hi @heeoneie — thanks so much for catching this so early and for counting the 38 catalogs! You're totally right — Record<UiLocale, T> makes a pure core-only #3975 red on its own, and we definitely don't want you to be the one to put red CI on main.

Let's go with option 3 — widen then tighten — it's the kindest to reviewers and keeps everything green:

• Please feel free to fold the widening right into feat(i18n-ko): core — add ko to UiLocale model #3975 so it stays self-contained. Something like Partial<Record<UiLocale, T>> & Record<'en', T> (with en still required) is perfect — missing ko will just fall back to en for a couple of weeks, which is exactly the expected behavior for a not-yet-shipped locale, so no risk.
• That lets feat(i18n-ko): core — add ko to UiLocale model #3975 land green, then feat(i18n-ko): desktop slice 1 — settings-preferences/onboarding/shell/permissions #3977-feat(i18n-ko): native surfaces and E2E fixtures #3980 can land as small, focused slices, and we'll do one final tiny tighten PR to bring UiCatalog<T> back to strict Record<UiLocale, T> once all catalogs are filled.
• No need to stack everything on an integration branch or land core last — widen-then-tighten keeps the history clean and reviewable.

Also totally understand holding off on claiming #3977 — ~2,900 lines is a lot to word-smith from a diff! Please take your time, run it in ko after #3975 lands, and just comment I'd like to take #3977 (or whichever slice you prefer) whenever you're ready. No rush at all.

Just for heads-up: we're settling the shared contract as ['zh-CN','zh-TW','en','ko'] (following #3853's region-aware shape), so #3975 will be built on ['zh-CN','zh-TW','en'] — we'll update the description to match, you don't need to rework anything beyond the widening.

Thanks again for the super careful analysis and for offering to carry the Korean copy — really appreciate you!

[me2seeks]

Hi @heeoneie — quick correction to my last message, sorry for the whiplash!

After your note I had a deeper feature audit run on #3853 (head 13428763b), and it flagged the Partial<Record<UiLocale,T>> widen-then-tighten we just agreed on. The audit's point is fair: that widening wouldn't just make ko optional — it would also make the already-shipped zh-CN/zh-TW optional, and force every UiCatalog getter to add an undefined fallback/assertion, then require a second global tighten. That's more risk than the small-PR benefit is worth.

Updated guidance per the audit: let's not widen. Instead, please keep the ko dictionaries off the enabled union in your domain slices (#3977-#3980) — you can prepare them on branches that don't yet add ko to UI_LOCALES — and then enable ko atomically (either one atomic vertical that adds UI_LOCALES + all catalogs together with clearly separated commits like #3853, or a stacked integration branch). The type stays strict Record<UiLocale,T> the whole time.

I know that's the opposite of what I just said — really sorry for the flip-flop! Your counting of the 38 catalogs was spot-on and is exactly why the audit prefers the atomic/stacked shape over the widening. If you'd still prefer to run ko live before committing wording, the stacked branch still lets you do that locally without putting an optional type on main.

I've updated the issue body to reflect this — let me know if the new shape works for you, or if you'd like to keep #3975 parked until #3853 lands and then do the atomic enable together. Again, sorry for the change and thanks for your patience!

[heeoneie]

No whiplash — the audit is right, and #389's reasoning goes further than the type shape: the timeout/rate/auth/5xx/network classification in redaction.ts is already duplicated between generalizedErrorMessage and generalizedErrorMessageChinese — identical branches, different strings — and ko would have made that a third copy on main (a fourth at #3853's head). Better to collapse it to "classify once → typed locale catalog" before another locale exists, not after.

I've read #3853 and @AcerYue0's contract question, so I'm working from ['zh-CN','zh-TW','en'], not the ['zh','en'] still in the #3975 body. Parking behind #3853 makes sense — adding ko is one line in UI_LOCALES once it lands.

On the classifier: I'd rather not open that PR right now. It touches the same file #3853 is actively reworking, and dropping a refactor there while it's blocked would just cost @AcerYue0 another rebase. Two options I'm happy with:

• I open it after feat(i18n): add Traditional Chinese locale #3853 lands, collapsing all three at once
• or I open it now against main (two copies today) if you'd prefer feat(i18n): add Traditional Chinese locale #3853 rebase onto it rather than carry a third

Your call — whichever costs @AcerYue0 less.

Not claiming a translation slice until #3853 lands.

[me2seeks]

No whiplash — the audit is right, and #389's reasoning goes further than the type shape: the timeout/rate/auth/5xx/network classification in redaction.ts is already duplicated between generalizedErrorMessage and generalizedErrorMessageChinese — identical branches, different strings — and ko would have made that a third copy on main (a fourth at #3853's head). Better to collapse it to "classify once → typed locale catalog" before another locale exists, not after.

I've read #3853 and @AcerYue0's contract question, so I'm working from ['zh-CN','zh-TW','en'], not the ['zh','en'] still in the #3975 body. Parking behind #3853 makes sense — adding ko is one line in UI_LOCALES once it lands.

On the classifier: I'd rather not open that PR right now. It touches the same file #3853 is actively reworking, and dropping a refactor there while it's blocked would just cost @AcerYue0 another rebase. Two options I'm happy with:

• I open it after feat(i18n): add Traditional Chinese locale #3853 lands, collapsing all three at once
• or I open it now against main (two copies today) if you'd prefer feat(i18n): add Traditional Chinese locale #3853 rebase onto it rather than carry a third

Your call — whichever costs @AcerYue0 less.

Not claiming a translation slice until #3853 lands.

Agreed. This looks better tracked as a separate issue rather than expanding #3975’s scope.

I’ll open a follow-up issue for collapsing the duplicated error classification into a single classifier + typed locale catalog, and mark it as blocked by #3853 for now. That should avoid forcing another rebase on @AcerYue0 while keeping the refactor visible and scoped separately.

Once #3853 lands, we can handle the classifier refactor there before adding another locale path. No need to claim a translation slice yet.

[heeoneie]

@Astro-Han I see this picked up good first issue and help wanted yesterday — could I be assigned, or would you rather it went to someone new?

I raised the Record<UiLocale, T> coupling on this issue and worked the sequencing out with @me2seeks above, so I have been treating it as mine and deliberately have not opened anything while #3853 is in flight. It is unassigned, though, and with the new labels I would rather not have a first-time contributor start the same work and collide with it.

The blocker did move this morning: @AcerYue0 merged main into #3853 at 03:59 UTC and requested review. It still reports a conflict, so I am not starting yet — the contract here depends on whether UI_LOCALES lands as ['zh-CN','zh-TW','en'], and I would rather build on the shape that actually merges than guess at it.

The labels are still on the issue, so if you would rather shape this differently, just say. I would mainly like to avoid two people discovering the same UiCatalog problem independently.

[heeoneie]

take