Quality And Review

This document describes the translation-quality, review, and memory-governance behavior that is implemented in the repository today.

Related Docs

• Documentation Index
• Jobs And Workflow
• Translation And Retrieval
• API Reference

Segment Verification States

apps/jobs/models.py defines these verification states for translation results:

• memory_reused
• glossary_verified
• ai_verified
• needs_review
• human_verified
• blocked
• inconsistent_with_memory
• inconsistent_with_glossary

These states are surfaced through job statistics and the verification-results API.

Immediate Rule-Based Checks

services/translation/quality.py runs rule-based checks for each translated segment.

Current checks include:

• placeholder integrity
• number consistency
• glossary compliance for required terms
• disallowed glossary target detection
• consistency with the best exact approved-memory match
• policy flags such as strict_review_required and low_resource_mode

Current state assignment behavior is:

Condition	Resulting state
Placeholder mismatch	blocked
Exact approved-memory conflict	inconsistent_with_memory
Mandatory glossary missing or disallowed term present	inconsistent_with_glossary
Approved memory was reused directly	memory_reused
strict_review_required is true or numbers do not match	needs_review
Glossary evidence exists and checks pass	glossary_verified
None of the above	ai_verified

Document-Level QA

After segment-level verification, services/translation/document_qa.py evaluates document-wide consistency.

Current document-level checks look for:

• repeated source segments producing inconsistent target output
• repeated glossary terms missing their approved target rendering
• inconsistent abbreviation rendering across the document
• inconsistent unit rendering across repeated segments

If document-level QA finds issues, the workflow can strengthen the stored verification state for affected segments and raise the job's review pressure during finalization.

Job-Level Outcome Rules

During QA finalization, the workflow writes a qa_report artifact and then sets job status based on verification outcomes:

• any blocked segment makes the job blocked
• any remaining review-required or inconsistency state makes the job needs_review
• otherwise the job advances to reassembly_pending

TMX Review Workflow

Export

POST /api/v1/jobs/{job_id}/tmx-export:

• requires existing translation results
• creates a review_tmx artifact
• creates a ReviewSession with status exported

Import

POST /api/v1/jobs/{job_id}/tmx-import:

• requires an uploaded TMX file
• validates job id, document version id, language pair, and stable anchors
• updates translation results with reviewed target text
• marks changed segments as human_verified
• leaves unchanged segments in their existing verification state unless the TMX explicitly carries verificationStatus=human_verified
• records reviewer metadata and changed-segment count on the review session and job metadata
• creates reviewed CandidateMemoryEntry rows from the imported targets
• moves the job to reassembly_pending only when the post-import verification states no longer require review or block delivery

When async workflow is off, TMX import can reassemble immediately. When async workflow is on, the import path can dispatch reassembly instead.

Candidate And Approved Memory

The repository keeps memory in two explicit layers:

• CandidateMemoryEntry
• ApprovedMemoryEntry

Current memory-governance behavior:

• TMX import creates reviewed candidate memory entries
• candidate entries keep source scope and language-pair information
• promotion into approved memory is an explicit API action through POST /api/v1/memory/promotions
• approved-memory entries are then eligible for exact and fuzzy reuse in later jobs

Replay Packages

Replay packages are built through POST /api/v1/jobs/{job_id}/replay.

The replay ZIP currently contains:

• reviewed TMX
• unit map JSON
• document manifest JSON
• job manifest JSON
• QA report JSON
• reassembly manifest JSON

Quality Signals Exposed By The API

The current API surface exposes quality information through:

• GET /api/v1/jobs/{job_id}/stats
• GET /api/v1/jobs/{job_id}/verification-results
• GET /api/v1/projects/{project_code}/review-coverage
• GET /api/v1/jobs/{job_id}/compare?other_job_id=...