Translation Service

Why it exists

The platform needs multilingual content delivery without duplicating or forking the underlying content model. Translation support creates document-level language variants linked to their source documents while preserving the original schema and content structure.

Use this when

• translating one or more components into multiple languages
• tracking the progress of a bulk translation job
• retrying failed translations
• correcting machine-generated translations manually
• reading translated content in a documentation or website app
• building language-specific document views in the CMS

What it includes

• bulk component and language selection in the CMS
• asynchronous translation jobs with progress tracking
• TensorZero-backed document translation
• automatic skipping of translations that are already current
• deduplication of identical active translation jobs
• recovery of active job progress after CMS navigation
• retry controls for failed translations
• persistent target-language preferences
• manual translation correction through the patch endpoint
• language-aware document retrieval
• source hashes for detecting stale translations
• translation-aware database columns and indexes

Core workflow

1. Open the Components page and select Send to translation.
2. Choose one or more components and target languages.
3. Review the estimated number of translations and queue the batch.
4. The translation manager loads the published source documents and skips translations whose source hash is already current.
5. Remaining translations are processed asynchronously through TensorZero.
6. Monitor queued, completed, skipped, and failed translations from the CMS.
7. Retry failed translations when necessary.
8. Correct translated content manually when machine-generated output needs adjustment.
9. Read translated variants through language-aware schema and document APIs.

Translation jobs

Submitting a batch creates a translation job. A job records:

• selected components and languages
• source documents processed
• translations scheduled
• translations skipped because they are already current
• translations completed
• translations failed
• current job status

Submitting the same selection while an equivalent job is active reconnects to the existing job instead of creating duplicate work.

The CMS stores the active job identifier locally so progress can be restored after navigation. Translation job state is currently held in memory by the translation manager and is cleared when the service restarts. Deploy the service as a single instance or use sticky routing so job submission and status requests reach the same process.

Stale translation detection

Each translated document stores a hash of the source document’s published content at the time it was translated.

When another translation batch is submitted:

• matching hashes indicate that the translation is current and can be skipped
• different hashes indicate that the source changed and the translation should be regenerated

This makes bulk translation safe to run repeatedly without retranslating unchanged content.

API endpoints

• POST /translation — queue translations for one or more components
• GET /translation-jobs/{job_id} — read translation job status and progress
• PATCH /translations — manually correct translated content

System surfaces

• CMS bulk translation dialog
• CMS translation job status and recovery controls
• translation manager API and background workers
• TensorZero translation integration
• CMS language-specific document views
• docs app language-aware content loading
• translation persistence and source-hash tracking