EN
Smiling cotton character from the original Cotton logo, with the background and lettering removed
Back to the hall

Cotton

Translation workflow

Turning generated translations into reviewable results.

A translation workflow for game dialogue.

2026.05.06 — 2026.05.26

Work project · translation processing, judgment and review path

  • Web appImplemented · development

Scores, retries and human review, each at its own boundary.

Generation and judgment share the glossary, and a hard-gate failure reported by the judge model cannot be offset by the mean score. Intermediate translation and judgment states are recorded, retry and cost limits are kept apart from exhausted credentials, and stalled jobs return to the queue or to review depending on the cause.

This work project connects translation generation, model-reported quality judgment, retries and human review in one flow.

From the start of the repository to the work confirmed during the engagement

A web app of translation editing and approval screens, an API and a job worker, running in the development environment.

Judgment flow map · from private implementation records
Cotton translation judgment · retry · recoveryThe API commits the source text and target locales to the database, then queues a job per target locale. A worker locks the row, checks the attempt, creates the draft and progress state, generates a translation with the glossary, and calls a judge model separately with the same glossary. The translation (Tx1) and the judgment with its evidence (Tx2) are recorded in separate transactions. Code aggregates the judgment so a hard-gate failure is not offset by the mean: a pass is finalized, a failure gets another turn, the turn or cost limit sends it to human review, and a quota or auth signal stops spending and waits for a credential check. A stale sweep looks at up to 200 drafts older than 10 minutes: one with attempts left but missing from the queue is re-queued, and one with attempts used up goes to review or the credential check depending on whether a result exists.Source · target localesStored segmentsHuman reviewneeds_review · not approvalCredential checkneeds_credentialAPI · job registrationQueue after commitJob queueBullMQ · job IDJob entryRow lock · attempt checkGlossary · contextWorkspace glossaryTranslation turnGenerate · model callJudge model call · parseVerdict rulesHard gate · weighted meanRetry · spendingTurns · cost · quotaTranslation stateDraft · progressTranslation · judgment rowsState · call logFinalizationFinal transactionQueue checkCompare queue stateStale sweepDrafts over 10 min · max 200Input · queueGeneration · judgmentState · acceptanceRecovery · human decision1source2 after commit · Queue after commit → BullMQ · job ID23 deliver job · BullMQ · job ID → Row lock · attempt check34progress row5attempt allowed1glossary2 same glossary · Workspace glossary → Judge model call · parse23Tx1 · translation4Tx2 · judgment5 scores · gates · Judge model call · parse → Hard gate · weighted mean56verdict7pass8final record1verdict2next turn3limit · abort4quota · auth5manual resume1stale draft2below limit3re-queue4 result exists · Drafts over 10 min · max 200 → Human review45no result

Registration → entry

Queued after the database commit; a worker locks the row, checks the attempt and creates the draft.

  1. Source · target localessourceQueue after commitAPI · job registration

    Source segments and the project’s target locales are stored in the database. Customer data is not shown.

  2. Queue after commitAPI · job registrationafter commitBullMQ · job IDJob queue

    After the database commit, a job with a request-scoped ID is queued per active target locale. If queueing fails, only a warning is logged and the commit is not rolled back (no atomic outbox), which is why the stale sweep exists.

  3. BullMQ · job IDJob queuedeliver jobRow lock · attempt checkJob entry

    BullMQ hands the job to a worker asynchronously.

  4. Row lock · attempt checkJob entryprogress rowDraft · progressTranslation state

    Inside a transaction the progress row is locked and a draft translation is created. Automatic retries of finalized or credential-paused jobs are skipped; manual requests are handled separately.

  5. Row lock · attempt checkJob entryattempt allowedGenerate · model callTranslation turn

    The attempt count goes up by one within its limit, then the translation turn starts.

Generate → judge → finalize

Generation and judgment use the same glossary; the translation and the judgment are recorded separately, and code aggregates the judgment before finalizing.

  1. Workspace glossaryGlossary · contextglossaryGenerate · model callTranslation turn

    The workspace glossary and context are looked up and passed to generation.

  2. Workspace glossaryGlossary · contextsame glossaryJudge model call · parseTranslation turn

    The judgment gets the same glossary constraints.

  3. Generate · model callTranslation turnTx1 · translationTranslation · judgment rowsTranslation state

    The model is called directly or through an en-US pivot, and the call, event and progress are written in one transaction. If the job runs again after a crash, the translation call and its cost can repeat.

  4. Judge model call · parseTranslation turnTx2 · judgmentTranslation · judgment rowsTranslation state

    Judge scores and evidence are inserted once per translation and turn; a duplicate finds the existing row, and citations are written only on the first insert. Not the same transaction as the translation.

  5. Judge model call · parseTranslation turnscores · gatesHard gate · weighted meanVerdict rules

    The judge model’s answer is parsed into per-dimension scores and gate results. Whether the glossary passed is what the judge model reports.

  6. Hard gate · weighted meanVerdict rulesverdictTurns · cost · quotaRetry · spending

    Any reported hard-gate failure means a zero and a fail; only then are the weighted mean and per-dimension thresholds applied. The overall threshold of 8.0 is a configuration default, not an observed translation quality.

  7. Turns · cost · quotaRetry · spendingpassFinal transactionFinalization

    A pass is finalized as translated.

  8. Final transactionFinalizationfinal recordState · call logTranslation state

    Candidate, state, score and turns are finalized, and progress finalized plus the state log are written in one transaction. A translation-complete event is emitted only for translated.

Retry · spending limits

No pass means another turn; a limit means human review; quota or auth stops spending and waits for an operator to resume.

  1. Hard gate · weighted meanVerdict rulesverdictTurns · cost · quotaRetry · spending

    Any reported hard-gate failure means a zero and a fail; only then are the weighted mean and per-dimension thresholds applied. The overall threshold of 8.0 is a configuration default, not an observed translation quality.

  2. Turns · cost · quotaRetry · spendingnext turnGenerate · model callTranslation turn

    A translation that does not pass is generated again with the previous translation and critique. Even a hard-gate failure can be retried first rather than going straight to a person.

  3. Turns · cost · quotaRetry · spendinglimit · abortHuman review

    When the turns run out or the cost ceiling is reached, the job is finalized as needs_review. Finalized means processing ended, not that a person approved it.

  4. Turns · cost · quotaRetry · spendingquota · authCredential check

    A quota or auth signal stops spending and sets needs_credential. There is no automatic switch to another account or provider. Transport errors without a halt signal go back to BullMQ retry.

  5. Credential checkmanual resumeBullMQ · job IDJob queue

    An operator who has checked the credentials restarts explicitly.

Stale job recovery

Old drafts are split by reason: missing from the queue means re-queue, attempts used up means a human decision.

  1. Draft · progressTranslation statestale draftDrafts over 10 min · max 200Stale sweep

    Up to 200 candidates that have been drafts for over 10 minutes are read, oldest first. The query takes no lock and updates and logs run as separate statements, so this is not described as a race-free batch.

  2. Drafts over 10 min · max 200Stale sweepbelow limitCompare queue stateQueue check

    With fewer attempts than the limit (3), the job is compared with the active, waiting, delayed and prioritized queue states. In code the attempts-exhausted branch comes before this queue check.

  3. Compare queue stateQueue checkre-queueBullMQ · job IDJob queue

    If the job is not in the queue, it is queued again. The API uses IDs with a request suffix while the sweep looks for the segment and locale ID, so it is not described as matching every in-flight request.

  4. Drafts over 10 min · max 200Stale sweepresult existsHuman review

    With all 3 attempts used and a translation result present, the job goes to needs_review.

  5. Drafts over 10 min · max 200Stale sweepno resultCredential check

    With all 3 attempts used and no result, the job goes to needs_credential.

Every connection at the same weight. Pick a flow to highlight only its path, with numbered steps.

  • Solid · direction of input, results and records
  • Dashed · run, judgment, request
  • Long dots · observation and reporting, apart from judgment
  • Short dashes · failure, stop, limit
  • Heavy black line · the selected flow; numbers give the order
  • Box · code or state boundary, named in its header
  • Inner chip · a component of that boundary
  • Dotted box · outside that boundary
  • Orange outline · where a model decides
  • Generation · spending · finalization
  • Entry · verdict rules · sweep
  • Queue · state · records
  • Registration · queue check

Drawn from private implementation and development records. Customer data and code paths are not shown.

One sweep
May 26, 2026, one development-environment sweep cycle: 200 checked, 106 state transitions, 2 re-queued. A state transition is not a successful translation, and the split of the 106 by destination state is not recorded.
Why not exactly once
Records are written without duplicates, but if a job runs again after a crash, model calls and their cost can repeat. The concurrency limit is per process, not cluster-wide.
Scope of the verdict
Keeping a mean from covering a glossary failure is an aggregation rule over reported gates. It does not prove that every banned term is found or that quality is native-level.