> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learnway.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Content Workflows & Multilingual Translation

> Architecture of AI Quiz Studio automated question generation and the two-step hybrid multilingual translation engine for African regional languages.

# AI Content Workflows & Multilingual Translation

High-quality content authoring and localized accessibility are essential pillars of LearnWay's mission to build the learning infrastructure for Africa's AI era. This document covers the automated **AI Quiz Studio** and the **Multilingual Translation Subsystem** inside `learnway-ai-service`.

***

## 1. AI Quiz Studio (`AiQuizStudioService`)

The AI Quiz Studio automates the synthesis of interactive, pedagogical multiple-choice questions (MCQs) directly from course lesson transcripts, documentation, or domain topics.

```mermaid theme={null}
flowchart TD
    subgraph Inputs["📥 Curriculum Ingestion"]
        LessonDoc["Lesson Content / Slide Text"]
        TopicPrompt["Topic Name & Target Difficulty (Beginner/Intermediate/Advanced)"]
        Language["Target Language (English, French, Swahili, etc.)"]
    end

    subgraph StudioEngine["⚡ AI Quiz Studio Engine (learnway-ai-service)"]
        PromptAssembler["Bloom's Taxonomy Prompt Builder"]
        GeminiExecution["Google Gemini 2.5 Flash\n(thinkingBudget: 0)"]
        DistractorValidator["Distractor & Option Label Sanitizer"]
        QuestionRepository["Save to ai_quiz_studio_questions"]
    end

    subgraph Bank["📚 Question Bank & Battle Pools"]
        PvPPools["Real-time 1-v-1 Quiz Battle Questions"]
        LessonQuizzes["End-of-Lesson Checkpoint Quizzes"]
        ContestPools["Time-Boxed Tournament Assessments"]
    end

    LessonDoc --> PromptAssembler
    TopicPrompt --> PromptAssembler
    Language --> PromptAssembler
    PromptAssembler --> GeminiExecution
    GeminiExecution --> DistractorValidator
    DistractorValidator --> QuestionRepository
    QuestionRepository --> PvPPools
    QuestionRepository --> LessonQuizzes
    QuestionRepository --> ContestPools
```

### Distractor Quality & Label Sanitization

To ensure questions test deep conceptual understanding rather than pattern memorization, the synthesis pipeline enforces strict rules:

* **Plausible Distractors**: Generates 3 realistic incorrect answers (distractors) reflecting common misconceptions.
* **Label Normalization**: Strips hardcoded prefixes (such as `"A)"`, `"B)"`) so questions can be dynamically shuffled in real-time PvP quiz battles without revealing the answer order.
* **Detailed Explanations**: Generates concise pedagogical rationales explaining *why* the correct answer is right and *why* distractors are invalid.

***

## 2. Two-Step Hybrid Multilingual Translation Engine (`AiTranslationService`)

To make advanced technical curricula accessible across diverse African linguistic landscapes, LearnWay combines the structural accuracy of **Google Cloud Translation API** with the contextual nuances of **Google Gemini**.

```mermaid theme={null}
flowchart LR
    SourceText["Original Lesson Markdown / HTML"] --> Step1
    
    subgraph Step1["Step 1: Base Machine Translation"]
        CloudTranslate["Google Cloud Translate v2"]
    end
    
    Step1 --> BaseTranslated["Draft Translation"]
    BaseTranslated --> Step2
    
    subgraph Step2["Step 2: Gemini Contextualization"]
        GeminiEngine["Google Gemini 2.5 Flash\n• Preserves Code & Markdown Syntax\n• Adapts Regional African Idioms\n• Preserves Technical Keywords"]
    end
    
    Step2 --> Sanitizer["Syntax & XSS Sanitizer"]
    Sanitizer --> DB[("Translated Content Repository\n(PostgreSQL)")]
```

### Supported Regional Languages & Dialects

The translation pipeline natively supports major African and international languages:

* **Swahili (`sw`)** (East Africa)
* **Yoruba (`yo`)** (West Africa)
* **Hausa (`ha`)** (West/Central Africa)
* **Igbo (`ig`)** (West Africa)
* **French (`fr`)** (Francophone Africa)
* **Portuguese (`pt`)** (Lusophone Africa)
* **Spanish (`es`)** & **Arabic (`ar`)**

### Technical Syntax & Code Preservation

Translating technical programming courses requires strict preservation of code blocks, variable names, and HTML formatting:

1. **Tag & Token Masking**: Code blocks (`fenced code`), inline tags (`<code>`, `<span>`), and LaTeX formulas are shielded before translation.
2. **Contextual Polishing**: Gemini reviews the draft translation to ensure technical idioms sound natural without translating reserved keywords (such as `import`, `function`, `async/await`, or `contract`).
3. **Automated Content Caching**: Translated modules are persisted in `translated_contents` to eliminate recurring translation latency and LLM costs.