Translation Engine

Translation Engine

Section: Pipeline · Diarization-and-Speaker-Management · Home · Text-to-Speech

The Translation Engine converts timed text segments from a source language to a target language. It sits between ASR and TTS. Routes include local ONNX-backed models and optional cloud providers. Shipping lanes stay commercial-safe via the model manifest. Domain concepts include translated segments, revisions, and language routing results.

Architecture and Workflow

The translation system is designed around a strict layered dependency model where orchestration occurs in the Application layer, while specific implementations reside in Infrastructure (for cloud) or Inference.Onnx (for local).

Translation Pipeline Flow

The translation workflow follows a structured sequence where segments are prepared, routed to a specific engine, and then processed into immutable snapshots.

flowchart TD
    Start[Start Translation Stage] --> Prepare[Prepare Translation Request]
    Prepare --> Route[IRuntimePlanner Selects Engine]
    Route --> Direct[Direct Route: e.g. Opus-MT]
    Route --> Pivot[Pivot Route: e.g. MADLAD-400]
    Direct --> Execute[Execute TranslateAsync]
    Pivot --> Execute
    Execute --> Metadata[Report Execution Metadata]
    Execute --> Result[Return TranslatedTextSegments]
    Result --> End[Update Pipeline Status]

Loading

The diagram shows the logic flow from initiating a translation stage to selecting a routing path and executing the engine.

Key Components

Component	Responsibility	File Path Reference
ITranslationEngine	The primary interface for all translation implementations.	src/Trackdub.Infrastructure/Translation/GeminiCloudTranslationEngine.cs
IRuntimePlanner	Determines routing (Direct vs. Pivot) and execution provider (CPU, GPU, etc.).	Inference / Composition planner types
TranslationWorkflow	Orchestrates the translation stage within the application pipeline.	src/Trackdub.Application/Transcripts/TranslationWorkflow.cs
GeminiCloudTranslationEngine	A specific implementation utilizing the Google Gemini Cloud API.	src/Trackdub.Infrastructure/Translation/GeminiCloudTranslationEngine.cs

Engine Implementation: Gemini Cloud Example

Cloud-based engines like GeminiCloudTranslationEngine implement ITranslationEngine along with reporting interfaces to provide telemetry on model usage and bootstrap details.

Sequence of a Cloud Translation Request

The following sequence diagram illustrates how a cloud engine interacts with external APIs while maintaining internal state reporting.

sequenceDiagram
    participant App as Application Layer
    participant Eng as GeminiCloudTranslationEngine
    participant API as Gemini API
    
    App->>Eng: TranslateAsync(TranslationRequest)
    activate Eng
    Eng->>Eng: ResolveApiKeyAsync()
    Eng->>API: POST /generateContent (JSON Array)
    API-->>Eng: 200 OK (Translated JSON)
    Eng->>Eng: TryParseTranslationArray()
    Eng->>Eng: Update LastExecutionMetadata
    Eng->>Eng: Update LastExecutionSummary
    Eng-->>App: IReadOnlyList<TranslatedTextSegment>
    deactivate Eng

Loading

Interaction between the Application layer and the Gemini Cloud Translation Engine.

Prompt Engineering and Safety

The engine uses specific system instructions to ensure the LLM returns only valid JSON arrays without markdown or explanations, preserving the order and count of segments. It also reports TranslationRoutingKind.Direct for supported direct language pairs.

Model Governance and Routing

Translation routing is strictly manifest-driven. The system uses a bundled-models.manifest.json to track capabilities and licensing.

Routing Logic

• Direct Route: Used for specific language pairs supported by a single model (e.g., Opus-MT).
• Pivot Route: Used when no direct model exists, often routing through a larger multilingual model like MADLAD-400.
• Commercial Safe Mode: When enabled, the IRuntimePlanner blocks any route that involves a model marked as non-commercial in the manifest.

Configuration Requirements

Cloud engines require specific environment variables for API keys to function:

• GEMINI_API_KEY or TRACKDUB_GEMINI_API_KEY for Gemini.
• Cloud providers are accessed via an ICloudApiKeyProvider.

Domain Concepts

The translation domain maintains several core types to ensure data integrity across the pipeline:

• TranslatedTextSegment: Contains the translated string mapped to original start and end timestamps.
• TranslationRequest: A container for segments, source language, and target language.
• TranslationExecutionMetadata: Records the provider, model ID, model alias, and routing kind used for a specific run.

Summary

The Translation Engine facilitates cross-platform, local-first translation by abstracting provider-specific logic behind the ITranslationEngine interface. By leveraging a manifest-driven IRuntimePlanner, Trackdub ensures that translation requests are handled by the most appropriate model—be it a local ONNX model or a cloud service—while strictly adhering to commercial licensing constraints and preserving segment timing integrity.