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

Bilingual UI Design

Goal: Make the application UI available in both Chinese and English, defaulting to Chinese and allowing users to switch languages with a button.

Context

The current application UI is written almost entirely in English across the upload screen, trim modal, editor, export modal, and voice market modal. The user wants the product to support both Chinese and English and to switch between them at runtime with a visible button.

The requested behavior is UI-only internationalization. It should not change the underlying subtitle generation workflow, target-language request payloads, or model/provider behavior.

Approaches Considered

Option A: Prop-based translations

Store the current locale in App and pass translated strings into every component via props.

Pros

• Very explicit data flow
• No new React context

Cons

• High prop churn across many components
• Harder to maintain as UI grows

Option B: Lightweight local i18n context

Create a small translation module and a React context that exposes:

• current locale
• locale setter
• translation lookup helper

Components read strings through a shared hook.

Pros

• Small implementation footprint
• Easy to scale across the existing component tree
• Avoids adding a third-party i18n library for a two-language UI

Cons

• Requires a small amount of context plumbing

Recommendation

Use Option B. It keeps the implementation simple while making future UI expansion much easier.

Architecture

Locale State

App will own the current locale with these rules:

• supported locales: zh, en
• default locale: zh

App will wrap the UI in a small provider that exposes locale state and a t(...) helper.

Translation Dictionary

Create a single front-end translation dictionary that covers current user-visible strings for:

• upload screen
• trim modal
• editor
• export modal
• voice market modal

The dictionary should use stable keys rather than raw string matching.

Language Switcher

Add a compact switcher button group in the app shell so the user can toggle:

• 中文
• English

The active locale should be visually highlighted.

Language List Rendering

The upload screen's target-language options should display localized labels while still preserving a stable English request value for the backend. This avoids accidentally changing API behavior when the UI language changes.

Each supported target language entry should therefore include:

• code
• backend display name or canonical request name
• Chinese label
• English label

Scope

Included

• Front-end UI copy
• Language switch button
• Localized supported-language labels in the upload screen
• Chinese default locale

Excluded

• Backend message localization
• API error localization from third-party providers
• Browser-language auto-detection
• Persistence across refreshes

Testing Strategy

Add tests that verify:

• the app defaults to Chinese
• clicking the language switch updates visible UI labels to English
• upload-screen language options render localized names correctly
• existing component behavior continues to work while localized

Rollout Notes

This design intentionally uses a local translation system instead of a third-party i18n package. That keeps the change fast, understandable, and easy to refactor later if the app grows into a larger multilingual product.