video_translate/docs/plans/2026-03-19-bilingual-ui.md

Bilingual UI Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Add Chinese and English UI support with Chinese as the default and a runtime switch button.

Architecture: App owns locale state and provides it through a lightweight translation context. UI components read localized strings from a shared dictionary and switch instantly without changing backend-facing request values.

Tech Stack: React, TypeScript, Vite, Vitest, Testing Library

---

Task 1: Add failing tests for app-level language switching

Files:

• Create: src/App.test.tsx

Step 1: Write the failing test

Add tests that verify:

• the upload screen defaults to Chinese copy
• clicking the English switch updates visible text to English

Step 2: Run test to verify it fails

Run: npm run test -- src/App.test.tsx Expected: FAIL because no locale state or switcher exists yet

Step 3: Write minimal implementation

Do not implement here; continue to later tasks.

Step 4: Run test to verify it passes

Run after Tasks 2 through 4.

Step 5: Commit

git add src/App.test.tsx src/App.tsx src/i18n.ts src/components/*.tsx
git commit -m "test: cover bilingual UI switching"

Task 2: Add translation infrastructure

Files:

• Create: src/i18n.tsx
• Modify: src/App.tsx

Step 1: Write the failing test

Covered by Task 1.

Step 2: Run test to verify it fails

Run: npm run test -- src/App.test.tsx Expected: FAIL due to missing locale provider and switch control

Step 3: Write minimal implementation

• Add locale type and translation dictionary
• Add a small React context and translation hook
• Store locale in App with zh as default
• Add a visible 中文 / English switcher

Step 4: Run test to verify it passes

Run after localized components are updated.

Step 5: Commit

git add src/i18n.tsx src/App.tsx src/App.test.tsx
git commit -m "feat: add lightweight UI locale infrastructure"

Task 3: Localize the upload flow

Files:

• Modify: src/components/UploadScreen.tsx
• Modify: src/components/TrimModal.tsx
• Modify: src/components/UploadScreen.test.tsx

Step 1: Write the failing test

Extend or add tests only if needed beyond Task 1.

Step 2: Run test to verify it fails

Run: npm run test -- src/App.test.tsx src/components/UploadScreen.test.tsx Expected: FAIL because upload copy and language labels remain English-only

Step 3: Write minimal implementation

• Localize upload-screen copy
• Localize target-language labels while preserving stable backend names
• Localize trim modal copy

Step 4: Run test to verify it passes

Run: npm run test -- src/App.test.tsx src/components/UploadScreen.test.tsx Expected: PASS

Step 5: Commit

git add src/components/UploadScreen.tsx src/components/TrimModal.tsx src/components/UploadScreen.test.tsx src/i18n.tsx
git commit -m "feat: localize upload flow"

Task 4: Localize editor and modal surfaces

Files:

• Modify: src/components/EditorScreen.tsx
• Modify: src/components/ExportModal.tsx
• Modify: src/components/VoiceMarketModal.tsx
• Modify: src/components/EditorScreen.test.tsx

Step 1: Write the failing test

Reuse the app-level switch test where possible.

Step 2: Run test to verify it fails

Run: npm run test -- src/App.test.tsx src/components/EditorScreen.test.tsx Expected: FAIL if editor or modal copy remains untranslated

Step 3: Write minimal implementation

• Localize editor copy and labels
• Localize export modal copy
• Localize voice market modal copy

Step 4: Run test to verify it passes

Run: npm run test -- src/App.test.tsx src/components/EditorScreen.test.tsx Expected: PASS

Step 5: Commit

git add src/components/EditorScreen.tsx src/components/ExportModal.tsx src/components/VoiceMarketModal.tsx src/components/EditorScreen.test.tsx src/i18n.tsx
git commit -m "feat: localize editor and modal UI"

Task 5: Verify targeted bilingual behavior

Files:

• Modify only if verification exposes gaps

Step 1: Write the failing test

Only add one if targeted verification finds a missing translation path.

Step 2: Run test to verify it fails

Only if needed.

Step 3: Write minimal implementation

Apply the smallest follow-up fix needed.

Step 4: Run test to verify it passes

Run: npm run test -- src/App.test.tsx src/components/UploadScreen.test.tsx src/components/EditorScreen.test.tsx Expected: PASS

Step 5: Commit

git add src/App.tsx src/i18n.tsx src/components/UploadScreen.tsx src/components/TrimModal.tsx src/components/EditorScreen.tsx src/components/ExportModal.tsx src/components/VoiceMarketModal.tsx
git commit -m "test: verify bilingual UI"