BACK-478 - Web-UI-i18n-support

Author: kuwork

backlog/tasks/back-478 - Web-UI-i18n-support.md

@@ -0,0 +1,124 @@
+---
+id: BACK-478
+title: Web UI i18n support
+status: Done
+assignee:
+  - Kimi
+created_date: '2026-05-16 15:20'
+updated_date: '2026-05-16 18:37'
+labels:
+  - feature
+  - web-ui
+  - i18n
+  - browser
+dependencies: []
+priority: medium
+ordinal: 7600
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Add internationalization (i18n) support to the Web UI.
+
+Currently, all user-facing text in the Web UI is hardcoded in English across ~20+ React components (Board, TaskList, Settings, Milestones, Navigation, Modal, etc.). This task extracts all hardcoded strings into a type-safe translation dictionary and allows users to switch languages via Settings.
+
+**Scope:** Web UI only. CLI and TUI are out of scope.
+**Languages:** English (`en`), Japanese (`ja`), Chinese Simplified (`zh-CN`), Chinese Traditional (`zh-TW`). Default to `en`.
+**Approach:** Zero-dependency lightweight i18n (custom React Context + hook), avoiding heavy libraries like i18next to keep the compiled binary small.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+### 1. Infrastructure
+
+Create a lightweight i18n layer under `src/web/`:
+
+```
+src/web/
+├── locales/
+│   ├── index.ts      # Locale union type, loader, and fallback logic
+│   ├── en.ts         # English dictionary (default)
+│   ├── ja.ts         # Japanese dictionary
+│   ├── zh-CN.ts      # Chinese Simplified dictionary
+│   └── zh-TW.ts      # Chinese Traditional dictionary
+├── contexts/
+│   └── I18nContext.tsx   # Provides locale state and t() function
+└── hooks/
+    └── useI18n.ts        # Hook for consuming translations
+```
+
+Requirements:
+- Full TypeScript type safety: accessing a missing key should be a compile-time error.
+- Support simple string interpolation (e.g., `t.tasks.assignedTo(name)`).
+- Compile-time embedding: import translation files as modules so they are inlined into the single-file binary by `bun build --compile`.
+
+### 2. Config Integration
+
+- Add `locale?: string` to `BacklogConfig` in `src/types/index.ts`.
+- Expose the field through the existing `/config` API (no backend changes needed if the field is passed through JSON).
+- In `Settings.tsx`, add a language selector dropdown (`English` / `日本語` / `简体中文` / `繁體中文`).
+- Default behavior: if `locale` is unset, fall back to `en` (or optionally detect `navigator.language`).
+
+### 3. Text Extraction & Replacement
+
+Systematically replace hardcoded English strings in all Web UI components. Key components to cover:
+
+- `Board.tsx` / `BoardPage.tsx` — "Kanban Board", "Loading tasks...", filter labels, swimlane titles
+- `TaskList.tsx` — column headers, empty states, search placeholder
+- `TaskCard.tsx` / `TaskColumn.tsx` — status labels, priority labels, button tooltips
+- `TaskDetailsModal.tsx` — form labels, section headers, action buttons
+- `Settings.tsx` — all setting labels, validation messages, success toasts
+- `MilestonesPage.tsx` — milestone labels, pool titles, archive section
+- `Navigation.tsx` / `SideNavigation.tsx` — nav item labels
+- `DocumentationDetail.tsx` / `DecisionDetail.tsx` — editor labels, metadata labels
+- `DraftsList.tsx` — page title, empty state
+- `Statistics.tsx` — chart labels, metric names
+- `CleanupModal.tsx` / `FilePreviewModal.tsx` / `InitializationScreen.tsx` — titles, descriptions, buttons
+- `ErrorBoundary.tsx` — error messages
+- `SuccessToast.tsx` — toast messages
+
+**Estimated translation keys:** ~300 (4 languages).
+
+### 4. Testing & Validation
+
+- Verify `bunx tsc --noEmit` passes (type-safe keys prevent typos).
+- Run `bun run check .` for formatting/linting.
+- Manual QA: switch language in Settings and verify all visible text updates without page reload.
+- Ensure fallback works when `locale` is missing or invalid.
+
+### 5. Build Verification
+
+- Confirm `bun run build` still produces a working single-file binary.
+- Confirm translation dictionaries are embedded (no runtime filesystem reads).
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+### Terminology Decisions
+- **Definition of Done** → **完成检查项** (Chinese): renamed from "完成定义" to be more intuitive for non-Agile users.
+- **poweredBy** → kept as "Powered by" in Chinese (Traditional) to match common UI conventions.
+
+### Challenges
+- **C disk space (ENOSPC)**: `bun build --compile` requires large temp space. Resolved by clearing `%TEMP%` and old `dist/` builds before compiling.
+- **Locale persistence**: `locale` field is stored in `BacklogConfig` and serialized to `backlog.config.yml` via `parseConfig`/`serializeConfig`.
+- **Settings page i18n lag**: initially only the language selector was i18n'd; all remaining hardcoded labels (project name, port, editor, DoD, etc.) were converted in a follow-up pass.
+- **Wiki detail page parity**: `Cancel`/`Edit` buttons and placeholder text were aligned to use the same `t.common.*` keys as the document detail page.
+
+### Components Fully Internationalized
+Board, TaskList, TaskDetailsModal, TaskCard, TaskColumn, SideNavigation, Navigation, Settings, Statistics, CleanupModal, InitializationScreen, MilestonesPage, DraftsList, WikiDetail, DocumentationDetail, DecisionDetail, Modal, Toast, ErrorBoundary, HealthIndicator, LabelFilter, AcceptanceCriteria, DependencyInput, FilePreview, PasteAwareMDEditor, MermaidMarkdown.
+<!-- DOD:END -->
+<!-- SECTION:NOTES:END -->
+
+## Definition of Done
+
+<!-- DOD:BEGIN -->
+- [x] #1 Lightweight i18n infrastructure exists (`locales/`, `I18nContext`, `useI18n`) with full TS type safety
+- [x] #2 `BacklogConfig` includes optional `locale` field; Settings page has language selector
+- [x] #3 All user-facing text in `src/web/components/` is extracted into translation dictionaries
+- [x] #4 Default language is English; Japanese, Simplified Chinese and Traditional Chinese are selectable and fully translated
+- [x] #5 `bunx tsc --noEmit` passes
+- [x] #6 `bun run check .` passes
+- [x] #7 `bun run build` produces a working binary with embedded translations

src/core/backlog.ts

@@ -53,12 +53,12 @@ import { getTaskFilename, getTaskPath, normalizeTaskId, taskIdsEqual } from "../
 import { attachSubtaskSummaries } from "../utils/task-subtasks.ts";
 import { upsertTaskUpdatedDate } from "../utils/task-updated-date.ts";
 import { isTerminalStatus } from "../utils/terminal-status.ts";
+import { AssetManager } from "./assets.ts";
 import { migrateConfig, needsMigration } from "./config-migration.ts";
 import { ContentStore } from "./content-store.ts";
 import { migrateDraftPrefixes, needsDraftPrefixMigration } from "./prefix-migration.ts";
 import { calculateNewOrdinal, DEFAULT_ORDINAL_STEP, resolveOrdinalConflicts } from "./reorder.ts";
 import { SearchService } from "./search-service.ts";
-import { AssetManager } from "./assets.ts";
 import { computeSequences, planMoveToSequence, planMoveToUnsequenced } from "./sequences.ts";
 import {
 	type BranchTaskStateEntry,

src/file-system/operations.ts

@@ -1430,6 +1430,9 @@ ${description || `Milestone: ${title}`}`,
 				case "backlogDirectory":
 					config.backlogDirectory = value.replace(/['"]/g, "");
 					break;
+				case "locale":
+					config.locale = value.replace(/['"]/g, "");
+					break;
 			}
 		}
 
@@ -1456,6 +1459,7 @@ ${description || `Milestone: ${title}`}`,
 			onStatusChange: config.onStatusChange,
 			prefixes: config.prefixes,
 			backlogDirectory: config.backlogDirectory,
+			locale: config.locale,
 		};
 	}
 
@@ -1488,6 +1492,7 @@ ${description || `Milestone: ${title}`}`,
 			...(config.onStatusChange ? [`onStatusChange: '${config.onStatusChange}'`] : []),
 			...(config.prefixes?.task ? [`task_prefix: "${config.prefixes.task}"`] : []),
 			...(config.backlogDirectory ? [`backlog_directory: "${config.backlogDirectory}"`] : []),
+			...(config.locale ? [`locale: "${config.locale}"`] : []),
 		];
 
 		return `${lines.join("\n")}\n`;

src/test/assets.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it, beforeEach, afterEach } from "bun:test";
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
 import { mkdir, utimes } from "node:fs/promises";
 import { join } from "node:path";
 import { AssetManager } from "../core/assets.ts";
@@ -8,7 +8,6 @@ let TEST_DIR: string;
 let assetsRoot: string;
 let manager: AssetManager;
 
-
 describe("AssetManager", () => {
 	beforeEach(async () => {
 		TEST_DIR = createUniqueTestDir("assets");

src/types/index.ts

@@ -309,6 +309,7 @@ export interface BacklogConfig {
 	defaultEditor?: string;
 	autoOpenBrowser?: boolean;
 	defaultPort?: number;
+	locale?: string;
 	remoteOperations?: boolean;
 	autoCommit?: boolean;
 	/** Disable all Git integration for filesystem-only projects. */

src/web/App.tsx

@@ -28,6 +28,8 @@ import {
 } from '../types';
 import { apiClient } from './lib/api';
 import { useHealthCheckContext } from './contexts/HealthCheckContext';
+import { useI18nContext } from './contexts/I18nContext';
+import { isValidLocale } from './locales';
 import { getWebVersion } from './utils/version';
 import { collectArchivedMilestoneKeys, collectMilestoneIds, milestoneKey } from './utils/milestones';
 
@@ -187,6 +189,7 @@ function App() {
   const [isLoading, setIsLoading] = useState(true);
 
   const { isOnline } = useHealthCheckContext();
+  const { setLocale } = useI18nContext();
   const previousOnlineRef = useRef<boolean | null>(null);
   const hasBeenRunningRef = useRef(false);
 
@@ -283,6 +286,9 @@ function App() {
       setProjectName(configData.projectName);
       setAvailableLabels(configData.labels || []);
       setConfig(configData);
+      if (configData.locale && isValidLocale(configData.locale)) {
+        setLocale(configData.locale);
+      }
       setMilestoneEntities(milestonesData);
       setArchivedMilestones(archivedMilestonesData);
       setMilestones(

src/web/components/AcceptanceCriteriaEditor.tsx

@@ -1,5 +1,6 @@
 import React, { useEffect, useRef, useState } from "react";
 import { type AcceptanceCriterion } from "../../types";
+import { useI18n } from '../hooks/useI18n';
 
 interface Props {
   criteria: AcceptanceCriterion[];
@@ -12,12 +13,13 @@ interface Props {
 const AcceptanceCriteriaEditor: React.FC<Props> = ({
   criteria: initial,
   onChange,
-  label = "Acceptance Criteria",
+  label,
   preserveIndices = false,
   disableToggle = false,
 }) => {
   const [criteria, setCriteria] = useState<AcceptanceCriterion[]>(initial || []);
   const [newCriterion, setNewCriterion] = useState("");
+  const { t } = useI18n();
 
   // Refs to auto-resize textareas
   const itemRefs = useRef<Record<number, HTMLTextAreaElement | null>>({});
@@ -79,7 +81,7 @@ const AcceptanceCriteriaEditor: React.FC<Props> = ({
   return (
     <div className="space-y-2">
       <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1 transition-colors duration-200">
-        {label}
+        {label ?? t.acceptanceCriteria.label}
       </label>
       <ul className="space-y-2">
         {criteria.map((c) => (
@@ -104,7 +106,7 @@ const AcceptanceCriteriaEditor: React.FC<Props> = ({
               onClick={() => handleRemove(c.index)}
               className="px-2 py-1 text-sm text-red-600 dark:text-red-400 hover:underline"
             >
-              Remove
+              {t.common.remove}
             </button>
           </li>
         ))}
@@ -115,15 +117,15 @@ const AcceptanceCriteriaEditor: React.FC<Props> = ({
             value={newCriterion}
             onChange={(e) => setNewCriterion(e.target.value)}
             onInput={(e) => autoResize(e.currentTarget)}
-            placeholder="New criterion"
+            placeholder={t.acceptanceCriteria.placeholder}
             className="flex-1 px-2 py-1 text-sm border border-gray-300 dark:border-gray-600 rounded-md bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100 focus:outline-none focus:ring-2 focus:ring-stone-500 dark:focus:ring-stone-400 focus:border-transparent transition-colors duration-200 resize-none overflow-hidden leading-5"
           />
           <button
             type="button"
             onClick={handleAdd}
             className="px-2 py-1 text-sm bg-blue-500 dark:bg-blue-600 text-white rounded-md hover:bg-blue-600 dark:hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 dark:focus:ring-offset-gray-800 focus:ring-blue-400 dark:focus:ring-blue-500 transition-colors duration-200"
           >
-            Add
+            {t.common.add}
           </button>
         </li>
       </ul>