# How a chapter translation reports its own progress

A chapter translation takes longer than a single request should. A chapter can hold hundreds of paragraphs, and each batch of them costs one call to a language model. If the browser waited for the whole chapter, the reader would stare at a spinner for minutes with no way to tell whether anything was happening. So the server does not return one answer at the end. It returns a stream of frames, one batch at a time, and the reader watches the chapter fill in as the frames arrive.

## A batch is the unit the reader hears about

The stream speaks in batches, not paragraphs and not chapters. Each batch is a group of paragraphs sent to the model in one call — in follow mode, the mode that translates as you read, a batch holds at most 500 characters or 12 paragraphs, whichever comes first. A whole-chapter run uses bigger batches, up to 3000 characters or 60 paragraphs, because nobody is waiting on the next line.

Six kinds of frame go down the wire, each with a name in an `event:` line and a JSON body in a `data:` line:

- `batch_start` — sent before the model is even called for that batch. It lists the paragraph ids in the batch, flags any already-failed paragraphs inside that range, and carries the batch size and window so the reader can work out its own thresholds.
- `batch` — the translations for that batch, each paragraph with its id, its original text, its translation, and a status. A failed paragraph is not hidden: it arrives in the same frame with a failure status, and the reader marks it as failed in place.
- `progress` — two numbers: how many paragraphs this chapter holds, and how many this run has attempted so far.
- `log` — short human-readable lines for a console panel: batch finished with so many right and so many failed, task finished with so many covered out of so many.
- `done` — the closing frame, with a status of `full` or `partial`.
- `error` — a terminal frame. When it arrives, the stream is over and no `done` follows.

The reader does not use a generic event feed for this. It opens the stream with a plain fetch request and reads the response body itself, splitting on blank lines. There are no frame ids, and nothing on either side remembers which frames a particular connection already received.

## The first frame arrives before any translation exists

The reason `batch_start` exists is a failure that has nothing to do with translation quality. Before it was added, the browser's fetch sat pending with no response at all until the first model call came back, and a long first batch looked exactly like a dead request. Now the server sends `batch_start` before calling the model, so the reader knows within milliseconds that the run is alive and which paragraphs are in flight. For paragraphs currently on screen, it inserts loading placeholders right then; a paragraph the reader has not scrolled to gets no placeholder, because there is nothing to show it in yet.

Two response headers back this up: `Cache-Control: no-cache` and `X-Accel-Buffering: no`, which tell proxies not to hold the frames back until the response completes. Buffering would defeat the whole design — a stream that arrives all at once at the end is just a slow request with extra steps.

There is one thing the stream does not do: it sends no heartbeat. Between frames there is silence, and silence is normal. A frame only appears when a batch finishes, and a batch takes as long as one model call takes. A reader that mistakes that silence for a stalled connection and retries will start a second run while the first is still working.

## Progress counts this run, not the chapter

The `progress` frame is easy to misread. Its attempted count only covers the current run: it starts at zero when the stream opens and grows by one batch at a time. It counts paragraphs attempted, including ones that failed, not paragraphs successfully translated. And it says nothing about paragraphs translated by earlier runs.

The chapter-wide truth lives elsewhere. Every `batch`, `progress`, and `done` frame carries a `tr_version` stamp, which is simply the latest write time among that chapter's saved translations for the target language. It is a freshness stamp, not a sequence number — it tells the reader whether the chapter's saved state moved, not which frame it is on. When the reader needs the real state of a chapter — which paragraphs are translated, which failed, which were never attempted — it asks a separate plain request, the chapter status endpoint, which returns those three lists plus the same version stamp.

## Done does not always mean finished

`done` with status `full` means every translatable paragraph in the chapter now has a saved record, whether the translation succeeded or failed. `done` with status `partial` means some paragraphs are still uncovered. Partial is the normal ending for an interrupted run, not an error: if a whole batch fails with a network error, the server stops rather than burning more calls on the following batches, and then closes with `done`/`partial`, leaving the remaining paragraphs for a later run.

An `error` frame is different. It means the run cannot continue at all — the usage allowance ran out mid-chapter, or the model call itself failed — and it ends the stream immediately, with no `done` after it. The paragraphs translated before that point are already saved, so the next run picks up after them rather than starting over.

## A dropped connection replays nothing

This is the part that surprises people who are used to feeds that resume. The stream has no replay. There are no frame ids, the browser does not send a last-received position, and the server keeps no per-connection backlog. If the connection drops halfway through a batch, the frames already delivered stay delivered, the frames not yet sent are gone, and a new connection starts a new stream from scratch.

What saves the reader from losing work is not the stream but the database behind it. Before a new stream starts, the reader re-asks the chapter status endpoint, and the server builds its work list from saved records: paragraphs already translated are skipped, paragraphs that failed permanently are skipped, paragraphs that failed in a retryable way are retried only after a cooldown. So a reconnected run translates only what is still missing. The catch is that it does not re-send what is already done — a fresh stream contains only new work, and the reader is expected to already have the earlier paragraphs on screen or to know from the status check that they exist.

There is exactly one exception, and it covers the narrowest case: the batch that was in flight when the reader itself aborted. When the reader stops a stream on purpose — the reader scrolled on, or changed chapter — it records the ids from the last `batch_start` it saw. The next stream it opens sends those ids back as a stash list, and the server checks the database: any stashed paragraph that did land safely gets re-sent as a `batch` frame before the main flow begins, so a translation that finished server-side but never reached the screen is not lost. That rescue runs for at most five abort cycles per paragraph; after that the paragraph drops off the stash list, and if it was translated it simply stays in the saved state for the status check to report.

Chat works the other way round, and the contrast shows why the granularity matters. A chat answer streams token by token — `token` frames carrying text fragments, plus `reasoning`, `tool_call`, and `tool_result` frames along the way — so a dropped answer is visible in pieces as it arrives. And when a chat connection dies, the server writes the partial answer to the session from its own ledger, marked stopped, so a refresh shows what was already said. Translation cannot do that for a paragraph mid-batch, because a batch is only written when the whole model call returns. The unit of progress is the batch, and a batch either lands complete or not at all.

So the stream only narrates one run while it happens: what batch is in flight, what just landed, how far this run has got, and whether it ended whole or short. Everything durable — which paragraphs are translated, which failed, what the chapter looks like now — lives in saved records, and the next run starts from there.
