MicroFish/.kiro/specs/i18n-externalize-remaining-backend-logs/research.md

# Research & Design Decisions

## Summary

- **Feature**: `i18n-externalize-remaining-backend-logs`
- **Discovery Scope**: Simple Addition (extending an established convention from ticket #6)
- **Key Findings**:
  - The `t()` helper, per-thread locale, and missing-key fallback are already in place in `backend/app/utils/locale.py` and require no changes.
  - The convention `t("log.<domain>.m###", **kwargs)` with `{name}` placeholders is already used by all sibling modules; this spec strictly extends it.
  - No existing test fixtures reference any of the nine Chinese strings to be replaced.

## Research Log

### Existing locale namespace structure
- **Context**: Need to add new keys without colliding with existing entries.
- **Sources Consulted**: `locales/en.json`, `locales/zh.json`, `.kiro/specs/i18n-externalize-backend-logs/requirements.md`.
- **Findings**:
  - `log.graph_api` is densely populated `m006`–`m019` plus `m026`. Free contiguous slots starting at the tail: `m027`, `m028`, `m029`.
  - `log.profile_generator` is densely populated `m001`–`m023`. Free slots: `m024`, `m025`.
  - `log.retry` does not exist; introducing it as a sibling to other `log.<domain>` namespaces matches the existing pattern.
- **Implications**: New keys append at the tail per existing namespace; `log.retry` is created fresh starting at `m001`.

### Locale resolution in async / background contexts
- **Context**: `retry.py` is shared infrastructure invoked from sync request handlers, background tasks, and async coroutines.
- **Sources Consulted**: `backend/app/utils/locale.py`, `backend/app/services/oasis_profile_generator.py` (uses `set_locale`), Flask docs (request-context behaviour).
- **Findings**:
  - `get_locale()` returns the request-context `Accept-Language` header when a Flask request is active, the per-thread locale otherwise, and `'zh'` as the default.
  - Asyncio coroutines run on the same OS thread by default, so the per-thread locale set by the parent function propagates into `await`-driven calls.
  - Missing-key fallback returns the key string and emits a deduped warning — never raises.
- **Implications**: No new locale-propagation wiring needed inside `retry.py`. Adding `from ..utils.locale import t` is sufficient.

### `print(...)` vs `logger` for the OASIS banners
- **Context**: Two `print(...)` banner statements at `oasis_profile_generator.py:945` and `:1001` decorate stdout. Should we keep them as `print` or fold them into existing `logger.info` calls?
- **Sources Consulted**: `backend/app/services/oasis_profile_generator.py:943` (existing `logger.info(t("log.profile_generator.m017", …))`), ticket #24 acceptance ("each `file:line` is fixed").
- **Findings**:
  - The existing `logger.info` and the `print(...)` are emitting the same logical event in two channels. The banner adds `'='*60` separators on the surrounding lines, which is purely a console-cosmetic; replacing the print with a logger call would lose the visual banner.
  - Ticket #24 wants externalisation, not removal.
- **Implications**: Keep both calls. Wrap the `print(f"...")` argument with `t(...)`. Introduce dedicated keys (`m024`, `m025`) so the banner copy is decoupled from the structured log copy at `m017`.

## Architecture Pattern Evaluation

| Option | Description | Strengths | Risks / Limitations | Notes |
|--------|-------------|-----------|---------------------|-------|
| Append-at-tail (selected) | Add new `m###` keys at the next contiguous slot per namespace; create `log.retry` fresh | Mirrors #6 convention; minimal diff; no overwrite risk | Numbering gaps under `log.graph_api` remain | Aligns with steering principle of preserving established conventions |
| Fill numbering gaps | Reuse missing slots `m009`, `m010`, etc. | Tighter numbering | Risk of colliding with reserved-but-not-yet-merged keys; mixed insertion sites complicate review | Rejected |
| Consolidate banner prints into logger | Remove the `print(...)` calls; use only `logger.info(t(...))` | One fewer key | Behaviour change (loses console banner); violates Requirement 3.2 | Rejected |

## Design Decisions

### Decision: Add a new `log.retry` sub-namespace rather than reusing `log.bootstrap` or `log.graph_api`
- **Context**: `retry.py` is a generic utility used by many callers; it does not belong to a single domain.
- **Alternatives Considered**:
  1. Place keys under `log.bootstrap` — wrong domain (bootstrap is for app startup logs).
  2. Place keys under each caller's namespace — would require dynamic key resolution, adding complexity.
  3. New `log.retry` sub-namespace — clean and self-describing.
- **Selected Approach**: Introduce `log.retry.m001`–`m004` as a peer of `log.graph_api`, `log.profile_generator`, etc.
- **Rationale**: Matches the per-domain naming scheme already in use; locates retry-specific copy in one place.
- **Trade-offs**: Adds one new sub-namespace under `log`, but does not change the top-level key set.
- **Follow-up**: Verify that no other module already defines `log.retry` (verified: it does not exist).

### Decision: Wrap `print(...)` arguments rather than removing the prints
- **Context**: Ticket #24 mandates externalisation of the listed call sites; behaviour preservation is in scope.
- **Alternatives Considered**:
  1. Keep `print(t("..."))` — preserves console banner, externalises text.
  2. Remove `print(...)`; rely on `logger.info` only — drops banner.
- **Selected Approach**: Option 1. The `'='*60` separator lines stay; only the message text routes through `t(...)`.
- **Rationale**: Minimum change; respects Requirement 3.2.
- **Trade-offs**: None significant.
- **Follow-up**: Confirm during validation that the surrounding separator prints (`print(f"\n{'='*60}")`) are not on the ticket's evidence list (they are not — they contain only ASCII).

### Decision: Pass exception text as a keyword argument named `e` (not `error`)
- **Context**: Existing `log.profile_generator` keys use `e=str(e)` and `error=...` inconsistently. Need to pick one convention to remain consistent.
- **Alternatives Considered**:
  1. Use `e` — matches `log.profile_generator.m003`, `m005`, `m008`, `m012`.
  2. Use `error` — matches `log.profile_generator.m018`.
- **Selected Approach**: Use `e` for raw exception strings (the more common pattern). Where a separate label is more readable, use a domain-specific name (e.g. `error` is fine when it carries semantic weight).
- **Rationale**: Match the dominant existing convention.
- **Trade-offs**: None.
- **Follow-up**: Use `e` throughout the new keys.

## Risks & Mitigations

- **Async retry on a fresh thread without `set_locale`** — Falls back to `'zh'`. Acceptable: ticket #24 acceptance targets *source-code* CJK absence. Documented for future ticket if needed.
- **Circular imports when adding `from ..utils.locale import t` to `retry.py`** — `locale.py` imports only `json`, `logging`, `os`, `threading`, and `flask` (no project modules). No circular risk.
- **Test-suite breakage from changed log text** — No fixtures match the Chinese strings. Verified by grep of `backend/`. Low risk.

## References

- Sibling spec: `.kiro/specs/i18n-externalize-backend-logs/requirements.md` — established convention.
- Ticket #6 (closed) and ticket #24 (this work).
- `backend/app/utils/locale.py` — `t()` contract.