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

[me2seeks]

Summary

Enable Korean in the Core UI locale vocabulary, system-language resolution and Intl formatting on top of the compatibility layer merged in #5921. Preserve the reviewed Korean error, just-now and quiet-preview copy from #5011; untranslated entries safely fall back to English. Existing English, Simplified Chinese and Traditional Chinese completeness remains enforced.

This follows the progressive rollout decision on #3975: Core enablement and each translation slice land as separate squash commits. The former all-or-nothing stack requirement is superseded. This PR remains draft pending exact-head CI and independent maintainer review; it does not merge automatically with its translation slices.

Scope

• Recognize ko, system ko-KR / ko_KR.UTF-8, and explicit Korean preferences; preserve language ordering and kok-IN → en.
• Map Korean to ko-KR for Intl formatting.
• Rebase onto main 6c63fa057ed97916b77db3ff002a13636d6a564a, retaining refactor(i18n): migrate UI catalogs to the resolver-based message format #5921's shipped-catalog safeguards and the extracted relative-time policy.
• Keep real Korean Core copy; do not add English ko placeholder blocks. New untranslated quiet-preview fields use the shared English fallback.
• Desktop language-selector entries, native/renderer translations, Storybook/E2E integration and translation-slice rebases remain outside this Core change. Core can resolve Korean from the system or explicit configuration; this PR alone does not add a Korean option to the Desktop selector.

Provenance and credit

#5011 remains the canonical reviewed source, unchanged at 6dddd3de0f9a2aee7a6121ffd0763d9a01c5ad49 (the same tree as the original reviewed 36a4377). The refreshed commit retains heeoneie's authorship, co-author credit and Generated-by: Claude Code; integration and validation record me2seeks as co-author and Generated-by: OpenAI Codex.

Refs #3975 and #5075.

Validation

Validated local head 1ddaa8bdf8eb143592bd9b44ebf0f6461e8c9acd:

• npm run build:test, npm run build and all workspace npm run typecheck checks pass, including Desktop renderer and Storybook.
• All Core and shared UI tests plus TUI catalog/fullscreen tests: 1782 passed, 0 failed, 0 skipped.
• Renderer architecture checks and their 167 tests pass against main.
• Repository lint and formatting, locale hygiene, TUI copy boundaries, Desktop/UI Knip and git diff --check pass.
• The first hosted run passed build/typechecks/static checks but exposed a Desktop test that indexed three hardcoded expectations by the now-four-locale list. Head 4b515f32bf82bb249415f6512d65cf4c4b2f6db3 fixes only that test: shipped literals remain explicit and Korean expects resolver-provided English fallback. Desktop main rebuild, all 33 bot detail tests, Biome and diff checks pass.
• Exact-head hosted CI: pending on the test repair. Local results do not establish hosted acceptance.

AI use

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Claude Code contributed the original Core implementation; OpenAI Codex contributed rebase integration, regression-test adaptation and validation. The human contributor owns submission and the final review/merge decision.

Checklist

• Tests cover Korean resolution, Core copy, Intl formatting and English fallback
• Local build, typechecks, affected tests and static checks pass
• Exact-head hosted CI passes
• Independent maintainer review

Does this PR entail a change in behavior?

• Yes — Korean becomes a resolved Core locale, with English fallback for untranslated surfaces
• No

[jackwener]

No findings in this core layer.

This exact head, a193ad8d1f5d00886ec4d182d9fd0b5a445c9c9c, is suitable only as the draft base of the atomic Korean-locale stack. It must not merge into main independently: adding ko to the closed UiLocale union intentionally makes incomplete downstream locale maps fail to compile until the remaining stack layers are present.

The implementation keeps the locale contract strict, recognizes Korean system tags without accidentally matching Konkani, maps the internal ko value to the ko-KR Intl tag, and completes the three catalogs required for @maka/core to build. I verified that this bridge commit's combined patch ID exactly matches the contributor's reviewed #5011 source range through 36a4377e66d3e2b61f722543dea73a43e8a52344; the commit also preserves the requested author, co-author, and Generated-by: Claude Code attribution.

@maka/core builds successfully, and the four affected suites pass 83/83. As a regression check, I removed Korean system-language recognition and returned an incorrect Intl tag; 11 locale assertions then failed, including the supported Korean tag matrix, language-order behavior, and Intl mapping. Biome on all eight changed files, the ASF header audit, and git diff --check also pass.

The hosted test check is red on this head. I inspected the failure: the build reaches and passes @maka/core, then stops on the expected downstream CLI maps that do not yet have a ko branch. This is the intended stack boundary, not a green merge gate. A synthetic merge with current main (ba849f404991af1f374df38a352f3ff5dc29d2ae) is textually clean and preserves this eight-file patch, but the PR should remain a draft until the complete stack is assembled and the full hosted check is green.

---

Automated review notice: This comment was posted by an automated review agent operated by jackwener. It is not an independent human review and does not replace one.

[heeoneie]

@me2seeks — this bridge has been red on Build since 2026-09-09 and I traced why. The cause is my core commit, and it is structural rather than a missing file, so I want to put the numbers and a proposal in front of you before anyone spends more time on slices.

What the CI shows, and what it hides. Run 34337991004 fails the Build step — not a test — with six TS7053: Property 'ko' does not exist errors in packages/cli. That is only where the workspace build stops first. Type-checking a193ad8d1 directly:

project	errors
packages/cli	6
apps/desktop main	177
apps/desktop renderer	156
apps/desktop storybook	185
apps/desktop preload	0

325 are TS2741 Property 'ko' is missing, 173 are TS7053, across 109 files. 63 distinct catalog files have no ko key.

Why. a193ad8d1 added ko to UI_LOCALES. UiCatalog<T> = Record<UiLocale, T>, so every catalog declared satisfies UiCatalog<T> now requires a ko key. 65 catalogs use that hard form, and nothing on this branch supplies their ko.

The consequence is a merge-order deadlock. This branch cannot be green on its own, and it cannot go green slice by slice either: it only turns green when every slice carrying a ko key has landed — #4515, #4349, #5451, #3978 and the rest. Each slice targets stack/i18n-ko-core, so each one lands on a red branch and none of them can prove it made things better. That is, I think, exactly why this has not moved in three weeks.

A fix already exists in the tree and is unused. packages/core/src/ui-locale.ts has defineUiMessageCatalog and resolveUiMessageCatalog. In that form en is required and every other locale is optional (readonly [Locale in Exclude<UiLocale, 'en'>]?: DeepPartial<Expected>), and resolveUiMessageCatalog merges each locale onto en. A catalog with no ko is then legal and resolves to English at runtime.

There is one working precedent in the repo: packages/cli/src/pi-tui-mcp-status.ts does

const MCP_STATUS_COPY = resolveUiMessageCatalog(
  defineUiMessageCatalog<TuiMcpStatusCopy>()(TUI_COPY_RESOURCES['mcp-status']),
);

Everything else still uses the hard satisfies UiCatalog<T>.

What I propose, in the order I would do it:

1. Migrate the catalogs that block the build from satisfies UiCatalog<T> to defineUiMessageCatalog + resolveUiMessageCatalog. No copy changes, no behavior change for en/zh-CN/zh-TW, and ko falls back to English until a slice fills it. The bridge goes green on its own.
2. Slices then land independently, each one replacing English fallback with real Korean in its own files, and each one provable in isolation.
3. Keep the widening of UI_LOCALES where it is — under this shape it is no longer a breaking change.

This also removes the need for something I flagged on #4515: that PR hand-writes ko blocks that are verbatim copies of en (35 Korean strings out of 3,559) purely to satisfy the type. Under the optional-locale form those stub blocks are unnecessary — roughly 3,500 lines of duplicated English that would otherwise have to be written, reviewed and later deleted.

One alternative, for completeness: revert ko from UI_LOCALES on this bridge and re-add it as the final commit once every catalog carries Korean. That keeps the type strict but blocks all slices until the last one is ready, and any slice adding a ko key early would hit excess-property errors. I do not recommend it.

Happy to do the migration in step 1 myself — it is my breakage. Tell me whether you want it on this bridge branch or as a separate PR against stack/i18n-ko-core, and whether you would rather migrate only the build-blocking catalogs or all 65 in one pass. I would start with the build-blocking set so the branch turns green in a reviewable diff.

For reference, everything above is reproducible on a193ad8d1 with npx tsc -p <project> --noEmit; I have not pushed anything.

[me2seeks]

@heeoneie — thanks for tracing the red bridge and laying out the resolver option. I accept the progressive Korean rollout and your English-fallback direction. This supersedes the 8 Sep atomic-completion rule: after the core enablement lands, Korean may be selected or follow the system while untranslated surfaces temporarily show English. Please do not add verbatim English ko blocks as placeholders.

Please prepare the catalog compatibility work as a focused PR against main before we merge this core bridge. Keeping it separate lets us validate the resolver migration with the currently shipped locales and preserves #5100 as the distinct, revertible Korean-core change you chose. Once it lands, maintainers will refresh #5100 and the stack.

For scope, use the complete required build/typecheck inventory caused by enabling ko, not just the first six CLI errors, and not an unrelated catalog rewrite. Your report shows errors across CLI, Desktop main/renderer/Storybook, and 109 files; please include the exact set needed for all required checks to pass. Keep English complete and preserve explicit key/placeholder/format coverage for zh-CN and zh-TW, so fallback cannot hide regressions in shipped languages. The Korean coverage report should continue to show which surfaces are translated and which are using English fallback. Please also keep function-valued catalog entries type-safe in the migrated shape.

This is shared integration work: you offered to address the core breakage, and maintainers will take or coordinate paths outside your core scope. The intended order is compatibility PR, #5100 as its own squash commit, then ready translation PRs one by one, each with its own squash commit. We will use the temporary stack for cross-slice visual and E2E validation.

简体中文

@heeoneie，感谢你查清红色基座的原因并提出复用解析器的方案。我接受韩语渐进式上线和英文回退方向。 这替代 9 月 8 日的“全部翻译完整后再启用”决定：核心合入后，韩语可以手动选择或跟随系统；暂未翻译的界面暂时显示英文。请不要再复制英文块作为 ko 占位。

请先把目录兼容改动作为一个聚焦 PR 合到 main，再合入核心桥接。这样可以先在现有语言下验证解析器迁移，并让 #5100 继续作为你选择的、可单独回退的韩语核心改动。该 PR 合入后，维护者会更新 #5100 和集成栈。

范围按启用 ko 后所有必需构建和类型检查实际会失败的目录确定：不只修最先出现的六个 CLI 错误，也不做无关的全仓目录重写。你的统计显示问题涉及 CLI、Desktop main/renderer/Storybook 共 109 个文件；请给出通过全部必需检查所需的精确文件清单。英文必须完整；简中、繁中的 key、占位参数及格式化完整性检查继续保留，不能让回退掩盖已有语言回归。韩语覆盖报告要能区分真实韩语和英文回退，并确保函数类目录迁移后仍有正确类型保护。

这是共同的集成工作：你提出处理核心阻塞，核心范围之外的路径由维护者接手或协调。计划顺序是兼容 PR、#5100 独立 squash、准备好的翻译 PR 逐个合入且各自 squash；临时集成栈用于跨分片界面和 E2E 验证。

[github-actions]

This pull request has had no new commits for 30 days and has been marked stale. It will be closed in 7 days unless a new commit is pushed.

Comments do not reset this timer: only a new commit does. If the pull request is intentionally long-lived, a maintainer can apply the pinned label.

[github-actions]

No description provided.