# UI i18n Audit (Remaining Work)

Scope: `packages/ui/` (and consumers: `packages/app/`, `packages/enterprise/`)

Date: 2026-01-20

This report documents the remaining user-facing strings in `packages/ui/src` that are still hardcoded (not routed through a translation function), and proposes an i18n architecture that works long-term across multiple packages.

## Current State

- `packages/app/` already has i18n via `useLanguage().t("...")` with dictionaries in `packages/app/src/i18n/en.ts` and `packages/app/src/i18n/zh.ts`.
- `packages/ui/` is a shared component library used by:
  - `packages/app/src/pages/session.tsx` (Session UI)
  - `packages/enterprise/src/routes/share/[shareID].tsx` (shared session rendering)
- `packages/ui/` currently has **hardcoded English UI copy** in several components (notably `session-turn.tsx`, `session-review.tsx`, `message-part.tsx`).
- `packages/enterprise/` does not currently have an i18n system, so any i18n approach must be usable without depending on `packages/app/`.

## Decision: How We Should Add i18n To `@opencode-ai/ui`

Introduce a small, app-agnostic i18n interface in `packages/ui/` and keep UI-owned strings in UI-owned dictionaries.

Why this is the best long-term shape:

- Keeps dependency direction clean: `packages/enterprise/` (and any future consumer) can translate UI without importing `packages/app/` dictionaries.
- Avoids prop-drilling strings through shared components.
- Allows each package to own its strings while still rendering a single, coherent locale in the product.

### Proposed Architecture

1. **UI provides an i18n context (no persistence)**

- Add `packages/ui/src/context/i18n.tsx`:
  - Exports `I18nProvider` and `useI18n()`.
  - Context value includes:
    - `t(key, params?)` translation function (template interpolation supported by the consumer).
    - `locale()` accessor for locale-sensitive formatting (Luxon/Intl).
  - Context should have a safe default (English) so UI components can render even if a consumer forgets the provider.

2. **UI owns UI strings (dictionaries live in UI)**

- Add `packages/ui/src/i18n/en.ts` and `packages/ui/src/i18n/zh.ts`.
- Export them from `@opencode-ai/ui` via `packages/ui/package.json` exports (e.g. `"./i18n/*": "./src/i18n/*.ts"`).
- Use a clear namespace prefix for all UI keys to avoid collisions:
  - Recommended: `ui.*` (e.g. `ui.sessionReview.title`).

3. **Consumers merge dictionaries and provide `t`/`locale` once**

- `packages/app/`:
  - Keep `packages/app/src/context/language.tsx` as the source of truth for locale selection/persistence.
  - Extend it to merge UI dictionaries into its translation table.
  - Add a tiny bridge provider in `packages/app/src/app.tsx` to feed `useLanguage()` into `@opencode-ai/ui`'s `I18nProvider`.

- `packages/enterprise/`:
  - Add a lightweight locale detector (similar to `packages/app/src/context/language.tsx`), likely based on `Accept-Language` on the server and/or `navigator.languages` on the client.
  - Merge `@opencode-ai/ui` dictionaries and (optionally) enterprise-local dictionaries.
  - Wrap the share route in `I18nProvider`.

### Key Naming Conventions (UI)

- Prefer component + semantic grouping:
  - `ui.sessionReview.title`
  - `ui.sessionReview.diffStyle.unified`
  - `ui.sessionReview.diffStyle.split`
  - `ui.sessionReview.expandAll`
  - `ui.sessionReview.collapseAll`

- For `SessionTurn`:
  - `ui.sessionTurn.steps.show`
  - `ui.sessionTurn.steps.hide`
  - `ui.sessionTurn.summary.response`
  - `ui.sessionTurn.diff.more` (use templating: `Show more changes ({{count}})`)
  - `ui.sessionTurn.retry.retrying` / `ui.sessionTurn.retry.inSeconds` / etc (avoid string concatenation that is English-order dependent)
  - Status text:
    - `ui.sessionTurn.status.delegating`
    - `ui.sessionTurn.status.planning`
    - `ui.sessionTurn.status.gatheringContext`
    - `ui.sessionTurn.status.searchingCode`
    - `ui.sessionTurn.status.searchingWeb`
    - `ui.sessionTurn.status.makingEdits`
    - `ui.sessionTurn.status.runningCommands`
    - `ui.sessionTurn.status.thinking`
    - `ui.sessionTurn.status.thinkingWithTopic` (template: `Thinking - {{topic}}`)
    - `ui.sessionTurn.status.gatheringThoughts`
    - `ui.sessionTurn.status.consideringNextSteps` (fallback)

## Locale-Sensitive Formatting (UI)

`SessionTurn` currently formats durations via Luxon `Interval.toDuration(...).toHuman(...)` without an explicit locale.

When i18n is added:

- Use `useI18n().locale()` and pass locale explicitly:
  - Luxon: `duration.toHuman({ locale: locale(), ... })` (or set `.setLocale(locale())` where applicable).
  - Intl numbers/currency (if added later): `new Intl.NumberFormat(locale(), ...)`.

## Initial Hardcoded Strings (Audit Findings)

These are the highest-impact UI surfaces to translate first.

### 1) `packages/ui/src/components/session-review.tsx`

- `Session changes`
- `Unified` / `Split`
- `Collapse all` / `Expand all`

### 2) `packages/ui/src/components/session-turn.tsx`

- Tool/task status strings (e.g. `Delegating work`, `Searching the codebase`)
- Steps toggle labels: `Show steps` / `Hide steps`
- Summary section title: `Response`
- Pagination CTA: `Show more changes ({{count}})`

### 3) `packages/ui/src/components/message-part.tsx`

Examples (non-exhaustive):

- `Error`
- `Edit`
- `Write`
- `Type your own answer`
- `Review your answers`

### 4) Additional Hardcoded Strings (Full Audit)

Found during a full `packages/ui/src/components` + `packages/ui/src/context` sweep:

- `packages/ui/src/components/list.tsx`
  - `Loading`
  - `No results`
  - `No results for "{{filter}}"`
- `packages/ui/src/components/message-nav.tsx`
  - `New message`
- `packages/ui/src/components/text-field.tsx`
  - `Copied`
  - `Copy to clipboard`
- `packages/ui/src/components/image-preview.tsx`
  - `Image preview` (alt text)

## Prioritized Implementation Plan

1. Completed (2026-01-20): Add `@opencode-ai/ui` i18n context (`packages/ui/src/context/i18n.tsx`) + export it.
2. Completed (2026-01-20): Add UI dictionaries (`packages/ui/src/i18n/en.ts`, `packages/ui/src/i18n/zh.ts`) + export them.
3. Completed (2026-01-20): Wire `I18nProvider` into:
   - `packages/app/src/app.tsx`
   - `packages/enterprise/src/app.tsx`
4. Completed (2026-01-20): Convert `packages/ui/src/components/session-review.tsx` and `packages/ui/src/components/session-turn.tsx` to use `useI18n().t(...)`.
5. Completed (2026-01-20): Convert `packages/ui/src/components/message-part.tsx`.
6. Completed (2026-01-20): Do a full `packages/ui/src/components` + `packages/ui/src/context` audit for additional hardcoded copy.

## Notes / Risks

- **SSR:** Enterprise share pages render on the server. Ensure the i18n provider works in SSR and does not assume `window`/`navigator`.
- **Key collisions:** Use a consistent `ui.*` prefix to avoid clashing with app keys.
- **Fallback behavior:** Decide whether missing keys should:
  - fall back to English, or
  - render the key (useful for catching missing translations).