# Polyglot Relay: An Authenticated Real-Time Translation Service

## PURPOSE
A small service that lets a client app send a spoken English phrase and receive
a target-language translation plus an optional pronunciation hint — the exact
flow in OpenAI's UK demo when the user says "please tell my Spanish friend I
will sell my guitar to him for no less than 150 pounds" and, earlier, gets
gently corrected on "buenos días". The service keeps an auditable record of
every translation request so you can see what was said, in which direction, and
how it was phrased.

## WHY THIS MATTERS
Real-time voice translation is the transcript's most measurable capability, and
the "Did I say that right?" exchange is the most instructive one: translation
alone is not enough, learners want feedback. That means each request carries a
language pair, an optional learner-correction flag, and an outcome you can
audit later — identity, rate limiting, and persistence become part of the
feature, not an afterthought.

## HOW TO BUILD
1. FastAPI app; `httpx.AsyncClient` as the single outbound transport.
2. SQLAlchemy 2.0 models: `ApiClient` (hashed key), `TranslationSession`,
   `Utterance`.
3. Bearer-token dependency that hashes the presented key and looks it up.
4. Translation call behind a `Translator` protocol; a `StubTranslator` returns
   deterministic output for tests and the "buenos días" correction note.
5. Postgres in production, SQLite for the lab; `pytest` with `respx` mocks.

```python
async def translate(req: TranslateIn, db: Session, client: ApiClient):
    translator = StubTranslator() if settings.offline else HttpTranslator()
    result = await translator.render(req.text, req.target_lang)
    db.add(Utterance(session_id=req.session_id, source=req.text,
                     target=result.text, pronounced_ok=result.ok))
    db.commit()
    return result
```

## WHEN TO USE IN PRODUCTION
Use it for multilingual customer support, travel and hospitality kiosks,
language-learning drills, and internal tools where staff serve non-native
speakers. Do NOT use it for legally binding or medical translation without a
human in the loop, for languages your provider does not support, or when the
deployment requires audio to stay on-device (a cloud relay leaks content).

## HOW IT HELPS STUDENTS
API keys and hashing, async HTTP with retries/timeouts, ORM modelling,
dependency injection, and mocking third parties in tests. It is the first
project where "the model" is a dependency you must guard, not the whole product.

## STARTER CODE
See `starter/main.py`: FastAPI app with the auth dependency, SQLAlchemy models,
and the deterministic translator stub.
