# L10n Cleanup + Stable Error Code + Frontend Text Migration Implementation Plan

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

**Goal:** Remove redundant l10n wrappers, introduce backend stable/mappable error codes for HTTP contracts, and continue frontend hardcoded-text localization migration to zh/en with default zh.

**Architecture:** Keep Flutter UI localization in `lib/l10n` as single source of truth, minimize cross-layer localization coupling, and use backend RFC7807 + `code`/`params` as machine-readable contract. Frontend maps `code -> l10n key` for user-facing messages while preserving fallback behavior.

**Tech Stack:** Flutter gen-l10n, FastAPI (RFC7807), Pydantic models, Dio client error mapping, existing AGENTS/rules constraints.

---

### Task 1: Freeze and baseline current behavior

**Files:**
- Modify: none (read-only task)
- Verify: `apps/lib/**`, `backend/src/**`, `docs/protocols/**`

**Step 1: Snapshot app localization status**

Run: `python scripts/count_cn_literals.py` (or equivalent one-off command)
Expected: baseline count and top files with Chinese literals.

**Step 2: Snapshot backend detail-string usage**

Run: `python scripts/count_http_detail_usage.py` (or equivalent one-off command)
Expected: per-file count of `HTTPException(detail=...)` hotspots.

**Step 3: Capture baseline checks**

Run: `cd apps && flutter analyze`
Expected: no new errors, only known existing warnings/infos.

Run: `cd backend && uv run pytest -q` (or targeted fast suite if full too slow)
Expected: baseline pass/fail recorded for regression comparison.

---

### Task 2: Refactor l10n structure to remove redundant wrapper responsibilities

**Files:**
- Modify: `apps/lib/app/app.dart`
- Modify: UI files currently importing `apps/lib/core/l10n/l10n.dart`
- Delete/Modify: `apps/lib/core/l10n/l10n.dart` (depending on final outcome)
- Verify: generated files under `apps/lib/l10n/`

**Step 1: Define target rule**

Rule:
- UI layer uses `context.l10n`.
- Non-UI layer does not depend on ad-hoc global locale state.
- If non-UI needs localization, pass already-localized strings in from caller or inject mapper service.

**Step 2: Write failing/static guard checks**

Add temporary grep checks:
- Fail when new code adds `L10n.current` in feature/presentation.
- Fail when `core/l10n/l10n.dart` is reintroduced for convenience access.

**Step 3: Replace call sites incrementally**

For each file:
1. Replace `L10n.current.xxx` with `context.l10n.xxx` where `BuildContext` exists.
2. For cubit/service/form validators, inject message providers or pass messages from UI.
3. Keep behavior unchanged.

**Step 4: Remove locale global mutation path**

In `app.dart`:
- Remove `L10n.setLocale(...)` style side effects.
- Keep Flutter-native delegates + `supportedLocales` + default locale logic.

**Step 5: Delete redundant wrapper (if no remaining valid use case)**

Delete `apps/lib/core/l10n/l10n.dart` only after all references are removed and non-UI strategy is in place.

**Step 6: Verify**

Run: `cd apps && flutter gen-l10n && flutter analyze`
Expected: no errors.

---

### Task 3: Define backend stable error code contract (RFC7807 extension)

**Files:**
- Modify: `backend/src/core/http/response.py`
- Modify: `backend/src/app.py`
- Create: `backend/src/core/http/errors.py`
- Modify: `docs/protocols/agent/api-endpoints.md`
- (optional) Create: `docs/protocols/common/error-contract.md`

**Step 1: Extend problem details schema**

Add fields:
- `code: str | None`
- `params: dict[str, str | int | float | bool] | None`

Preserve RFC7807 required fields and media type.

**Step 2: Introduce unified domain error type**

In `core/http/errors.py`, create exception class carrying:
- http status
- stable error code (UPPER_SNAKE_CASE)
- optional params
- optional internal detail

**Step 3: Wire global exception handlers**

In `app.py`:
- Convert domain exceptions to problem+json with `code` and `params`.
- Keep fallback for unknown exceptions.

**Step 4: Define code naming convention**

Examples:
- `AUTH_INVALID_TOKEN`
- `AUTH_TOKEN_EXPIRED`
- `SCHEDULE_ITEM_NOT_FOUND`
- `TODO_TITLE_REQUIRED`
- `FRIENDSHIP_ALREADY_EXISTS`

---

### Task 4: Migrate backend hotspots from free-text detail to stable codes

**Files:**
- Modify: `backend/src/v1/friendships/service.py`
- Modify: `backend/src/v1/schedule_items/service.py`
- Modify: `backend/src/v1/todo/service.py`
- Modify: `backend/src/v1/agent/service.py`
- Modify: `backend/src/v1/users/service.py`
- Modify: `backend/src/v1/memories/service.py`
- Modify: `backend/src/v1/auth/gateway.py`
- Modify: `backend/src/v1/agent/router.py`
- Modify: other files with `HTTPException(detail=...)`

**Step 1: Prioritize by impact**

Order:
1. Auth
2. Agent
3. Todo/Schedule/Friendships
4. Users/Memories

**Step 2: Replace throw sites**

For each detail-based throw:
1. Map to stable `code`.
2. Keep detail only as optional server diagnostic text.
3. Add params when useful (e.g., max size, field, limit).

**Step 3: Preserve backwards compatibility window**

During transition:
- Keep `detail` present.
- Add `code`/`params` immediately.
- Frontend prefers `code`, falls back to existing behavior.

---

### Task 5: Frontend network error mapping to l10n via backend code

**Files:**
- Modify: `apps/lib/core/network/api_exception.dart`
- Create: `apps/lib/core/network/error_code_mapper.dart`
- Modify: call sites currently displaying raw backend detail
- Modify: `apps/lib/l10n/app_zh.arb`, `apps/lib/l10n/app_en.arb`

**Step 1: Parse `code` and `params` from response payload**

In `ApiException.fromDioError`:
- Read RFC7807 + extension fields.
- Keep `statusCode` fallback behavior.

**Step 2: Map `code -> localized message`**

Implement central mapper:
- Input: code/status/params
- Output: localized user-facing string key resolution

**Step 3: Fallback strategy**

Priority:
1. known code mapping
2. status-based generic mapping
3. safe generic fallback (`request failed` localized)

**Step 4: Replace UI direct usage of raw server detail**

Audit and update places where `e.toString()` or backend detail is shown directly.

---

### Task 6: Continue frontend hardcoded text migration (remaining files)

**Files:**
- Modify: `apps/lib/features/settings/presentation/screens/*.dart` (remaining high-count files)
- Modify: `apps/lib/features/calendar/presentation/screens/*.dart`
- Modify: `apps/lib/features/calendar/presentation/widgets/*.dart`
- Modify: `apps/lib/l10n/app_zh.arb`, `apps/lib/l10n/app_en.arb`

**Step 1: Batch by screen group**

Batch A: settings deep pages
Batch B: calendar pages
Batch C: shared/home leftovers

**Step 2: Migrate with key hygiene**

Rules:
- key names are feature-prefixed and stable
- dynamic texts use placeholders, not string concatenation
- avoid duplicate semantic keys

**Step 3: After each batch, run verification**

Run:
- `cd apps && flutter gen-l10n`
- `cd apps && flutter analyze`

Track remaining hardcoded-literal count after each batch.

---

### Task 7: Protocol docs and test updates

**Files:**
- Modify: `docs/protocols/agent/api-endpoints.md`
- Modify/Create: `docs/protocols/common/error-contract.md`
- Modify: backend integration/unit tests asserting only `detail`
- Modify: frontend tests around error display/mapping

**Step 1: Document new error response shape**

Example:

```json
{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Validation failed",
  "code": "TODO_TITLE_REQUIRED",
  "params": {"field": "title"},
  "instance": "/api/v1/todo"
}
```

**Step 2: Update tests to assert codes first**

Replace brittle text assertions with:
- `status`
- `code`
- optional `params`

---

### Task 8: Final verification gate

**Files:**
- Verify only

**Step 1: Apps verification**

Run:
- `cd apps && flutter gen-l10n`
- `cd apps && flutter analyze`

**Step 2: Backend verification**

Run:
- `cd backend && uv run ruff check .`
- `cd backend && uv run basedpyright`
- `cd backend && uv run pytest -q`

**Step 3: Cross-contract smoke**

Run targeted API checks ensuring error payload includes `code` for representative modules.

---

### Task 9: Rollout and compatibility

**Files:**
- Modify: release notes/changelog if used

**Step 1: Progressive rollout strategy**

- Phase 1: backend emits both `detail` + `code`
- Phase 2: frontend consumes `code` with fallback
- Phase 3: clean up legacy detail-dependent branches

**Step 2: Monitoring**

- Log unknown/unmapped error codes on frontend
- Add backend metrics for top emitted error codes

---

## Risks and mitigations

- Risk: non-UI code loses localization access after wrapper removal
  - Mitigation: inject messages from UI/service boundary; avoid static locale globals.
- Risk: backend code migration is broad (many detail throws)
  - Mitigation: staged module-by-module migration + compatibility window.
- Risk: front/back mismatch in error code enum
  - Mitigation: shared protocol doc + CI checks for known code list.

## Done criteria

- `apps/lib/core/l10n/l10n.dart` removed or reduced to zero-overlap minimal utility with explicit justification.
- Backend RFC7807 responses include stable `code` (and optional `params`) on migrated endpoints.
- Frontend maps known codes to zh/en l10n; raw detail is no longer primary user-facing string.
- Hardcoded visible Chinese text count in `apps/lib` reduced to agreed threshold or zero for targeted modules.
- Docs and tests updated accordingly.