Add web i18n scaffolding and locale-aware timestamps

- Add message catalogs and locale resolution for app settings
- Wire the root provider and update chat/diff timestamp formatting
- Add guardrail tests for locale resolution and catalog parity

Author: BunsDev

.plans/web-i18n-rollout.md

@@ -0,0 +1,196 @@
+# Web i18n Rollout Tracker
+
+_Last updated: 2026-03-31_
+
+This document tracks the phased rollout of multilingual support for `apps/web`.
+
+Supported locales:
+
+- `en`
+- `es`
+- `fr`
+- `zh-CN`
+
+Status values:
+
+- `TODO`: Not started
+- `IN_PROGRESS`: Started but not yet shippable
+- `DONE`: Implemented and verified
+- `BLOCKED`: Waiting on a dependency or decision
+
+## Scope
+
+In scope for this rollout:
+
+- frontend-only localization in `apps/web`
+- product-owned UI strings only
+- locale persistence via app settings
+- locale-aware timestamps
+- root screens, settings, onboarding, and mobile pairing in the first shippable stop
+
+Out of scope for this rollout:
+
+- `apps/server`
+- `apps/marketing`
+- user/model/code content translation
+- arbitrary provider/server freeform error translation
+
+## Current Snapshot
+
+Overall status: `IN_PROGRESS`
+
+Completed so far:
+
+- Added `react-intl` to `apps/web`
+- Added locale schema support to `apps/web/src/appSettings.ts`
+- Added the shared i18n scaffolding under `apps/web/src/i18n/`
+- Added initial message catalogs for `en`, `es`, `fr`, and `zh-CN`
+- Wired the root route through a shared `I18nProvider`
+- Made timestamps honor the resolved app locale
+- Updated the timestamp callsites in chat and diff surfaces
+- Added Phase 1 guardrail tests for locale resolution, timestamp formatting, and catalog parity
+- `apps/web` tests pass
+- `bun fmt` passed
+- `bun lint` passed
+
+Not yet completed:
+
+- Settings page migration
+- Onboarding migration
+- Mobile pairing migration
+- Repo-wide `bun typecheck` currently fails in `apps/server` on unrelated Effect/FileSystem context issues
+
+## Phase 1 — Infrastructure
+
+Objective:
+Establish the shared localization foundation without coupling it to the server or user content.
+
+Checklist:
+
+- [x] Add `react-intl` to `apps/web`
+  - Status: `DONE`
+- [x] Add persisted locale preference to `apps/web/src/appSettings.ts`
+  - Status: `DONE`
+- [x] Add shared i18n module in `apps/web/src/i18n/`
+  - Status: `DONE`
+- [x] Add message catalogs for `en`, `es`, `fr`, and `zh-CN`
+  - Status: `DONE`
+- [ ] Wire `I18nProvider` into [apps/web/src/routes/__root.tsx](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/routes/__root.tsx)
+  - Status: `DONE`
+- [ ] Expose stable translation helpers for component usage
+  - Status: `DONE`
+- [ ] Add locale-aware timestamp formatting in [apps/web/src/timestampFormat.ts](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/timestampFormat.ts)
+  - Status: `DONE`
+- [ ] Update timestamp callsites in [apps/web/src/components/chat/MessagesTimeline.tsx](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/components/chat/MessagesTimeline.tsx)
+  - Status: `DONE`
+- [ ] Update timestamp callsites in [apps/web/src/components/DiffPanel.tsx](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/components/DiffPanel.tsx)
+  - Status: `DONE`
+
+Exit criteria:
+
+- Locale can be resolved at runtime from `system | en | es | fr | zh-CN`
+- The app can render under a single root i18n provider
+- Timestamp formatting can follow the selected app locale
+
+## Phase 2 — First Shippable Surfaces
+
+Objective:
+Ship a coherent multilingual slice that is complete on the highest-value product-owned surfaces.
+
+Checklist:
+
+- [ ] Migrate root route loading/error copy in [apps/web/src/routes/__root.tsx](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/routes/__root.tsx)
+  - Status: `TODO`
+- [ ] Migrate root keybinding toasts in [apps/web/src/routes/__root.tsx](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/routes/__root.tsx)
+  - Status: `TODO`
+- [ ] Add language selector to [apps/web/src/routes/_chat.settings.tsx](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/routes/_chat.settings.tsx)
+  - Status: `TODO`
+- [ ] Migrate product-owned settings copy in [apps/web/src/routes/_chat.settings.tsx](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/routes/_chat.settings.tsx)
+  - Status: `TODO`
+- [ ] Migrate supporting settings components in [apps/web/src/components/EnvironmentVariablesEditor.tsx](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/components/EnvironmentVariablesEditor.tsx)
+  - Status: `TODO`
+- [ ] Migrate supporting settings components in [apps/web/src/components/CustomThemeDialog.tsx](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/components/CustomThemeDialog.tsx)
+  - Status: `TODO`
+- [ ] Migrate onboarding content in [apps/web/src/components/onboarding/onboardingSteps.ts](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/components/onboarding/onboardingSteps.ts)
+  - Status: `TODO`
+- [ ] Migrate onboarding controls in [apps/web/src/components/onboarding/OnboardingDialog.tsx](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/components/onboarding/OnboardingDialog.tsx)
+  - Status: `TODO`
+- [ ] Migrate mobile pairing UI in [apps/web/src/components/mobile/MobilePairingScreen.tsx](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/components/mobile/MobilePairingScreen.tsx)
+  - Status: `TODO`
+
+Exit criteria:
+
+- Users can select a language in Settings without reloading
+- Root screens, Settings, Onboarding, and Mobile Pairing render localized product UI
+- English remains the safe fallback when a locale cannot be resolved or loaded
+
+## Phase 3 — High-Traffic Product Surfaces
+
+Objective:
+Extend localization to the most visible remaining chrome and toast-heavy flows.
+
+Checklist:
+
+- [ ] Migrate sidebar toasts and chrome in [apps/web/src/components/Sidebar.tsx](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/components/Sidebar.tsx)
+  - Status: `TODO`
+- [ ] Migrate chat home empty state in [apps/web/src/components/ChatHomeEmptyState.tsx](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/components/ChatHomeEmptyState.tsx)
+  - Status: `TODO`
+- [ ] Migrate workspace file tree messages in [apps/web/src/components/WorkspaceFileTree.tsx](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/components/WorkspaceFileTree.tsx)
+  - Status: `TODO`
+- [ ] Migrate Git actions UI copy in [apps/web/src/components/GitActionsControl.tsx](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/components/GitActionsControl.tsx)
+  - Status: `TODO`
+- [ ] Migrate branch selector copy in [apps/web/src/components/BranchToolbarBranchSelector.tsx](/Users/buns/.okcode/worktrees/okcode/okcode-587a5d98/apps/web/src/components/BranchToolbarBranchSelector.tsx)
+  - Status: `TODO`
+
+Exit criteria:
+
+- The highest-traffic app chrome and common toasts are localized
+- Remaining untranslated product UI is narrow and intentional
+
+## Phase 4 — Hardening and Verification
+
+Objective:
+Make the rollout safe to maintain and safe to ship repeatedly.
+
+Checklist:
+
+- [ ] Add locale resolution tests
+  - Status: `DONE`
+- [ ] Add app settings default tests for locale
+  - Status: `DONE`
+- [ ] Add message catalog parity tests
+  - Status: `DONE`
+- [ ] Add timestamp formatting tests
+  - Status: `DONE`
+- [ ] Run `bun fmt`
+  - Status: `DONE`
+- [ ] Run `bun lint`
+  - Status: `DONE`
+- [ ] Run `bun typecheck`
+  - Status: `BLOCKED`
+
+Exit criteria:
+
+- Catalog drift is caught by tests
+- Locale behavior is covered by automated checks
+- Required repository quality gates pass
+
+## Shippable Stop
+
+The first shippable stop is:
+
+- Phase 1 complete
+- Phase 2 complete
+- Phase 4 verification complete
+
+Phase 3 can follow later without blocking the first release if the app’s core localized surfaces are already coherent.
+
+## Next Up
+
+Immediate next implementation steps:
+
+1. Resolve the unrelated `apps/server` typecheck failures so repo-wide verification can pass again.
+2. Migrate root route strings and root toasts.
+3. Migrate Settings and its supporting components.
+4. Migrate Onboarding and Mobile Pairing.
+5. Continue with Phase 2 completion toward the first shippable localized stop.

apps/web/src/appSettings.test.ts

@@ -5,6 +5,7 @@ import {
   AppSettingsSchema,
   DEFAULT_SIDEBAR_PROJECT_SORT_ORDER,
   DEFAULT_SIDEBAR_THREAD_SORT_ORDER,
+  DEFAULT_APP_LOCALE,
   DEFAULT_TIMESTAMP_FORMAT,
   getAppModelOptions,
   getCustomModelOptionsByProvider,
@@ -258,6 +259,7 @@ describe("AppSettingsSchema", () => {
       defaultThreadEnvMode: "worktree",
       confirmThreadDelete: false,
       enableAssistantStreaming: false,
+      locale: DEFAULT_APP_LOCALE,
       sidebarProjectSortOrder: DEFAULT_SIDEBAR_PROJECT_SORT_ORDER,
       sidebarThreadSortOrder: DEFAULT_SIDEBAR_THREAD_SORT_ORDER,
       timestampFormat: DEFAULT_TIMESTAMP_FORMAT,

apps/web/src/components/DiffPanel.tsx

@@ -21,6 +21,7 @@ import {
 } from "../lib/diffFileReviewState";
 import { resolveDiffThemeName } from "../lib/diffRendering";
 import { useTurnDiffSummaries } from "../hooks/useTurnDiffSummaries";
+import { useI18n } from "../i18n/useI18n";
 import { useStore } from "../store";
 import { useAppSettings } from "../appSettings";
 import { formatShortTimestamp } from "../timestampFormat";
@@ -268,6 +269,7 @@ export { DiffWorkerPoolProvider } from "./DiffWorkerPoolProvider";
 export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
   const navigate = useNavigate();
   const { resolvedTheme } = useTheme();
+  const { resolvedLocale } = useI18n();
   const { settings } = useAppSettings();
   const [diffRenderMode, setDiffRenderMode] = useState<DiffRenderMode>("stacked");
   const [diffWordWrap, setDiffWordWrap] = useState(settings.diffWordWrap);
@@ -554,14 +556,26 @@ export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
             {selectedTurnId === null
               ? "All changes"
               : selectedTurn?.turnId === latestSelectedTurnId
-                ? `Latest • ${formatShortTimestamp(selectedTurn.completedAt, settings.timestampFormat)}`
+                ? `Latest • ${formatShortTimestamp(
+                    selectedTurn.completedAt,
+                    settings.timestampFormat,
+                    resolvedLocale,
+                  )}`
                 : `Change ${
                     selectedTurn?.checkpointTurnCount ??
                     (selectedTurn
                       ? inferredCheckpointTurnCountByTurnId[selectedTurn.turnId]
                       : null) ??
                     "?"
-                  } • ${selectedTurn ? formatShortTimestamp(selectedTurn.completedAt, settings.timestampFormat) : ""}`}
+                  } • ${
+                    selectedTurn
+                      ? formatShortTimestamp(
+                          selectedTurn.completedAt,
+                          settings.timestampFormat,
+                          resolvedLocale,
+                        )
+                      : ""
+                  }`}
           </SelectButton>
           <SelectPopup>
             <SelectItem value="all">All changes</SelectItem>
@@ -578,7 +592,11 @@ export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
                         }`}
                   </span>
                   <span className="text-muted-foreground text-xs">
-                    {formatShortTimestamp(summary.completedAt, settings.timestampFormat)}
+                    {formatShortTimestamp(
+                      summary.completedAt,
+                      settings.timestampFormat,
+                      resolvedLocale,
+                    )}
                   </span>
                 </span>
               </SelectItem>

apps/web/src/components/chat/MessagesTimeline.test.tsx

@@ -1,8 +1,10 @@
 import { MessageId } from "@okcode/contracts";
+import type { ReactElement } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
 import { beforeAll, describe, expect, it, vi } from "vitest";
 
 import { buildChatShortcutGuides } from "~/lib/chatShortcutGuidance";
+import { I18nProvider } from "~/i18n/I18nProvider";
 
 function matchMedia() {
   return {
@@ -36,6 +38,9 @@ beforeAll(() => {
     documentElement: {
       classList,
       offsetHeight: 0,
+      style: {
+        setProperty: () => {},
+      },
     },
   });
   vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
@@ -46,10 +51,14 @@ beforeAll(() => {
 
 const EMPTY_SHORTCUT_GUIDES = buildChatShortcutGuides([], "Win32");
 
+function renderWithI18n(element: ReactElement) {
+  return renderToStaticMarkup(<I18nProvider>{element}</I18nProvider>);
+}
+
 describe("MessagesTimeline", () => {
   it("renders inline terminal labels with the composer chip UI", async () => {
     const { MessagesTimeline } = await import("./MessagesTimeline");
-    const markup = renderToStaticMarkup(
+    const markup = renderWithI18n(
       <MessagesTimeline
         hasMessages
         isWorking={false}
@@ -105,7 +114,7 @@ describe("MessagesTimeline", () => {
 
   it("renders context compaction entries in the normal work log", async () => {
     const { MessagesTimeline } = await import("./MessagesTimeline");
-    const markup = renderToStaticMarkup(
+    const markup = renderWithI18n(
       <MessagesTimeline
         hasMessages
         isWorking={false}
@@ -151,7 +160,7 @@ describe("MessagesTimeline", () => {
 
   it("renders shortcut guidance when the timeline is empty", async () => {
     const { MessagesTimeline } = await import("./MessagesTimeline");
-    const markup = renderToStaticMarkup(
+    const markup = renderWithI18n(
       <MessagesTimeline
         hasMessages={false}
         isWorking={false}

apps/web/src/components/chat/MessagesTimeline.tsx

@@ -53,6 +53,7 @@ import {
 import { cn } from "~/lib/utils";
 import { type TimestampFormat } from "../../appSettings";
 import { formatTimestamp } from "../../timestampFormat";
+import { useI18n } from "../../i18n/useI18n";
 import {
   buildInlineTerminalContextText,
   formatInlineTerminalContextLabel,
@@ -113,6 +114,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
   shortcutGuides,
   onOpenSettings,
 }: MessagesTimelineProps) {
+  const { resolvedLocale } = useI18n();
   const timelineRootRef = useRef<HTMLDivElement | null>(null);
   const [timelineWidthPx, setTimelineWidthPx] = useState<number | null>(null);
 
@@ -467,7 +469,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
                       </span>
                     )}
                     <p className="text-right text-[10px] text-muted-foreground/30">
-                      {formatTimestamp(row.message.createdAt, timestampFormat)}
+                      {formatTimestamp(row.message.createdAt, timestampFormat, resolvedLocale)}
                     </p>
                   </div>
                 </div>
@@ -579,6 +581,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
                       ? formatElapsed(row.durationStart, nowIso)
                       : formatElapsed(row.durationStart, row.message.completedAt),
                     timestampFormat,
+                    resolvedLocale,
                   )}
                 </p>
               </div>
@@ -795,9 +798,10 @@ function formatMessageMeta(
   createdAt: string,
   duration: string | null,
   timestampFormat: TimestampFormat,
+  locale: ReturnType<typeof useI18n>["resolvedLocale"],
 ): string {
-  if (!duration) return formatTimestamp(createdAt, timestampFormat);
-  return `${formatTimestamp(createdAt, timestampFormat)} • ${duration}`;
+  if (!duration) return formatTimestamp(createdAt, timestampFormat, locale);
+  return `${formatTimestamp(createdAt, timestampFormat, locale)} • ${duration}`;
 }
 
 const UserMessageTerminalContextInlineLabel = memo(