feat(i18n): add Traditional Chinese locale

.github/workflows/zh-tw-locale-screenshots.yml

@@ -0,0 +1,37 @@
+name: Traditional Chinese locale screenshots
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  screenshots:
+    runs-on: macos-15
+    timeout-minutes: 45
+    steps:
+      - name: Check out pull request
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.19.0
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Capture locale screenshots
+        run: npm --workspace @maka/desktop run e2e -- e2e/zh-tw-locale-screenshots.spec.ts --workers=1
+
+      - name: Upload locale screenshots
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: zh-tw-locale-screenshots
+          path: apps/desktop/test-results/**/zh-tw-locale/*.png
+          if-no-files-found: warn

apps/desktop/.storybook/preview.tsx

@@ -38,7 +38,12 @@ const withMakaRoot: Decorator = (Story, context) => {
   // lines are ~1.8× the width of the Chinese copy, so a row that fits in zh
   // overflows, truncates, or clips in en. Stories were locked to `zh`, which
   // is exactly why those breakages only ever showed up in the shipped app.
-  const locale = context.globals.locale === 'en' ? 'en' : 'zh';
+  const locale =
+    context.globals.locale === 'en'
+      ? 'en'
+      : context.globals.locale === 'zh-TW'
+        ? 'zh-TW'
+        : 'zh-CN';
 
   root.classList.toggle('dark', colorScheme === 'dark');
   root.style.colorScheme = colorScheme;
@@ -96,7 +101,8 @@ const preview: Preview = {
       toolbar: {
         icon: 'globe',
         items: [
-          { title: '中文', value: 'zh' },
+          { title: '简体中文', value: 'zh-CN' },
+          { title: '繁體中文', value: 'zh-TW' },
           { title: 'English', value: 'en' },
         ],
       },
@@ -114,7 +120,7 @@ const preview: Preview = {
   },
   initialGlobals: {
     colorScheme: 'light',
-    locale: 'zh',
+    locale: 'zh-CN',
     palette: 'default',
   },
   parameters: {

apps/desktop/e2e/accessibility-coverage.spec.ts

@@ -48,7 +48,7 @@ test('every settings page exposes named actionable controls', async ({ window: p
   const sectionLabels = (await navigation.getByRole('button').allTextContents())
     .map((label) => label.trim().replace(/\s*Beta$/, ''))
     .filter((label) => label.length > 0 && label !== '返回应用');
-  const expectedSectionLabels = groupedNav('zh')
+  const expectedSectionLabels = groupedNav('zh-CN')
     .flatMap(({ items }) => items)
     .filter(({ enabled }) => enabled)
     .map(({ label }) => label);

apps/desktop/e2e/fixtures.ts

@@ -141,7 +141,7 @@ async function seedE2eConnection(userDataDir: string): Promise<void> {
   }
 }
 
-async function seedE2eLocale(userDataDir: string, locale: 'zh' | 'en'): Promise<void> {
+async function seedE2eLocale(userDataDir: string, locale: 'zh-CN' | 'zh-TW' | 'en'): Promise<void> {
   const workspaceRoot = path.join(userDataDir, 'workspaces', 'default');
   await createSettingsStore(workspaceRoot).update({
     personalization: { uiLocale: locale },
@@ -342,7 +342,7 @@ async function withE2eWindow(
     seed: boolean;
     readinessSelector: string;
     e2eFixtureScenario?: string;
-    locale?: 'zh' | 'en';
+    locale?: 'zh-CN' | 'zh-TW' | 'en';
     /** Opt this window back into animated scrolling; see `scroll-motion-policy`. */
     scrollMotion?: 'auto' | 'smooth';
     /** #1312: force app:info's platform so the window boots natively into that platform's `data-os` cascade. */
@@ -445,13 +445,13 @@ export const test = base.extend<{
 }>({
   // Seeded: a pre-staged connection clears onboarding so the composer is ready.
   window: async ({}, use) => {
-    await withE2eWindow({ seed: true, readinessSelector: COMPOSER_INPUT, locale: 'zh' }, use);
+    await withE2eWindow({ seed: true, readinessSelector: COMPOSER_INPUT, locale: 'zh-CN' }, use);
   },
   onboardingWindow: async ({}, use) => {
     await withE2eWindow({
       seed: false,
       readinessSelector: '[data-maka-contract="onboarding-card"]',
-      locale: 'zh',
+      locale: 'zh-CN',
       showWindow: true,
     }, use);
   },
@@ -460,7 +460,7 @@ export const test = base.extend<{
       {
         seed: true,
         readinessSelector: COMPOSER_INPUT,
-        locale: 'zh',
+        locale: 'zh-CN',
         gitReviewExtraFiles: 0,
       },
       async (page, context) => {
@@ -476,7 +476,7 @@ export const test = base.extend<{
     await withE2eWindow({
       seed: true,
       readinessSelector: COMPOSER_INPUT,
-      locale: 'zh',
+      locale: 'zh-CN',
       invocableSkills: true,
     }, use);
   },
@@ -495,7 +495,7 @@ export const test = base.extend<{
     await withE2eWindow({
       seed: true,
       readinessSelector: COMPOSER_INPUT,
-      locale: 'zh',
+      locale: 'zh-CN',
       newTaskProject: true,
       showWindow: true,
     }, use);
@@ -505,7 +505,7 @@ export const test = base.extend<{
       seed: false,
       readinessSelector: '[data-maka-contract="search-modal"][open]',
       e2eFixtureScenario: 'sidebar-search-modal-open',
-      locale: 'zh',
+      locale: 'zh-CN',
       showWindow: true,
     }, use);
   },
@@ -514,7 +514,7 @@ export const test = base.extend<{
       {
         seed: true,
         readinessSelector: COMPOSER_INPUT,
-        locale: 'zh',
+        locale: 'zh-CN',
         parentRemovalSessions: true,
       },
       use,
@@ -556,7 +556,7 @@ export const test = base.extend<{
       seed: false,
       readinessSelector: '.settingsSurface',
       e2eFixtureScenario: 'settings-models',
-      locale: 'zh',
+      locale: 'zh-CN',
       showWindow: true,
     }, use);
   },

apps/desktop/e2e/request-header-row-contract.spec.ts

@@ -37,7 +37,7 @@ import { getProviderSettingsCopy } from '../src/renderer/locales/settings-provid
  * surfaces as they first render, and this editor is three clicks deep.
  */
 
-const copy = getProviderSettingsCopy('zh').detail;
+const copy = getProviderSettingsCopy('zh-CN').detail;
 
 test('the request header remove button centres on its field', async ({
   requestHeaderRowWindow: page,

apps/desktop/e2e/zh-tw-locale-screenshots.spec.ts

@@ -0,0 +1,47 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { test, expect } from './fixtures';
+
+test('captures General Settings in Simplified and Traditional Chinese', async ({
+  window: page,
+}, testInfo) => {
+  const outputDirectory = path.join(testInfo.outputDir, 'zh-tw-locale');
+  await mkdir(outputDirectory, { recursive: true });
+
+  await page.getByRole('button', { name: '设置', exact: true }).click();
+  await expect(page.getByRole('main', { name: '设置内容' })).toBeVisible();
+  await page.getByRole('button', { name: '通用', exact: true }).click();
+  await expect(page.getByText('界面语言', { exact: true }).first()).toBeVisible();
+  await page.screenshot({ path: path.join(outputDirectory, 'settings-zh-CN.png'), fullPage: true });
+  await page.keyboard.press('Escape');
+
+  await page.evaluate(async () => {
+    await window.maka.settings.update({ personalization: { uiLocale: 'zh-TW' } });
+  });
+  await page.reload();
+  await page.waitForSelector('.maka-composer-editor');
+  await page.getByRole('button', { name: '設定', exact: true }).click();
+  await expect(page.getByRole('main', { name: '設定內容' })).toBeVisible();
+  await page.getByRole('button', { name: '通用', exact: true }).click();
+  await expect(page.getByText('介面語言', { exact: true }).first()).toBeVisible();
+  await page.screenshot({ path: path.join(outputDirectory, 'settings-zh-TW.png'), fullPage: true });
+});

apps/desktop/src/main/__tests__/active-execution-boundary-read-model.test.ts

@@ -286,7 +286,7 @@ describe('Boundary decisions notify the read model', () => {
   function handlersWithRecorder() {
     const boundaryChanges: string[] = [];
     const handlers = createAppShellSessionEventHandlers({
-      uiLocale: 'zh',
+      uiLocale: 'zh-CN',
       activeIdRef: { current: 'session-a' },
       liveTurnBySessionRef: { current: {} },
       refreshMessages: async () => true,

apps/desktop/src/main/__tests__/agent-graph-panel-copy.test.ts

@@ -0,0 +1,30 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { getAgentGraphPanelCopy } from '../../renderer/agent-graph-panel.js';
+
+test('Traditional Chinese Agent Graph copy does not use Simplified fallbacks', () => {
+  const copy = getAgentGraphPanelCopy('zh-TW');
+  assert.equal(copy.loading, '正在讀取 Graph 狀態…');
+  assert.equal(copy.openSession, '開啟子任務');
+  assert.equal(copy.currentEpoch, '目前');
+  assert.equal(copy.status('active'), '執行中');
+});

apps/desktop/src/main/__tests__/app-shell-session-settings-actions.test.ts

@@ -102,7 +102,7 @@ function createHarness(options: {
   });
 
   const actions = createAppShellSessionSettingsActions({
-    uiLocale: 'zh',
+    uiLocale: 'zh-CN',
     activeIdRef,
     connections: options.connections ?? ([{ slug: 'e2e', name: 'E2E' }] as LlmConnection[]),
     messages: options.messages ?? [],

apps/desktop/src/main/__tests__/computer-use-status-item-locale.test.ts

@@ -50,7 +50,7 @@ test('rebuilds an active Computer Use menu when its resolved locale changes', ()
   assert.deepEqual(menus.at(-1)?.map((row) => row.label), ['Stop Using Safari']);
 
   locale.observe(mergeSettings(createDefaultSettings(), {
-    personalization: { uiLocale: 'zh' },
+    personalization: { uiLocale: 'zh-CN' },
   }));
   assert.deepEqual(menus.at(-1)?.map((row) => row.label), ['停止操作 Safari']);
 

apps/desktop/src/main/__tests__/config-transfer-service.test.ts

@@ -100,6 +100,27 @@ describe('config-transfer-service', () => {
     assert.deepEqual(writtenMemory, ['# imported memory']);
   });
 
+  it('canonicalizes a legacy zh preference before the imported settings reach observers', async () => {
+    const { deps, updatedSettings } = makeDeps();
+    const bundle = {
+      schemaVersion: 1,
+      exportedAt: '',
+      appVersion: '0.1.0',
+      includedData: ['settings'] as const,
+      data: {
+        settings: {
+          personalization: { uiLocale: 'zh', displayName: 'Maka user' },
+        },
+      },
+    };
+
+    await applyConfigImport(bundle as any, 'skip', deps);
+
+    assert.deepEqual(updatedSettings, [
+      { personalization: { uiLocale: 'zh-CN', displayName: 'Maka user' } },
+    ]);
+  });
+
   it('restores the selection a backup states instead of re-enabling its default', async () => {
     // A backup can hold a connection whose default model the user had disabled.
     // `save()` cannot tell a stated selection from one a sync echoed back, so it

apps/desktop/src/main/__tests__/desktop-locale-authority.test.ts

@@ -24,15 +24,15 @@ import { createDesktopLocaleAuthority } from '../desktop-locale-authority.js';
 
 test('resolves explicit preferences and observes a mid-session settings change', async () => {
   let settings = mergeSettings(createDefaultSettings(), {
-    personalization: { uiLocale: 'zh' },
+    personalization: { uiLocale: 'zh-CN' },
   });
   const authority = createDesktopLocaleAuthority({
     readSettings: async () => settings,
     preferredSystemLanguages: () => ['en-US'],
   });
 
-  assert.equal(await authority.resolve(), 'zh');
-  assert.equal(authority.current(), 'zh');
+  assert.equal(await authority.resolve(), 'zh-CN');
+  assert.equal(authority.current(), 'zh-CN');
   settings = mergeSettings(settings, { personalization: { uiLocale: 'en' } });
   authority.observe(settings);
   assert.equal(authority.current(), 'en');
@@ -50,14 +50,14 @@ test('publishes only resolved-locale changes and allows listeners to detach', ()
     personalization: { uiLocale: 'en' },
   }));
   authority.observe(mergeSettings(createDefaultSettings(), {
-    personalization: { uiLocale: 'zh' },
+    personalization: { uiLocale: 'zh-CN' },
   }));
   unsubscribe();
   authority.observe(mergeSettings(createDefaultSettings(), {
     personalization: { uiLocale: 'en' },
   }));
 
-  assert.deepEqual(observed, ['zh']);
+  assert.deepEqual(observed, ['zh-CN']);
 });
 
 test('keeps automatic preference live against the current system fallback', async () => {
@@ -68,8 +68,10 @@ test('keeps automatic preference live against the current system fallback', asyn
   });
 
   assert.equal(await authority.resolve(), 'en');
+  languages = ['zh-TW'];
+  assert.equal(authority.current(), 'zh-TW');
   languages = ['zh-CN'];
-  assert.equal(authority.current(), 'zh');
+  assert.equal(authority.current(), 'zh-CN');
 });
 
 test('does not let a stale read replace a newer observed preference', async () => {
@@ -86,19 +88,34 @@ test('does not let a stale read replace a newer observed preference', async () =
 
   const read = authority.resolve();
   authority.observe(mergeSettings(createDefaultSettings(), {
-    personalization: { uiLocale: 'zh' },
+    personalization: { uiLocale: 'zh-CN' },
   }));
   release(createDefaultSettings());
 
-  assert.equal(await read, 'zh');
-  assert.equal(authority.current(), 'zh');
-  assert.deepEqual(observed, ['zh']);
+  assert.equal(await read, 'zh-CN');
+  assert.equal(authority.current(), 'zh-CN');
+  assert.deepEqual(observed, ['zh-CN']);
 });
 
 test('falls back to its current projection when settings cannot be read', async () => {
   const authority = createDesktopLocaleAuthority({
     readSettings: async () => { throw new Error('unreadable'); },
     preferredSystemLanguages: () => ['zh-CN'],
   });
-  assert.equal(await authority.resolve(), 'zh');
+  assert.equal(await authority.resolve(), 'zh-CN');
+});
+
+test('never projects the legacy zh preference into native copy lookups', async () => {
+  const legacy = mergeSettings(createDefaultSettings(), {
+    personalization: { uiLocale: 'zh-CN' },
+  });
+  (legacy.personalization as { uiLocale: string }).uiLocale = 'zh';
+  const authority = createDesktopLocaleAuthority({
+    readSettings: async () => legacy,
+    preferredSystemLanguages: () => ['en-US'],
+  });
+
+  assert.equal(authority.observe(legacy), 'zh-CN');
+  assert.equal(authority.current(), 'zh-CN');
+  assert.equal(await authority.resolve(), 'zh-CN');
 });