read.markets/docs/superpowers/plans/2026-05-27-localization-italian.md

# Localization (Italian active, ES/FR/DE WIP) — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make every AI-generated user-facing surface render in Italian when the user picks `Italiano` in settings; lay the wiring so adding ES/FR/DE later is a one-line constant change.

**Architecture:** Per-user surfaces (`portfolio_analysis`, `email_digest_job`, follow-up chat if present) thread the user's `lang` into the LLM prompt via a `respond_in_clause()` helper — one extra line on the system prompt, no extra call. The hourly `ai_log_job` writes the English `StrategicLog` row as today, then fans out parallel `translate()` calls (`asyncio.gather`) — one per active non-en language with at least one user — and persists each result in a new `strategic_log_translations` table. The `/log` endpoint serves the matching translation when present and falls back to English otherwise.

**Tech Stack:** FastAPI · SQLAlchemy 2.0 async · Alembic · MariaDB (prod) / aiosqlite (tests) · existing `openrouter.call_llm` (DeepSeek-4-flash primary, OpenRouter fallback) · Jinja2 templates

**Spec:** `docs/superpowers/specs/2026-05-27-localization-italian-design.md`

---

## File Structure

**Create:**
- `app/services/i18n.py` — `LANGUAGES`, `ACTIVE_LANGUAGES`, `respond_in_clause()`
- `app/services/translation.py` — `translate(client, text, target_lang)` wrapping `call_llm`
- `alembic/versions/0022_localization.py` — adds `users.lang`, creates `strategic_log_translations`
- `tests/test_i18n.py` — unit tests for the two new services
- `tests/test_localization_integration.py` — wiring/fan-out + route-level integration

**Modify:**
- `app/models.py` — add `User.lang`, new `StrategicLogTranslation` model
- `app/jobs/ai_log_job.py` — translation fan-out after English row is committed
- `app/services/portfolio_analysis.py` — accept + thread `lang` field
- `app/routers/universe.py` — pass `cu.user.lang` (or `"en"` for admin) into `parse_request`
- `app/jobs/email_digest_job.py` — thread `user.lang` into the per-user prompt
- `app/routers/api.py` — add `PATCH /api/settings/language` endpoint
- `app/routers/pages.py` — `log_page` / `log_page_day` serve translated content when available
- `app/templates/settings.html` — language dropdown + small JS handler

**Reuse without modification:**
- `app/services/openrouter.call_llm`, `LogResult`
- `app/auth.require_auth` / `require_token` / `CurrentUser`
- `app/db.Base`, `utcnow`, `get_session`
- Test session-factory pattern from `tests/test_referral_conversion.py::_build_session_factory`

---

## Test Conventions

All tests runnable in the project-isolated container:

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_i18n.py tests/test_localization_integration.py -v
```

DB-touching tests use the per-test `_build_session_factory(tmp_path)` pattern from `tests/test_referral_conversion.py`. LLM calls mocked via `monkeypatch.setattr(<module>, "call_llm", AsyncMock(...))`. Real Yahoo/network calls forbidden.

---

### Task 1: i18n service — LANGUAGES, ACTIVE_LANGUAGES, respond_in_clause

**Files:**
- Create: `app/services/i18n.py`
- Test: `tests/test_i18n.py`

- [ ] **Step 1: Write failing tests**

Create `tests/test_i18n.py`:

```python
"""Unit tests for app.services.i18n."""
from __future__ import annotations

import pytest


def test_languages_contains_all_four_plus_english():
    from app.services.i18n import LANGUAGES
    assert set(LANGUAGES.keys()) == {"en", "it", "es", "fr", "de"}
    assert LANGUAGES["en"] == "English"
    assert LANGUAGES["it"] == "Italian"
    assert LANGUAGES["es"] == "Spanish"
    assert LANGUAGES["fr"] == "French"
    assert LANGUAGES["de"] == "German"


def test_active_languages_is_en_and_it_only():
    from app.services.i18n import ACTIVE_LANGUAGES
    assert ACTIVE_LANGUAGES == {"en", "it"}


def test_respond_in_clause_empty_for_english():
    from app.services.i18n import respond_in_clause
    assert respond_in_clause("en") == ""


def test_respond_in_clause_empty_for_none_or_empty():
    from app.services.i18n import respond_in_clause
    assert respond_in_clause("") == ""
    assert respond_in_clause(None) == ""


def test_respond_in_clause_italian():
    from app.services.i18n import respond_in_clause
    result = respond_in_clause("it")
    assert "Italian" in result
    assert result.startswith("\n\n")


def test_respond_in_clause_unknown_lang_falls_back_to_english():
    """Defensive: a raw POST or stale lang code should not crash the
    prompt assembly. Unknown codes map to no-suffix (English default)."""
    from app.services.i18n import respond_in_clause
    assert respond_in_clause("xx") == ""
```

- [ ] **Step 2: Run tests to verify they fail**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_i18n.py -v
```

Expected: 6 FAIL with `ImportError`.

- [ ] **Step 3: Implement `app/services/i18n.py`**

```python
"""Language registry + prompt helpers for localized AI output.

Two surfaces consume this module:
- Per-user LLM call sites (portfolio analysis, digest, chat) call
  ``respond_in_clause(user.lang)`` and append the result to their
  system prompt.
- The settings dropdown + its PATCH endpoint consult ``ACTIVE_LANGUAGES``
  to decide which options are selectable.

Adding Spanish/French/German support later is a one-line constant
change: extend ``ACTIVE_LANGUAGES`` to include the new code. No other
code change is required — the rest of the system already treats them
as first-class via ``LANGUAGES``.
"""
from __future__ import annotations


# Display labels for every language the system knows about. ES/FR/DE
# are kept here so labels still render in the dropdown (as disabled
# options) without requiring code changes to enable them later.
LANGUAGES: dict[str, str] = {
    "en": "English",
    "it": "Italian",
    "es": "Spanish",
    "fr": "French",
    "de": "German",
}


# Languages users can actually select. Settings POST validates against
# this; the strategic-log translation fan-out only considers these.
ACTIVE_LANGUAGES: set[str] = {"en", "it"}


def respond_in_clause(lang: str | None) -> str:
    """Suffix appended to per-user LLM system prompts.

    Returns an empty string for ``en`` (no nudge needed), an unknown
    code, or ``None``/empty input — those callers want the default
    English path. Otherwise returns ``"\\n\\nRespond in <Language>."``
    keyed off ``LANGUAGES``.
    """
    if not lang or lang == "en" or lang not in LANGUAGES:
        return ""
    return f"\n\nRespond in {LANGUAGES[lang]}."
```

- [ ] **Step 4: Run tests to verify they pass**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_i18n.py -v
```

Expected: 6 PASS.

- [ ] **Step 5: Commit**

```bash
git add app/services/i18n.py tests/test_i18n.py
git commit -m "i18n: add LANGUAGES, ACTIVE_LANGUAGES, respond_in_clause helper"
```

## Context

- Working directory: `/home/gg/mydocker_images/products/read.markets`. Branch `main`. Commit directly.
- Test runner: ONLY `docker compose -f docker-compose.test.yml ...`. NEVER plain `docker compose ...` against the prod stack.
- If `git commit` is blocked by the auto-mode classifier, leave the tree dirty and report — the controller will commit.

---

### Task 2: translation service

**Files:**
- Create: `app/services/translation.py`
- Test: `tests/test_i18n.py` (append)

- [ ] **Step 1: Write failing tests**

Append to `tests/test_i18n.py`:

```python
@pytest.mark.asyncio
async def test_translate_happy_path(monkeypatch):
    from unittest.mock import AsyncMock, MagicMock

    from app.services import translation as mod
    from app.services.openrouter import LogResult

    monkeypatch.setattr(mod, "call_llm", AsyncMock(return_value=LogResult(
        content="# Apertura\n\nIl mercato è in calo dello 0,4%.",
        model="deepseek/deepseek-v4-flash",
        prompt_tokens=300, completion_tokens=80, cost_usd=0.00002,
    )))

    client = MagicMock()
    translated, llm_log = await mod.translate(
        client, "# Open\n\nThe market is down 0.4%.", "it",
    )
    assert "Apertura" in translated
    assert llm_log.model == "deepseek/deepseek-v4-flash"
    assert llm_log.cost_usd == pytest.approx(0.00002)


@pytest.mark.asyncio
async def test_translate_strips_code_fences(monkeypatch):
    """If the LLM wraps the output in ```markdown ... ```, strip it."""
    from unittest.mock import AsyncMock, MagicMock

    from app.services import translation as mod
    from app.services.openrouter import LogResult

    fenced = "```markdown\n# Titolo\n\nCorpo.\n```"
    monkeypatch.setattr(mod, "call_llm", AsyncMock(return_value=LogResult(
        content=fenced, model="m", prompt_tokens=10, completion_tokens=20, cost_usd=0.0,
    )))

    client = MagicMock()
    translated, _ = await mod.translate(client, "# Title\n\nBody.", "it")
    assert "```" not in translated
    assert translated.startswith("# Titolo")


@pytest.mark.asyncio
async def test_translate_provider_failure_propagates(monkeypatch):
    from unittest.mock import AsyncMock, MagicMock

    from app.services import translation as mod

    monkeypatch.setattr(mod, "call_llm", AsyncMock(side_effect=RuntimeError("upstream down")))

    client = MagicMock()
    with pytest.raises(RuntimeError, match="upstream down"):
        await mod.translate(client, "# Title\n\nBody.", "it")


@pytest.mark.asyncio
async def test_translate_unknown_lang_returns_source_unchanged(monkeypatch):
    """Defensive: an unknown lang code (or 'en') short-circuits without
    calling the LLM. Callers shouldn't have to gate the call themselves."""
    from unittest.mock import AsyncMock, MagicMock

    from app.services import translation as mod
    from app.services.openrouter import LogResult

    call_mock = AsyncMock(return_value=LogResult(
        content="should not be returned",
        model="m", prompt_tokens=0, completion_tokens=0, cost_usd=0.0,
    ))
    monkeypatch.setattr(mod, "call_llm", call_mock)

    client = MagicMock()
    out, _ = await mod.translate(client, "Hello world.", "en")
    assert out == "Hello world."
    call_mock.assert_not_awaited()
```

- [ ] **Step 2: Run tests to verify they fail**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_i18n.py -k translate -v
```

Expected: 4 FAIL with `ImportError`.

- [ ] **Step 3: Implement `app/services/translation.py`**

```python
"""Markdown translation via the existing LLM provider chain.

DeepSeek-4-flash at ~$0.28/M output tokens is cheap enough that we
don't bother with a separate translation-only model. ``call_llm``'s
provider chain (DeepSeek primary, OpenRouter fallback) handles this
path identically to any other LLM call.

The translator is content-aware in one important way: it instructs the
model to preserve markdown structure, ticker symbols, numbers, dates,
and percentages verbatim. This keeps generated artefacts (tables of
quotes, embedded percentages, dated references) intact across the
translation boundary.
"""
from __future__ import annotations

import httpx

from app.services.i18n import LANGUAGES
from app.services.openrouter import LogResult, call_llm


_SYSTEM_PROMPT_TMPL = """\
You are an expert translator working on financial-markets commentary.
Translate the following markdown text to {language}.

Strict rules:
- Preserve ALL markdown formatting (headings, lists, emphasis, links,
  tables, code spans).
- Do NOT translate ticker symbols (AAPL, MSFT, VOD.L, ASML.AS, etc.),
  company legal names, percentages, dates, ISO currency codes, or any
  numbers.
- Do NOT add commentary, preambles, or apologies. Output ONLY the
  translated markdown.
"""


async def translate(
    client: httpx.AsyncClient,
    text: str,
    target_lang: str,
) -> tuple[str, LogResult]:
    """Translate markdown ``text`` to ``target_lang``.

    Returns ``(translated_markdown, LogResult)``. Caller persists the
    cost/model provenance from LogResult next to the cached row.

    Short-circuits without calling the LLM when ``target_lang`` is
    ``'en'``, unknown, or empty — returns the source unchanged with a
    zero-cost stub LogResult. This lets fan-out callers iterate over
    all languages without per-call gating.

    Raises on provider failure (HTTP error, all chain providers down).
    Callers in fan-out paths should catch and log per-language.
    """
    if not target_lang or target_lang == "en" or target_lang not in LANGUAGES:
        # No-op fast path. Returning a fake LogResult keeps the call
        # signature stable for callers who unpack the tuple.
        return text, LogResult(
            content=text, model="noop",
            prompt_tokens=0, completion_tokens=0, cost_usd=0.0,
        )

    system_prompt = _SYSTEM_PROMPT_TMPL.format(language=LANGUAGES[target_lang])
    messages = [
        {"role": "system", "content": system_prompt},
        {"role": "user",   "content": text},
    ]
    result = await call_llm(client, messages)

    content = (result.content or "").strip()
    # Strip code fences if the model wrapped its output despite the system rule.
    if content.startswith("```"):
        # Drop the opening fence (with optional language tag).
        first_nl = content.find("\n")
        if first_nl != -1:
            content = content[first_nl + 1:]
        # Drop the closing fence.
        if content.rstrip().endswith("```"):
            content = content.rstrip()[:-3].rstrip()
        content = content.strip()

    return content, result
```

- [ ] **Step 4: Run tests to verify they pass**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_i18n.py -v
```

Expected: 10 tests pass total (6 from Task 1 + 4 new).

- [ ] **Step 5: Commit**

```bash
git add app/services/translation.py tests/test_i18n.py
git commit -m "i18n: add translate() helper backed by call_llm"
```

---

### Task 3: User.lang column + StrategicLogTranslation model

**Files:**
- Modify: `app/models.py`
- Test: `tests/test_localization_integration.py`

- [ ] **Step 1: Write failing tests**

Create `tests/test_localization_integration.py`:

```python
"""Integration tests: model surface, ai_log_job translation fan-out,
route-level localized fetch, settings PATCH validation."""
from __future__ import annotations

import pytest


def _build_session_factory(tmp_path):
    """Per-test sqlite engine + factory. Mirrors test_referral_conversion.py."""
    from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine

    from app import db as db_mod
    from app.db import Base
    import app.models  # noqa: F401 — registers models on Base.metadata

    engine = create_async_engine(f"sqlite+aiosqlite:///{tmp_path}/loc.db")
    factory = async_sessionmaker(engine, expire_on_commit=False)
    db_mod._engine = engine
    db_mod._session_factory = factory

    async def _setup():
        async with engine.begin() as conn:
            await conn.run_sync(Base.metadata.create_all)

    return engine, factory, _setup


def test_user_has_lang_column_with_default_en():
    from sqlalchemy import inspect
    from app.models import User

    cols = {c.name: c for c in inspect(User).columns}
    assert "lang" in cols
    assert cols["lang"].nullable is False
    # SQLAlchemy default may be a callable or a literal — check both.
    default = cols["lang"].default
    assert default is not None
    if hasattr(default, "arg"):
        assert default.arg == "en"


def test_strategic_log_translation_model_columns():
    from sqlalchemy import inspect
    from app.models import StrategicLogTranslation

    cols = {c.name: c for c in inspect(StrategicLogTranslation).columns}
    assert "log_id" in cols
    assert "lang" in cols
    assert "content_md" in cols
    assert "generated_at" in cols
    assert "llm_model" in cols
    assert "llm_cost_usd" in cols
    assert cols["log_id"].nullable is False
    assert cols["lang"].nullable is False
    assert cols["content_md"].nullable is False
```

- [ ] **Step 2: Run tests to verify they fail**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_localization_integration.py -v
```

Expected: 2 FAIL — first on `User.lang` missing, second on `StrategicLogTranslation` import error.

- [ ] **Step 3: Add `User.lang` column**

In `app/models.py`, find the `User` class. Find a sensible place near other user-preference columns (next to `tone` or `digest_tone`) and add:

```python
    # Preferred language for AI-generated content (strategic log,
    # digest emails, portfolio commentary). Default 'en'. The settings
    # PATCH endpoint validates against ACTIVE_LANGUAGES in
    # app/services/i18n.py before writing.
    lang: Mapped[str] = mapped_column(
        String(8), nullable=False, default="en", server_default="en",
    )
```

- [ ] **Step 4: Add `StrategicLogTranslation` model**

In `app/models.py`, append after the existing `StrategicLog` class (around line 108-122):

```python
class StrategicLogTranslation(Base):
    """Cached translation of a single StrategicLog row.

    Populated by ai_log_job after the English row is committed: one
    row per (log_id, lang) combination. The /log endpoint serves the
    matching row when available and falls back to the English source
    when no row exists yet (e.g. translation failed or the language
    was added after the log was generated).

    No user attribution — the cache is shared. Setting `lang` on a
    user just selects which (already-translated) variant they see.
    """
    __tablename__ = "strategic_log_translations"

    id: Mapped[int] = mapped_column(_PK, primary_key=True, autoincrement=True)
    log_id: Mapped[int] = mapped_column(
        _PK, ForeignKey("strategic_logs.id", ondelete="CASCADE"), nullable=False,
    )
    lang: Mapped[str] = mapped_column(String(8), nullable=False)
    content_md: Mapped[str] = mapped_column(Text, nullable=False)
    generated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, default=utcnow,
    )
    llm_model: Mapped[str | None] = mapped_column(String(64))
    llm_cost_usd: Mapped[float | None] = mapped_column(Float)

    __table_args__ = (
        UniqueConstraint("log_id", "lang", name="uq_slt_log_lang"),
    )
```

- [ ] **Step 5: Run tests to verify they pass**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_localization_integration.py -v
```

Expected: 2 PASS.

- [ ] **Step 6: Commit**

```bash
git add app/models.py tests/test_localization_integration.py
git commit -m "models: add User.lang + StrategicLogTranslation"
```

## Context for this task

- The existing `User` class already imports `String`, `mapped_column`, `Mapped`. No new imports needed for `User.lang`.
- For `StrategicLogTranslation`, `_PK`, `String`, `Text`, `DateTime`, `Float`, `ForeignKey`, `UniqueConstraint`, `Mapped`, `mapped_column`, `Base`, `utcnow`, `datetime` are all already imported at the top of `app/models.py` — no new imports needed.

---

### Task 4: Alembic migration 0022

**Files:**
- Create: `alembic/versions/0022_localization.py`

- [ ] **Step 1: Write the migration**

```python
"""localization: users.lang + strategic_log_translations.

Revision ID: 0022
Revises: 0021
Create Date: 2026-05-27
"""
from typing import Sequence, Union

import sqlalchemy as sa
from alembic import op


revision: str = "0022"
down_revision: Union[str, None] = "0021"
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None


def upgrade() -> None:
    op.add_column(
        "users",
        sa.Column(
            "lang", sa.String(length=8), nullable=False,
            server_default="en",
        ),
    )
    op.create_table(
        "strategic_log_translations",
        sa.Column("id", sa.BigInteger(), primary_key=True, autoincrement=True),
        sa.Column("log_id", sa.BigInteger(), nullable=False),
        sa.Column("lang", sa.String(length=8), nullable=False),
        sa.Column("content_md", sa.Text(), nullable=False),
        sa.Column("generated_at", sa.DateTime(timezone=True), nullable=False),
        sa.Column("llm_model", sa.String(length=64), nullable=True),
        sa.Column("llm_cost_usd", sa.Float(), nullable=True),
        sa.ForeignKeyConstraint(
            ["log_id"], ["strategic_logs.id"],
            ondelete="CASCADE", name="fk_slt_log",
        ),
        sa.UniqueConstraint("log_id", "lang", name="uq_slt_log_lang"),
    )


def downgrade() -> None:
    op.drop_table("strategic_log_translations")
    op.drop_column("users", "lang")
```

- [ ] **Step 2: Verify migration chain integrity**

```bash
docker compose -f docker-compose.test.yml run --rm test python -c "
from alembic.config import Config
from alembic.script import ScriptDirectory
sd = ScriptDirectory.from_config(Config('alembic.ini'))
heads = sd.get_heads()
assert heads == ('0022',), heads
rev = sd.get_revision('0022')
assert rev.down_revision == '0021'
print('OK')
"
```

Expected: prints `OK`.

- [ ] **Step 3: Commit**

```bash
git add alembic/versions/0022_localization.py
git commit -m "alembic: add 0022 localization (users.lang + strategic_log_translations)"
```

## Context

- Previous migration is `0021_csv_format_template.py`. The new file follows the same hand-rolled style.
- Codebase convention for integer server_defaults is `sa.text("0")` — but here we have no integer defaults to set. String default `"en"` uses the bare string per existing migrations (e.g. `0011_drop_portfolio_tables.py` uses `server_default="GBP"`).

---

### Task 5: ai_log_job translation fan-out

**Files:**
- Modify: `app/jobs/ai_log_job.py`
- Test: `tests/test_localization_integration.py` (append)

- [ ] **Step 1: Inspect the existing log-writing path**

```bash
grep -n "def \|StrategicLog\|session.commit\|session.add" app/jobs/ai_log_job.py | head -20
```

Locate the function and the line where the new `StrategicLog` row is committed. The fan-out runs **after** that commit.

- [ ] **Step 2: Write failing tests**

Append to `tests/test_localization_integration.py`:

```python
@pytest.mark.asyncio
async def test_log_translation_fanout_no_active_non_en_users(tmp_path, monkeypatch):
    """When no users have an active non-en lang, the fan-out makes no
    translation calls and no rows are inserted."""
    from unittest.mock import AsyncMock
    from sqlalchemy import select

    from app.db import utcnow
    from app.models import StrategicLog, StrategicLogTranslation, User
    from app.jobs import ai_log_job

    _, factory, setup = _build_session_factory(tmp_path)
    await setup()

    fake_translate = AsyncMock()
    monkeypatch.setattr(ai_log_job, "translate", fake_translate)

    # Seed an English user (no non-en users).
    async with factory() as session:
        session.add(User(id=1, email="en@x", tier="paid", lang="en"))
        slog = StrategicLog(
            generated_at=utcnow(), content_md="# Open\n\nDown 0.4%.",
            tone="INTERMEDIATE", analysis="NORMAL",
        )
        session.add(slog)
        await session.commit()
        log_id = slog.id

    async with factory() as session:
        await ai_log_job.translate_log_for_active_languages(session, log_id)

    fake_translate.assert_not_awaited()
    async with factory() as session:
        rows = (await session.execute(select(StrategicLogTranslation))).scalars().all()
    assert rows == []


@pytest.mark.asyncio
async def test_log_translation_fanout_italian_user(tmp_path, monkeypatch):
    """One user at lang=it triggers one translation; the row lands with
    the right lang and log_id."""
    from unittest.mock import AsyncMock
    from sqlalchemy import select

    from app.db import utcnow
    from app.models import StrategicLog, StrategicLogTranslation, User
    from app.services.openrouter import LogResult
    from app.jobs import ai_log_job

    _, factory, setup = _build_session_factory(tmp_path)
    await setup()

    async def _fake_translate(client, text, target_lang):
        assert target_lang == "it"
        return "# Apertura\n\nIn calo 0,4%.", LogResult(
            content="# Apertura\n\nIn calo 0,4%.",
            model="deepseek/deepseek-v4-flash",
            prompt_tokens=300, completion_tokens=80, cost_usd=0.00002,
        )
    monkeypatch.setattr(ai_log_job, "translate", _fake_translate)

    async with factory() as session:
        session.add(User(id=2, email="it@x", tier="paid", lang="it"))
        slog = StrategicLog(
            generated_at=utcnow(), content_md="# Open\n\nDown 0.4%.",
            tone="INTERMEDIATE", analysis="NORMAL",
        )
        session.add(slog)
        await session.commit()
        log_id = slog.id

    async with factory() as session:
        await ai_log_job.translate_log_for_active_languages(session, log_id)

    async with factory() as session:
        rows = (await session.execute(select(StrategicLogTranslation))).scalars().all()
    assert len(rows) == 1
    row = rows[0]
    assert row.log_id == log_id
    assert row.lang == "it"
    assert row.content_md.startswith("# Apertura")
    assert row.llm_model == "deepseek/deepseek-v4-flash"
    assert row.llm_cost_usd == pytest.approx(0.00002)


@pytest.mark.asyncio
async def test_log_translation_fanout_per_language_failure_isolated(tmp_path, monkeypatch):
    """If one language's translation fails, the others (if any) still land
    and the job does not raise."""
    from unittest.mock import AsyncMock
    from sqlalchemy import select

    from app.db import utcnow
    from app.models import StrategicLog, StrategicLogTranslation, User
    from app.jobs import ai_log_job

    _, factory, setup = _build_session_factory(tmp_path)
    await setup()

    async def _fake_translate(client, text, target_lang):
        raise RuntimeError("upstream down")
    monkeypatch.setattr(ai_log_job, "translate", _fake_translate)

    async with factory() as session:
        session.add(User(id=3, email="it@x", tier="paid", lang="it"))
        slog = StrategicLog(
            generated_at=utcnow(), content_md="# Open",
            tone="INTERMEDIATE", analysis="NORMAL",
        )
        session.add(slog)
        await session.commit()
        log_id = slog.id

    # Must NOT raise.
    async with factory() as session:
        await ai_log_job.translate_log_for_active_languages(session, log_id)

    async with factory() as session:
        rows = (await session.execute(select(StrategicLogTranslation))).scalars().all()
    assert rows == []
```

- [ ] **Step 3: Run tests to verify they fail**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_localization_integration.py -k log_translation_fanout -v
```

Expected: 3 FAIL with `AttributeError: module 'app.jobs.ai_log_job' has no attribute 'translate_log_for_active_languages'`.

- [ ] **Step 4: Add the fan-out function**

In `app/jobs/ai_log_job.py`, add (at module scope, alongside other helpers; use existing imports + add what's missing — `httpx`, `asyncio`, `select`, the i18n + translation modules, and the model imports):

```python
import asyncio
import httpx

from sqlalchemy import select

from app.db import utcnow
from app.models import User, StrategicLogTranslation
from app.services.i18n import ACTIVE_LANGUAGES
from app.services.translation import translate
```

(Add only the lines not already present.)

Then add the function:

```python
async def translate_log_for_active_languages(session, log_id: int) -> None:
    """Fan out per-language translations for the strategic log identified
    by ``log_id``.

    Reads ``users.lang`` (deduplicated, restricted to ACTIVE_LANGUAGES
    minus English), one translation call per language in parallel via
    ``asyncio.gather``, persists each successful result as a
    ``StrategicLogTranslation`` row. Per-language failures are logged
    but never raise — the strategic log itself is already committed at
    this point and translation is a best-effort enhancement.

    The job orchestrator calls this AFTER the English ``StrategicLog``
    row is committed; pass the row's ``id`` in.
    """
    from app.models import StrategicLog  # local import: avoid widening top-level imports
    target_langs = sorted({l for l in ACTIVE_LANGUAGES if l != "en"})
    if not target_langs:
        return

    active_langs = (await session.execute(
        select(User.lang).distinct().where(User.lang.in_(target_langs))
    )).scalars().all()
    if not active_langs:
        return

    log_row = await session.get(StrategicLog, log_id)
    if log_row is None:
        log.warning("log.translate.missing_log", log_id=log_id)
        return

    async with httpx.AsyncClient(follow_redirects=True, timeout=60) as client:
        results = await asyncio.gather(*[
            translate(client, log_row.content_md, lang)
            for lang in active_langs
        ], return_exceptions=True)

    for lang, result in zip(active_langs, results):
        if isinstance(result, Exception):
            log.warning("log.translate.failed", lang=lang, log_id=log_id,
                        error=str(result)[:200])
            continue
        translated_md, llm_log = result
        session.add(StrategicLogTranslation(
            log_id=log_id, lang=lang,
            content_md=translated_md,
            generated_at=utcnow(),
            llm_model=llm_log.model,
            llm_cost_usd=llm_log.cost_usd,
        ))
    await session.commit()
```

- [ ] **Step 5: Wire the fan-out into the existing log-write path**

Find the function in `ai_log_job.py` that writes a `StrategicLog` row and calls `session.commit()`. After that commit, capture the row's `id` and call:

```python
await translate_log_for_active_languages(session, slog.id)
```

(Use whatever the actual local variable name for the row is.)

- [ ] **Step 6: Run tests to verify they pass**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_localization_integration.py -v
```

Expected: 5 tests pass (2 from Task 3 + 3 new).

- [ ] **Step 7: Commit**

```bash
git add app/jobs/ai_log_job.py tests/test_localization_integration.py
git commit -m "ai-log-job: translate strategic log for active non-en languages"
```

---

### Task 6: portfolio_analysis localization

**Files:**
- Modify: `app/services/portfolio_analysis.py`
- Modify: `app/routers/universe.py` — the `/api/analyze` route
- Test: `tests/test_localization_integration.py` (append)

- [ ] **Step 1: Write failing tests**

Append to `tests/test_localization_integration.py`:

```python
@pytest.mark.asyncio
async def test_analyse_threads_lang_into_system_prompt(monkeypatch):
    """When lang='it', the system prompt sent to call_llm contains
    'Respond in Italian.' — the LLM does the rest."""
    from unittest.mock import AsyncMock
    from app.services import portfolio_analysis as pa
    from app.services.openrouter import LogResult

    captured = {}

    async def _fake_call_llm(client, messages, **kw):
        captured["messages"] = messages
        return LogResult(
            content="Analisi del portafoglio in italiano.",
            model="m", prompt_tokens=400, completion_tokens=100, cost_usd=0.0001,
        )
    monkeypatch.setattr(pa, "call_llm", _fake_call_llm)

    payload = {
        "positions": [{"yahoo_ticker": "AAPL", "qty": 10, "avg_cost": 150.0,
                       "currency": "USD", "name": "Apple Inc"}],
        "prices": {"AAPL": {"p": 172.4, "c": "USD"}},
        "fx": {"USD": 1.0},
        "base_currency": "USD",
        "tone": "INTERMEDIATE",
        "analysis": "NORMAL",
        "lang": "it",
    }
    req = pa.parse_request(payload)
    assert req.lang == "it"

    # Direct call into analyse() to inspect the captured prompt.
    # Use None session — analyse should not touch the DB in this code path
    # because we mocked call_llm before any AICall ledger write.
    # If analyse insists on a session, wrap with the test factory.
    result = await pa.analyse(None, req)  # noqa: ARG  — session ignored by mock
    system = next(m["content"] for m in captured["messages"] if m["role"] == "system")
    assert "Respond in Italian" in system


@pytest.mark.asyncio
async def test_analyse_no_clause_when_lang_is_en(monkeypatch):
    from unittest.mock import AsyncMock
    from app.services import portfolio_analysis as pa
    from app.services.openrouter import LogResult

    captured = {}

    async def _fake_call_llm(client, messages, **kw):
        captured["messages"] = messages
        return LogResult(
            content="Portfolio analysis in English.",
            model="m", prompt_tokens=400, completion_tokens=100, cost_usd=0.0001,
        )
    monkeypatch.setattr(pa, "call_llm", _fake_call_llm)

    payload = {
        "positions": [{"yahoo_ticker": "AAPL", "qty": 10, "avg_cost": 150.0,
                       "currency": "USD", "name": "Apple Inc"}],
        "prices": {"AAPL": {"p": 172.4, "c": "USD"}},
        "fx": {"USD": 1.0},
        "base_currency": "USD",
        "tone": "INTERMEDIATE",
        "analysis": "NORMAL",
        "lang": "en",
    }
    req = pa.parse_request(payload)
    await pa.analyse(None, req)
    system = next(m["content"] for m in captured["messages"] if m["role"] == "system")
    assert "Respond in" not in system
```

- [ ] **Step 2: Run tests to verify they fail**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_localization_integration.py -k analyse -v
```

Expected: 2 FAIL — either `lang` field on `AnalysisRequest` missing, or "Respond in Italian" not in the prompt.

- [ ] **Step 3: Add `lang` to AnalysisRequest and thread through**

In `app/services/portfolio_analysis.py`:

1. Locate the `AnalysisRequest` dataclass (or pydantic model). Add a `lang: str = "en"` field next to `tone` / `analysis`.
2. Locate `parse_request`. Read `payload.get("lang", "en")` and pass it to the request constructor. Validate against `LANGUAGES`:

```python
from app.services.i18n import LANGUAGES, respond_in_clause

# Inside parse_request, alongside the existing tone/analysis parsing:
lang = (payload.get("lang") or "en").strip().lower()
if lang not in LANGUAGES:
    lang = "en"
```

Then build the request with `lang=lang`.

3. Locate `analyse` (the async function that builds messages and calls `call_llm`). After the system prompt is composed, append the i18n clause:

```python
system_prompt = system_prompt + respond_in_clause(req.lang)
```

(Use whatever the local variable name for the system prompt is.)

- [ ] **Step 4: Pass the user's lang from the route**

In `app/routers/universe.py`, find `analyze_portfolio` (the `/api/analyze` route handler). Add the user's lang to the payload before calling `parse_request`:

```python
# Just before parse_request:
user_lang = (
    principal.user.lang if (principal.user and principal.user.lang) else "en"
)
payload["lang"] = user_lang
```

(The handler receives `principal` via Depends. Confirm by reading the handler's signature; if the principal isn't already wired in, add `principal: CurrentUser = Depends(require_paid)` matching the existing dep.)

- [ ] **Step 5: Run tests to verify they pass**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_localization_integration.py -v
```

Expected: 7 tests pass (5 from Tasks 3+5 + 2 new).

- [ ] **Step 6: Commit**

```bash
git add app/services/portfolio_analysis.py app/routers/universe.py tests/test_localization_integration.py
git commit -m "analyse: thread user.lang into the system prompt"
```

---

### Task 7: email_digest_job — translate variants once, route by (tone, lang)

**Files:**
- Modify: `app/jobs/email_digest_job.py`
- Test: `tests/test_localization_integration.py` (append)

**Design recap:** The digest job already produces one English variant per
tone (NOVICE / INTERMEDIATE / PRO) once per job run. After those English
variants are built, the job translates each one to every active
non-English language in parallel and builds an in-memory lookup
`{(tone, lang): content_md}`. The per-user send step picks the cell
matching `(user.digest_tone, user.lang)`, falling back to `(tone, 'en')`
when a translation is missing or failed. No per-user LLM call.

- [ ] **Step 1: Inspect the existing digest flow**

```bash
grep -n "_generate_variants\|_send_one\|active_users\|for .* in .*users" app/jobs/email_digest_job.py | head -20
```

Identify:
1. Where the English variants are built (one call per tone).
2. The shape of the returned object (likely `dict[str, str]` keyed by tone like `"NOVICE"`).
3. The per-user send loop and where it picks a variant for the recipient.

- [ ] **Step 2: Write a failing test**

Append to `tests/test_localization_integration.py`:

```python
@pytest.mark.asyncio
async def test_digest_translates_variants_per_active_lang(monkeypatch):
    """After English variants are built, the job translates each to every
    active non-en lang. The result is an in-memory mapping the send loop
    consults."""
    from unittest.mock import AsyncMock, MagicMock
    from app.jobs import email_digest_job as ed
    from app.services.openrouter import LogResult

    # Stub the English variant builder so we control the input set.
    english_variants = {
        "NOVICE":       "**Today.** Markets calmer.",
        "INTERMEDIATE": "**Today.** Indices slightly down.",
        "PRO":          "**Today.** Risk-off rotation, breadth weak.",
    }

    # Track every translate() call so we can assert fan-out shape.
    translate_calls: list[tuple[str, str]] = []

    async def _fake_translate(client, text, target_lang):
        translate_calls.append((text, target_lang))
        return f"[IT] {text}", LogResult(
            content=f"[IT] {text}", model="m",
            prompt_tokens=10, completion_tokens=10, cost_usd=0.0,
        )

    monkeypatch.setattr(ed, "translate", _fake_translate)

    # The helper under test takes the English variants dict + a list of
    # active non-en languages, returns the {(tone, lang): content} table.
    client = MagicMock()
    table = await ed._translate_variants_for_active_langs(
        client, english_variants, ["it"],
    )

    # Three tones × one non-en lang = three translation calls.
    assert len(translate_calls) == 3
    assert {lang for _, lang in translate_calls} == {"it"}

    # English entries are present unchanged.
    assert table[("NOVICE", "en")] == english_variants["NOVICE"]
    assert table[("PRO", "en")] == english_variants["PRO"]
    # Italian entries are populated.
    assert table[("INTERMEDIATE", "it")].startswith("[IT] ")


@pytest.mark.asyncio
async def test_digest_translation_failure_falls_back_to_english(monkeypatch):
    """When translate() fails for a (tone, lang) cell, the table entry
    for that cell is the English variant of the same tone — the user
    still gets a digest, just in English that day."""
    from app.jobs import email_digest_job as ed

    english_variants = {"INTERMEDIATE": "**Today.** Indices down."}

    async def _fake_translate(client, text, target_lang):
        raise RuntimeError("upstream down")
    monkeypatch.setattr(ed, "translate", _fake_translate)

    from unittest.mock import MagicMock
    client = MagicMock()
    table = await ed._translate_variants_for_active_langs(
        client, english_variants, ["it"],
    )

    assert table[("INTERMEDIATE", "it")] == english_variants["INTERMEDIATE"]


def test_digest_pick_variant_uses_user_lang():
    """The variant-picker helper consults user.digest_tone + user.lang."""
    from app.jobs import email_digest_job as ed

    table = {
        ("NOVICE", "en"):       "novice en",
        ("NOVICE", "it"):       "novice it",
        ("INTERMEDIATE", "en"): "intermediate en",
        ("INTERMEDIATE", "it"): "intermediate it",
    }
    assert ed._pick_variant(table, tone="NOVICE", lang="it") == "novice it"
    assert ed._pick_variant(table, tone="INTERMEDIATE", lang="en") == "intermediate en"
    # Missing lang → fallback to English variant of the same tone.
    assert ed._pick_variant(table, tone="NOVICE", lang="de") == "novice en"
    # Missing tone → fallback to INTERMEDIATE/en (the safe default).
    assert ed._pick_variant(table, tone="UNKNOWN", lang="en") == "intermediate en"
```

- [ ] **Step 3: Run tests to verify they fail**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_localization_integration.py -k "digest_translates or digest_translation_failure or digest_pick" -v
```

Expected: 3 FAIL with `AttributeError` for `_translate_variants_for_active_langs` and `_pick_variant`.

- [ ] **Step 4: Implement the two helpers + wire them into the job**

In `app/jobs/email_digest_job.py`, add the necessary imports at the top (skip any that are already present):

```python
import asyncio

from app.services.i18n import ACTIVE_LANGUAGES
from app.services.translation import translate
```

Add the two helpers as module-level functions:

```python
async def _translate_variants_for_active_langs(
    client,
    english_variants: dict[str, str],
    target_langs: list[str],
) -> dict[tuple[str, str], str]:
    """Build a {(tone, lang): content_md} table.

    Starts with the English variants as the canonical cells. For each
    (tone, target_lang) pair where target_lang != 'en', calls translate()
    in parallel; on failure the cell falls back to the English variant
    of the same tone so the digest still goes out, just untranslated.
    """
    table: dict[tuple[str, str], str] = {
        (tone, "en"): content for tone, content in english_variants.items()
    }
    pairs = [
        (tone, lang)
        for tone in english_variants
        for lang in target_langs
        if lang != "en"
    ]
    if not pairs:
        return table

    results = await asyncio.gather(*[
        translate(client, english_variants[tone], lang) for tone, lang in pairs
    ], return_exceptions=True)
    for (tone, lang), result in zip(pairs, results):
        if isinstance(result, Exception):
            log.warning("digest.translate.failed",
                        tone=tone, lang=lang, error=str(result)[:200])
            table[(tone, lang)] = english_variants[tone]
            continue
        translated_md, _llm_log = result
        table[(tone, lang)] = translated_md
    return table


def _pick_variant(
    table: dict[tuple[str, str], str], tone: str, lang: str,
) -> str:
    """Return the digest content for a recipient.

    Lookup order: exact (tone, lang) → (tone, 'en') → ('INTERMEDIATE',
    'en') → first table value. The last falls are defensive; the table
    always contains at least one English entry when the job is sending."""
    if (tone, lang) in table:
        return table[(tone, lang)]
    if (tone, "en") in table:
        return table[(tone, "en")]
    if ("INTERMEDIATE", "en") in table:
        return table[("INTERMEDIATE", "en")]
    return next(iter(table.values()))
```

Now find the place in the job loop where English variants are generated
(after `_generate_variants` returns its tone-keyed dict) and before the
per-user send loop. Insert:

```python
# Build the per-language translation table once per job run. Active
# non-en languages are derived from users.lang so we don't translate
# for languages no one uses today.
active_non_en = sorted({l for l in ACTIVE_LANGUAGES if l != "en"})
# Optional further filter: only languages with at least one user.
# (See task notes — defer if optimization isn't worth it yet.)
variant_table = await _translate_variants_for_active_langs(
    client, variants, active_non_en,
)
```

And in the per-user send step, replace the direct variant lookup
(e.g. `content = variants[user.digest_tone]`) with:

```python
content = _pick_variant(
    variant_table,
    tone=(user.digest_tone or "INTERMEDIATE").upper(),
    lang=(user.lang or "en"),
)
```

- [ ] **Step 5: Run tests to verify they pass**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_localization_integration.py -v
```

Expected: all tests pass (≥10 total now).

- [ ] **Step 6: Commit**

```bash
git add app/jobs/email_digest_job.py tests/test_localization_integration.py
git commit -m "digest: translate variants once per active non-en language"
```

## Context

- Translation count per job run is `tones × non-en active languages`.
  Today that's `3 × 1 = 3` translation calls per digest run. Negligible cost.
- A failed translation degrades gracefully — the cell falls back to the
  English variant of the same tone. The recipient receives a digest in
  English instead of getting no email at all. This matches the spec's
  "translation is best-effort" intent.

---

### Task 8: /log endpoint localized fetch

**Files:**
- Modify: `app/routers/pages.py` — `log_page` and `log_page_day`
- Test: `tests/test_localization_integration.py` (append)

- [ ] **Step 1: Inspect the existing log endpoints**

```bash
grep -n "def log_page\|StrategicLog\|content_md\|generated_at" app/routers/pages.py | head -20
```

Locate the function(s) that fetch the strategic log and pass `content_md` to the template.

- [ ] **Step 2: Write a failing test**

Append to `tests/test_localization_integration.py`:

```python
@pytest.mark.asyncio
async def test_log_endpoint_serves_italian_when_user_is_italian(tmp_path):
    """When a user with lang='it' opens /log, the served content_md is
    the Italian translation, not the English original."""
    from datetime import datetime, timezone

    from app.db import utcnow
    from app.models import StrategicLog, StrategicLogTranslation, User

    _, factory, setup = _build_session_factory(tmp_path)
    await setup()

    async with factory() as session:
        session.add(User(id=10, email="it@x", tier="paid", lang="it"))
        slog = StrategicLog(
            generated_at=utcnow(), content_md="# Open\n\nDown 0.4%.",
            tone="INTERMEDIATE", analysis="NORMAL",
        )
        session.add(slog)
        await session.commit()
        session.add(StrategicLogTranslation(
            log_id=slog.id, lang="it",
            content_md="# Apertura\n\nIn calo 0,4%.",
            generated_at=utcnow(), llm_model="m", llm_cost_usd=0.0,
        ))
        await session.commit()
        log_id = slog.id

    # We test the resolver function directly rather than spinning up the
    # FastAPI TestClient — the resolver shape returns the rendered MD.
    from app.routers.pages import _resolve_log_content
    async with factory() as session:
        user = await session.get(User, 10)
        content = await _resolve_log_content(session, log_id, user.lang)
    assert "Apertura" in content
    assert "Open" not in content


@pytest.mark.asyncio
async def test_log_endpoint_falls_back_to_english_when_no_translation(tmp_path):
    """User lang='it' but no IT translation exists → English fallback."""
    from app.db import utcnow
    from app.models import StrategicLog, User

    _, factory, setup = _build_session_factory(tmp_path)
    await setup()

    async with factory() as session:
        session.add(User(id=11, email="it2@x", tier="paid", lang="it"))
        slog = StrategicLog(
            generated_at=utcnow(), content_md="# Open\n\nDown 0.4%.",
            tone="INTERMEDIATE", analysis="NORMAL",
        )
        session.add(slog)
        await session.commit()
        log_id = slog.id

    from app.routers.pages import _resolve_log_content
    async with factory() as session:
        user = await session.get(User, 11)
        content = await _resolve_log_content(session, log_id, user.lang)
    assert "Open" in content
```

- [ ] **Step 3: Run tests to verify they fail**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_localization_integration.py -k log_endpoint -v
```

Expected: 2 FAIL — `_resolve_log_content` doesn't exist yet.

- [ ] **Step 4: Add the resolver and wire it into `log_page` / `log_page_day`**

In `app/routers/pages.py`, add the resolver as a module-level async function:

```python
async def _resolve_log_content(
    session: AsyncSession, log_id: int, lang: str,
) -> str:
    """Return the markdown content of strategic log ``log_id`` in the
    user's preferred language.

    If ``lang`` is ``en`` or no translation exists for the requested
    language, returns the English original. The fallback is silent —
    a missing translation is the expected case for hours where
    translation hasn't yet run."""
    from app.models import StrategicLog, StrategicLogTranslation

    if lang and lang != "en":
        row = (await session.execute(
            select(StrategicLogTranslation)
            .where(StrategicLogTranslation.log_id == log_id)
            .where(StrategicLogTranslation.lang == lang)
        )).scalar_one_or_none()
        if row is not None:
            return row.content_md
    log_row = await session.get(StrategicLog, log_id)
    return log_row.content_md if log_row is not None else ""
```

Then in `log_page` (and `log_page_day` if present), replace the line that pulls `content_md` directly from the StrategicLog row with a call to `_resolve_log_content(session, log.id, cu.user.lang if cu.user else "en")`.

- [ ] **Step 5: Run tests to verify they pass**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_localization_integration.py -v
```

Expected: all 10 tests pass.

- [ ] **Step 6: Commit**

```bash
git add app/routers/pages.py tests/test_localization_integration.py
git commit -m "log: serve translated content when available; English fallback"
```

---

### Task 9: PATCH /api/settings/language endpoint

**Files:**
- Modify: `app/routers/api.py`
- Test: `tests/test_localization_integration.py` (append)

- [ ] **Step 1: Write failing tests**

Append to `tests/test_localization_integration.py`:

```python
@pytest.mark.asyncio
async def test_patch_language_accepts_active(tmp_path):
    """PATCH /api/settings/language accepts 'en' and 'it' and persists."""
    from app.models import User
    from app.routers.api import patch_language_prefs, LanguagePrefsIn
    from app.auth import CurrentUser

    _, factory, setup = _build_session_factory(tmp_path)
    await setup()

    async with factory() as session:
        session.add(User(id=20, email="u@x", tier="paid", lang="en"))
        await session.commit()

    class _P:
        is_admin = False
        def __init__(self, u): self.user = u

    async with factory() as session:
        user = await session.get(User, 20)
        result = await patch_language_prefs(
            payload=LanguagePrefsIn(lang="it"),
            principal=_P(user),
            session=session,
        )
        assert result.lang == "it"

    async with factory() as session:
        user = await session.get(User, 20)
    assert user.lang == "it"


@pytest.mark.asyncio
async def test_patch_language_rejects_wip(tmp_path):
    """PATCH rejects 'es'/'fr'/'de'/'xx' with 400 — ACTIVE_LANGUAGES gate."""
    from fastapi import HTTPException
    from app.models import User
    from app.routers.api import patch_language_prefs, LanguagePrefsIn

    _, factory, setup = _build_session_factory(tmp_path)
    await setup()

    async with factory() as session:
        session.add(User(id=21, email="u2@x", tier="paid", lang="en"))
        await session.commit()

    class _P:
        is_admin = False
        def __init__(self, u): self.user = u

    for bad in ("es", "fr", "de", "xx"):
        async with factory() as session:
            user = await session.get(User, 21)
            with pytest.raises(HTTPException) as exc:
                await patch_language_prefs(
                    payload=LanguagePrefsIn(lang=bad),
                    principal=_P(user),
                    session=session,
                )
            assert exc.value.status_code == 400
```

- [ ] **Step 2: Run tests to verify they fail**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_localization_integration.py -k patch_language -v
```

Expected: 2 FAIL with `ImportError` for `patch_language_prefs` / `LanguagePrefsIn`.

- [ ] **Step 3: Add the endpoint**

In `app/routers/api.py`, near the existing `patch_digest_prefs` (around lines 868-897), add:

```python
from app.services.i18n import ACTIVE_LANGUAGES


# ---------------------------------------------------------------------------
# Settings — language preference
# ---------------------------------------------------------------------------


class LanguagePrefsIn(BaseModel):
    lang: str


class LanguagePrefsOut(BaseModel):
    lang: str


@router.patch("/settings/language", response_model=LanguagePrefsOut)
async def patch_language_prefs(
    payload: LanguagePrefsIn,
    principal: CurrentUser = Depends(require_token),
    session: AsyncSession = Depends(get_session),
) -> LanguagePrefsOut:
    if principal.user is None:
        raise HTTPException(status_code=400, detail="no_user_context")
    lang = (payload.lang or "").strip().lower()
    if lang not in ACTIVE_LANGUAGES:
        raise HTTPException(
            status_code=400,
            detail=f"unsupported language: {payload.lang!r}",
        )
    user = await session.get(User, principal.user.id)
    if user is None:
        raise HTTPException(status_code=404, detail="user_not_found")
    user.lang = lang
    await session.commit()
    return LanguagePrefsOut(lang=lang)
```

(`User` and `BaseModel` are already imported at the top of `app/routers/api.py`. If `ACTIVE_LANGUAGES` import collides with anything else, alias it.)

- [ ] **Step 4: Run tests to verify they pass**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/test_localization_integration.py -v
```

Expected: all 12 tests pass.

- [ ] **Step 5: Commit**

```bash
git add app/routers/api.py tests/test_localization_integration.py
git commit -m "settings: PATCH /api/settings/language with ACTIVE_LANGUAGES gate"
```

---

### Task 10: Settings UI dropdown

**Files:**
- Modify: `app/templates/settings.html`
- Modify: `app/routers/pages.py::settings_page` — pass `user.lang` to the template context

- [ ] **Step 1: Add the language section to settings.html**

In `app/templates/settings.html`, find the existing settings sections (`<details class="settings-section">` blocks). Add a new section next to the email-digest preferences:

```html
<details class="settings-section">
  <summary class="settings-section__head">Language</summary>
  <p class="settings-section__lede">
    Language the AI uses for the strategic log, your daily digest, and
    portfolio commentary. The interface itself stays in English for now.
  </p>
  <div class="settings-row">
    <select id="lang-select" class="settings-select">
      <option value="en" {% if (user.lang or 'en') == 'en' %}selected{% endif %}>English</option>
      <option value="it" {% if (user.lang or 'en') == 'it' %}selected{% endif %}>Italiano</option>
      <option value="es" disabled>Español &middot; coming soon</option>
      <option value="fr" disabled>Français &middot; coming soon</option>
      <option value="de" disabled>Deutsch &middot; coming soon</option>
    </select>
    <span id="lang-status" class="settings-status" aria-live="polite"></span>
  </div>
  <script>
    (function () {
      var sel = document.getElementById('lang-select');
      var status = document.getElementById('lang-status');
      if (!sel) return;
      sel.addEventListener('change', async function () {
        status.textContent = 'saving…';
        try {
          var r = await fetch('/api/settings/language', {
            method: 'PATCH',
            headers: {'Content-Type': 'application/json'},
            body: JSON.stringify({lang: sel.value}),
          });
          if (!r.ok) throw new Error('HTTP ' + r.status);
          status.textContent = '✓ saved';
          setTimeout(function () { status.textContent = ''; }, 1500);
        } catch (e) {
          status.textContent = '✗ failed';
        }
      });
    })();
  </script>
</details>
```

- [ ] **Step 2: Confirm `settings_page` passes `user.lang`**

In `app/routers/pages.py::settings_page`, the template context already includes `user`. The template reads `user.lang` directly from that object. No code change required — the Jinja2 expression `{% if (user.lang or 'en') == 'it' %}` handles old rows whose `lang` field hasn't been populated yet (defensive, post-migration).

If the existing template context does NOT pass the `user` object (it should, based on the digest-prefs section), add it.

- [ ] **Step 3: Manual smoke verification step**

Smoke is deferred to Task 11. No test step here — pure markup + small inline JS.

- [ ] **Step 4: Commit**

```bash
git add app/templates/settings.html
git commit -m "settings: add language dropdown (IT active, ES/FR/DE WIP)"
```

---

### Task 11: Final regression + deploy + manual smoke

**Files:**
- (no code changes — verification only)

- [ ] **Step 1: Full test suite**

```bash
docker compose -f docker-compose.test.yml run --rm test pytest tests/ 2>&1 | tail -5
```

Expected: every previous test plus the new `tests/test_i18n.py` and `tests/test_localization_integration.py` pass. Total should now be ~280 passing.

- [ ] **Step 2: Apply migration to prod DB (requires explicit user approval)**

```bash
docker compose exec app alembic upgrade head
```

Expected: `Running upgrade 0021 -> 0022, localization`.

- [ ] **Step 3: Restart prod app (requires explicit user approval)**

```bash
docker compose restart app
docker compose logs app --tail 30 | grep -E "(Uvicorn|startup complete|ERROR|Traceback)"
```

Expected: `Application startup complete.` cleanly; no tracebacks.

- [ ] **Step 4: Manual smoke — switch a paid test user to Italian**

In a paid-tier browser session, open `/settings`. Confirm the Language dropdown appears with all five options, the English option selected, ES/FR/DE disabled and labelled "coming soon". Pick `Italiano`, confirm the inline `✓ saved` status appears. Refresh — Italian remains selected.

- [ ] **Step 5: Manual smoke — strategic log translation**

Wait for the next hourly `ai_log_job` tick (or trigger via the scheduler/admin). Confirm a row appears in `strategic_log_translations` with `lang='it'`. NOTE: this requires a prod DB read; only run with explicit user approval:

```bash
docker compose exec app python -c "
import asyncio
from sqlalchemy import select
from app.db import get_session_factory
from app.models import StrategicLogTranslation

async def main():
    factory = get_session_factory()
    async with factory() as s:
        rows = (await s.execute(
            select(StrategicLogTranslation).order_by(StrategicLogTranslation.id.desc()).limit(3)
        )).scalars().all()
        for r in rows:
            print(r.id, r.log_id, r.lang, r.llm_model, r.llm_cost_usd, r.content_md[:80])
asyncio.run(main())
"
```

Expected: at least one row with `lang='it'`, `llm_model` containing `deepseek`, `llm_cost_usd` a small positive number.

- [ ] **Step 6: Manual smoke — portfolio analysis**

On the dashboard as the Italian user, click "Analyse" (or whatever triggers `/api/analyze`). Confirm the rendered AI commentary is in Italian.

- [ ] **Step 7: Manual smoke — email digest**

```bash
docker compose exec app python -m app.cli send-test-digest <italian-user-email> daily
```

Expected: digest email lands in Italian, including the subject line.

- [ ] **Step 8: Manual smoke — Edge cases**

- Direct `curl -X PATCH /api/settings/language` with `{"lang": "es"}` → 400.
- Switch user back to English, refresh dashboard — log renders in English again.

---

## Self-Review

**Spec coverage walkthrough:**

- **`users.lang` column with default 'en'** → Task 3 model + Task 4 migration
- **`strategic_log_translations` table** → Task 3 model + Task 4 migration
- **`i18n.LANGUAGES` + `ACTIVE_LANGUAGES`** → Task 1
- **`respond_in_clause()`** → Task 1
- **`translate()` helper** → Task 2 (no-op fast path for `en`/unknown; code-fence stripping; raises on provider failure)
- **`ai_log_job` translation fan-out** → Task 5 (parallel via `asyncio.gather`; per-language failure isolated)
- **Portfolio analysis `lang`-aware system prompt** → Task 6
- **Email digest: shared variant generation, post-translation, (tone, lang) routing** → Task 7
- **`/log` localized fetch with English fallback** → Task 8
- **`PATCH /api/settings/language` with ACTIVE_LANGUAGES gate** → Task 9
- **Settings dropdown with IT active + ES/FR/DE disabled** → Task 10
- **No tier gating on translation** → Task 5 query selects on `User.lang` only, no `tier` filter
- **No retroactive backfill** → not built; only forward-going translations
- **No UI label translation** → out of scope, Task 10 surfaces this in the section copy

**Type / signature consistency:**

- `respond_in_clause(lang: str | None) -> str` — used in Tasks 6, 7. Consistent.
- `translate(client, text, target_lang) -> tuple[str, LogResult]` — used in Tasks 2, 5. Consistent.
- `ACTIVE_LANGUAGES: set[str]` — used in Tasks 5, 9. Consistent.
- `LanguagePrefsIn { lang: str }` / `LanguagePrefsOut { lang: str }` — used in Task 9 only.
- `_resolve_log_content(session, log_id, lang) -> str` — used in Task 8 only.
- `translate_log_for_active_languages(session, log_id) -> None` — used in Task 5 only.

**Note on Task 7:** the digest job is treated as shared content. `_generate_variants` keeps its existing per-tone behaviour unchanged; localization is layered on top via two new module-level helpers (`_translate_variants_for_active_langs`, `_pick_variant`) and a routing change in the per-user send loop. No restructuring of the existing tone-generation path is needed. Translation count per run is `tones × non-en active langs` (today: 3 calls/run) — negligible.