StillHammer/Class_generator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
fe7153d28b
Class_generator/english_exemple_ultra_commented.json
StillHammer fe7153d28b Fix compatibility system and improve UX 
- Add intelligent content-game compatibility system with visual badges
- Fix Adventure Reader to work with Dragon's Pearl content structure
- Implement multi-column games grid for faster navigation
- Add pronunciation display for Chinese vocabulary and sentences
- Fix navigation breadcrumb to show proper hierarchy (Home > Levels > Content)
- Add back buttons to all navigation pages
- Improve JSONContentLoader to preserve story structure
- Add comprehensive debugging and diagnostic tools

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-18 19:29:21 +08:00

2224 lines
133 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

{
// ========================================================================================================
// ========================================================================================================
// EDUCATIONAL CONTENT MODULE SPECIFICATION
// COMPLETE REFERENCE IMPLEMENTATION
// ========================================================================================================
// ========================================================================================================
//
// This JSON file serves as the definitive specification and reference implementation for educational
// content modules used in language learning applications. It demonstrates EVERY possible field,
// parameter, and configuration option available in the system.
//
// CRITICAL IMPLEMENTATION NOTES FOR AI SYSTEMS:
// =============================================
// 1. FIELD OPTIONALITY: Unless explicitly marked as "REQUIRED", every single field in this specification
// is OPTIONAL. AI systems and game engines MUST be designed to gracefully handle missing fields.
// Do NOT crash or throw errors when fields are absent - instead, adapt functionality based on
// available data richness.
//
// 2. PROGRESSIVE ENHANCEMENT: This specification follows a progressive enhancement model. Basic games
// can work with minimal data (just translations), while advanced features unlock as more data
// becomes available. AI systems should detect data richness and enable appropriate features.
//
// 3. BACKWARD COMPATIBILITY: This format maintains 100% backward compatibility with simpler formats.
// Legacy content using old structures will continue to work without modification.
//
// 4. EXTENSIBILITY: New fields and sections can be added without breaking existing implementations.
// AI systems should ignore unknown fields and continue processing known data.
//
// 5. VALIDATION: Before processing, AI systems should validate the basic structure but should NOT
// fail on missing optional fields. Use default values and graceful degradation.
//
// ========================================================================================================
// ========================================================================================================
// CORE METADATA SECTION
// ========================================================================================================
// This section contains essential identification and configuration data that every content module
// MUST provide. These fields are used for content discovery, compatibility assessment, and basic
// system functionality. Without these core fields, the content module cannot be processed.
// REQUIRED: Unique identifier for this content module
// SPECIFICATION: Must be lowercase, use underscores for spaces, contain only alphanumeric characters
// USAGE: Used as primary key in databases, file naming, URL generation, and cross-references
// VALIDATION: Must be unique across all content modules in the system
// AI SYSTEMS: Use this for caching, indexing, and relationship mapping between modules
"id": "english_class_demo_complete_example",
// REQUIRED: Human-readable display name for this content module
// SPECIFICATION: Should be concise but descriptive, maximum 100 characters recommended
// USAGE: Displayed in user interfaces, content browsers, and selection menus
// LOCALIZATION: This is in the original language; translations may be provided separately
// AI SYSTEMS: Use for search indexing, content recommendations, and display purposes
"name": "English Class Demo - Complete Example",
// REQUIRED: Brief description explaining what this content module contains and teaches
// SPECIFICATION: Should be 1-3 sentences, maximum 300 characters, clear and informative
// USAGE: Shown in content previews, tooltips, and selection interfaces
// SEO: Should contain relevant keywords for content discovery
// AI SYSTEMS: Use for content categorization, similarity matching, and recommendation algorithms
"description": "Comprehensive example showcasing all content structure possibilities",
// REQUIRED: Difficulty level on a standardized 1-10 scale
// SPECIFICATION: Integer values only, standardized meanings:
// 1-2: Absolute beginner (first words, basic greetings)
// 3-4: Beginner (simple sentences, basic grammar)
// 5-6: Intermediate (complex sentences, intermediate grammar)
// 7-8: Advanced (nuanced language, advanced concepts)
// 9-10: Native/Expert level (idioms, cultural subtleties, professional language)
// USAGE: Used for content filtering, prerequisite checking, and adaptive difficulty
// AI SYSTEMS: Critical for content sequencing and personalized learning path generation
"difficulty": 6,
// REQUIRED: ISO 639-1 language code for the source/original language of the content
// SPECIFICATION: Two-letter lowercase ISO code (en, fr, es, de, etc.)
// USAGE: Determines the source language for all "original" fields throughout the module
// LOCALIZATION: Enables proper text-to-speech, spell checking, and grammar analysis
// AI SYSTEMS: Essential for language-specific processing and cross-language content mapping
"original_lang": "english",
// REQUIRED: ISO 639-1 language code for the user's native language (translation target)
// SPECIFICATION: Two-letter lowercase ISO code, determines translation language
// USAGE: Defines the language for all "userLanguage" fields in the module
// PERSONALIZATION: Allows system to adapt content to user's native language
// AI SYSTEMS: Used for translation validation, cultural adaptation, and localized feedback
"user_lang": "french",
// OPTIONAL: Path to icon file representing this content module
// SPECIFICATION: Can be relative path, absolute path, or URL. Supported formats: SVG, PNG, JPG, WebP
// FALLBACK: If file is missing or fails to load, use icon_fallback instead
// SIZING: Recommended size 64x64px minimum, should be square aspect ratio
// AI SYSTEMS: Validate file existence before display, implement graceful fallback to icon_fallback
"icon": "assets/icons/uk-flag.svg",
// REQUIRED IF icon IS SPECIFIED: Emoji fallback for when icon file is unavailable
// SPECIFICATION: Single Unicode emoji character that represents the content theme
// USAGE: Displayed when icon file fails to load, in text-only interfaces, or minimal UIs
// ACCESSIBILITY: Should be descriptive and relevant to content theme
// AI SYSTEMS: Always validate this field exists when icon field is present
"icon_fallback": "🇬🇧",
// ========================================================================================================
// CLASSIFICATION AND TAGGING SYSTEM
// ========================================================================================================
// This section provides structured metadata for content discovery, filtering, and automatic
// compatibility assessment. Tags enable AI systems to make intelligent decisions about content
// usage, game compatibility, and learning path optimization.
// OPTIONAL: Array of classification tags for content discovery and filtering
// SPECIFICATION: Use lowercase, hyphen-separated tags from the standardized taxonomy below
// USAGE: Content browsers can filter by these tags, AI can assess game compatibility
// EXTENSIBILITY: New tags can be added, but use standard taxonomy when possible
// AI SYSTEMS: Use for automatic content categorization and compatibility scoring
"tags": [
// CONTENT DIFFICULTY TAGS (mutually exclusive):
"beginner-friendly", // Suitable for beginners (difficulty ≤ 4)
// "intermediate-level", // For intermediate learners (difficulty 5-6)
// "advanced-content", // For advanced learners (difficulty 7-8)
// "expert-native", // For native/expert level (difficulty 9-10)
// MEDIA RICHNESS TAGS (can combine multiple):
"audio-rich", // Contains significant audio content (>50% of vocabulary items have audio)
// "image-heavy", // Contains many images (>50% of vocabulary items have images)
// "video-content", // Contains video materials
// "text-only", // Primarily text-based content
// LEARNING FOCUS TAGS (can combine multiple):
"grammar-focus", // Emphasizes grammar learning (has grammar section or grammar exercises)
// "vocabulary-focus", // Primarily vocabulary building
// "pronunciation-focus", // Emphasis on pronunciation and phonetics
// "conversation-focus", // Dialogue and speaking practice emphasis
// CONTENT TYPE TAGS (can combine multiple):
"cultural-content", // Includes cultural context, traditions, customs (has cultural section)
"interactive", // Has interactive exercises (matching, corrections, fill-in-blanks)
"daily-life", // Real-world applicable content (practical situations)
"conversation", // Dialogue-based learning (has dialogues section)
"multimedia", // Multiple content types (text, audio, visual combined)
// PEDAGOGICAL APPROACH TAGS (can combine multiple):
// "gamified", // Designed for game-based learning
// "formal-academic", // Academic/textbook style content
// "informal-casual", // Casual, conversational learning style
// "immersive", // Immersive, context-rich learning
// THEMATIC CONTENT TAGS (can combine multiple):
// "business-english", // Professional/business context
// "travel-language", // Travel and tourism focused
// "academic-language", // Academic and educational contexts
// "everyday-situations" // Common daily life situations
],
// OPTIONAL: Array of learning skills and competencies addressed by this content module
// SPECIFICATION: Use standardized skill identifiers for consistency across modules
// USAGE: Progress tracking systems use this to map learning objectives and outcomes
// ASSESSMENT: AI tutoring systems can focus on specific skills based on this metadata
// ANALYTICS: Learning analytics can track skill development across multiple modules
"skills_covered": [
// VOCABULARY SKILLS:
"vocabulary_recognition", // Passive vocabulary: recognizing and understanding words when encountered
"vocabulary_production", // Active vocabulary: using words correctly in speech and writing
"vocabulary_categorization", // Grouping words by themes, topics, or grammatical categories
// LISTENING SKILLS:
"listening_comprehension", // Understanding spoken language in various contexts
"audio_discrimination", // Distinguishing between similar sounds, words, or phrases
"listening_for_detail", // Extracting specific information from audio content
"listening_for_gist", // Understanding general meaning and main ideas from audio
// READING SKILLS:
"reading_comprehension", // Understanding written text at sentence and paragraph level
"reading_for_detail", // Extracting specific information from written text
"reading_fluency", // Reading smoothly and efficiently
"skimming_scanning", // Quick reading techniques for information gathering
// SPEAKING AND PRONUNCIATION SKILLS:
"pronunciation", // Correct sound production and accent training
"intonation_stress", // Proper word stress and sentence intonation patterns
"oral_fluency", // Speaking smoothly and naturally
"conversation_skills", // Interactive dialogue ability and turn-taking
// GRAMMAR AND STRUCTURE SKILLS:
"grammar_application", // Using grammar rules correctly in context
"sentence_construction", // Building grammatically correct sentences
"pattern_recognition", // Identifying linguistic patterns and structures
"error_correction", // Identifying and fixing grammatical mistakes
// CULTURAL AND CONTEXTUAL SKILLS:
"cultural_awareness", // Understanding cultural context and appropriateness
"pragmatic_competence", // Using language appropriately in social contexts
"cross_cultural_communication", // Communicating effectively across cultures
// COGNITIVE AND LEARNING SKILLS:
"translation", // Converting meaning between languages
"language_comparison", // Understanding similarities and differences between languages
"metalinguistic_awareness", // Understanding how language works as a system
"learning_strategies", // Developing effective language learning techniques
// FUNCTIONAL SKILLS:
"task_completion", // Using language to accomplish specific tasks
"information_processing", // Understanding and organizing linguistic information
"critical_thinking", // Analyzing and evaluating language use and meaning
"creative_expression" // Using language for creative and personal expression
],
// ========================================================================================================
// VOCABULARY SECTION - PROGRESSIVE COMPLEXITY
// ========================================================================================================
// The vocabulary section demonstrates a progressive complexity model where content creators can
// start with basic word-translation pairs and gradually add richer linguistic data. This design
// ensures that simple content works in basic games while enabling advanced features as data
// richness increases. AI systems should detect the complexity level of each vocabulary entry
// and enable appropriate features accordingly.
//
// PROGRESSIVE COMPLEXITY LEVELS:
// =============================
// Level 1 (MINIMAL): String value only - "word": "translation"
// Level 2 (BASIC): Object with translation and type
// Level 3 (MEDIUM): Adds pronunciation OR image (single media enhancement)
// Level 4 (RICH): Multiple media types (audio + image + examples)
// Level 5 (COMPREHENSIVE): Full linguistic data (conjugations, grammar notes)
// Level 6 (ADVANCED): Cultural context and regional variations
//
// AI GAME COMPATIBILITY MATRIX:
// =============================
// Basic matching games: Require Level 1 minimum
// Pronunciation games: Require Level 3+ with pronunciation or audio
// Visual games: Require Level 3+ with images
// Grammar games: Require Level 5+ with conjugation data
// Cultural games: Require Level 6+ with cultural context
//
"vocabulary": {
// ================================================================================================
// LEVEL 1: MINIMAL COMPLEXITY
// ================================================================================================
// DESCRIPTION: Simplest possible format - just a word and its translation as a string value
// USAGE: Perfect for basic vocabulary games, simple matching exercises, flashcards
// GAME COMPATIBILITY: Works with ALL game types that need basic translation pairs
// PERFORMANCE: Fastest to parse and process, minimal memory footprint
// AUTHORING: Easiest for content creators - just word pairs in spreadsheets
// AI PROCESSING: Detect by checking if value is string (not object)
"cat": "chat", // English word -> French translation (string format)
"dog": "chien", // Simple word pair, no additional metadata
"house": "maison", // Minimal format ensures maximum compatibility
"water": "eau", // AI systems: treat these as basic vocabulary items
"food": "nourriture", // Enable basic matching, flashcard, and quiz games
// ================================================================================================
// LEVEL 2: BASIC COMPLEXITY
// ================================================================================================
// DESCRIPTION: Object format with essential linguistic metadata
// ADDS: Grammatical type classification for enhanced game mechanics
// USAGE: Enables grammar-aware games, categorization exercises, word type sorting
// GAME COMPATIBILITY: Grammar games can now categorize words appropriately
// AUTHORING EASE: Still simple - just add one field for word type
// AI PROCESSING: Detect by checking for object with 'translation' and 'type' fields only
"book": {
"translation": "livre",
"type": "noun" // REQUIRED: grammatical category for this word
// STANDARD VALUES: noun, verb, adjective, adverb, pronoun,
// preposition, conjunction, interjection, article, greeting,
// number, color, food, animal, body_part, clothing, etc.
// AI SYSTEMS: Use for word categorization games and grammar exercises
},
"read": {
"translation": "lire",
"type": "verb" // Enables verb conjugation games and grammar pattern recognition
},
"happy": {
"translation": "heureux",
"type": "adjective" // Enables adjective comparison games and descriptive exercises
},
// ================================================================================================
// LEVEL 3: MEDIUM COMPLEXITY
// ================================================================================================
// DESCRIPTION: Enhanced with ONE media type - either pronunciation OR image
// ADDS: Single multimedia enhancement for richer learning experience
// USAGE: Enables pronunciation games OR visual recognition games (not both)
// STRATEGY: Choose pronunciation for abstract words, images for concrete nouns
// GAME COMPATIBILITY: Unlocks pronunciation games OR visual matching games
// AUTHORING: Moderate effort - requires recording audio OR finding/creating images
// AI PROCESSING: Detect by presence of 'pronunciation' OR 'image' field (mutually exclusive at this level)
"apple": {
"translation": "pomme",
"type": "noun",
"pronunciation": "/ˈæp.əl/", // IPA (International Phonetic Alphabet) notation
// SPECIFICATION: Use standard IPA symbols enclosed in forward slashes
// USAGE: Text-to-speech systems, pronunciation games, phonetic exercises
// VALIDATION: AI should verify IPA format correctness
// ALTERNATIVES: Can also accept simplified phonetic (AP-uhl)
"image": "images/vocabulary/apple.jpg" // Path to visual representation
// SPECIFICATION: Relative or absolute path, supports JPG, PNG, SVG, WebP
// USAGE: Visual vocabulary games, memory games, image-word matching
// FALLBACK: AI should handle missing image files gracefully
// SIZING: Recommended minimum 256x256px for clarity
},
"beautiful": {
"translation": "beau/belle",
"type": "adjective",
"pronunciation": "/ˈbjuː.tɪ.fəl/",
"examples": ["The sunset is beautiful"] // OPTIONAL: Array of usage examples in context
// USAGE: Help learners understand word usage and context
// SPECIFICATION: Use simple, clear sentences appropriate for difficulty level
// AI SYSTEMS: Can be used for context-based exercises and comprehension
},
// ================================================================================================
// LEVEL 4: RICH COMPLEXITY
// ================================================================================================
// DESCRIPTION: Multiple media types for comprehensive multimedia learning
// ADDS: Combination of audio, visual, and textual enhancements
// USAGE: Enables advanced vocabulary games with multiple sensory inputs
// LEARNING THEORY: Supports multiple learning styles (visual, auditory, kinesthetic)
// GAME COMPATIBILITY: Unlocks ALL types of multimedia vocabulary games
// AUTHORING: Significant effort - requires multiple media assets per word
// AI PROCESSING: Detect by presence of multiple media fields (audio + image + examples)
"elephant": {
"translation": "éléphant",
"type": "noun",
"pronunciation": "/ˈel.ɪ.fənt/",
"audio": "audio/vocabulary/elephant.mp3", // Audio pronunciation file
// SPECIFICATION: MP3, WAV, or OGG format, max 10 seconds
// QUALITY: Clear, native speaker pronunciation, minimal background noise
// USAGE: Pronunciation games, listening exercises, audio-visual matching
// FALLBACK: If audio fails, use text-to-speech as backup
"image": "images/vocabulary/elephant.jpg", // Visual representation
// SPECIFICATION: High-quality image, clear subject, minimal background
// CONTEXT: Should show typical/recognizable example of the concept
// ACCESSIBILITY: Should work well with colorblind users
"examples": [
"The elephant is huge", // Multiple usage examples
"Elephants have good memory" // Shows different contexts and grammatical patterns
]
// AI SYSTEMS: Rich media enables sophisticated games like:
// - Audio-visual matching (hear word, click correct image)
// - Multi-modal memory games (audio + visual + text)
// - Pronunciation practice with visual feedback
// - Context-based sentence completion exercises
},
// ================================================================================================
// LEVEL 5: COMPREHENSIVE COMPLEXITY
// ================================================================================================
// DESCRIPTION: Complete linguistic analysis with grammatical patterns and relationships
// ADDS: Advanced linguistic metadata for professional language learning
// USAGE: Enables sophisticated grammar games, conjugation practice, linguistic analysis
// TARGET AUDIENCE: Advanced learners, language teachers, linguistic research
// GAME COMPATIBILITY: Unlocks advanced grammar games and linguistic pattern recognition
// AUTHORING: Expert-level effort - requires linguistic knowledge and detailed analysis
// AI PROCESSING: Detect by presence of 'conjugation' or 'grammarNotes' fields
"run": {
"translation": "courir",
"type": "verb",
"pronunciation": "/rʌn/",
"audio": "audio/vocabulary/run.mp3",
"image": "images/vocabulary/run_action.gif", // SPECIFICATION: Can be GIF for action words
// USAGE: Animated images help demonstrate actions
// PERFORMANCE: Keep GIFs under 2MB for web performance
"examples": [
"I run in the park every morning", // Present tense usage
"She runs faster than me", // Third person singular form
"They ran to catch the bus" // Past tense usage - shows verb conjugation in context
],
"grammarNotes": "Irregular verb: run/runs/running/ran/run", // Educational notes for teachers/advanced learners
// USAGE: Displayed in grammar-focused exercises
// CONTENT: Should highlight important patterns, irregularities, or usage rules
"conjugation": { // OPTIONAL: Detailed verb conjugation patterns
"present": ["run", "runs"], // Array: [base form, third person singular]
"past": "ran", // Past tense form (string for regular, object for complex)
"participle": "run", // Past participle form
"continuous": "running" // Present participle / gerund form
// EXTENSIBILITY: Can add more tenses (future, conditional, subjunctive) as needed
// AI SYSTEMS: Use for automatic conjugation exercises and grammar pattern recognition
},
"difficulty_context": "Physical action verb - easy to demonstrate" // Teaching hints for AI tutors
// USAGE: Helps AI systems provide contextual learning tips
// CONTENT: Pedagogical insights for optimal teaching approach
},
// ================================================================================================
// LEVEL 6: ADVANCED COMPLEXITY (Cultural Context)
// ================================================================================================
// DESCRIPTION: Maximum linguistic richness with cultural and contextual information
// ADDS: Cultural awareness, regional variations, cross-cultural understanding
// USAGE: Advanced cultural competency games, cross-cultural communication training
// TARGET AUDIENCE: Advanced learners, cultural immersion programs, international communication
// GAME COMPATIBILITY: Enables cultural awareness games and contextual learning
// AUTHORING: Expert cultural knowledge required, significant research effort
// AI PROCESSING: Detect by presence of 'cultural_note' field
"breakfast": {
"translation": "petit-déjeuner",
"type": "noun",
"pronunciation": "/ˈbrek.fəst/",
"audio": "audio/vocabulary/breakfast.mp3",
"image": "images/vocabulary/breakfast.jpg", // Should show culturally representative breakfast
"examples": [
"I have breakfast at 7 AM",
"What did you have for breakfast?",
"Breakfast is the most important meal"
],
"cultural_note": "Traditional English breakfast includes eggs, bacon, beans, and toast"
// SPECIFICATION: Brief cultural context explaining cultural significance
// USAGE: Cultural awareness games, cross-cultural communication training
// CONTENT: Should explain cultural practices, traditions, or social norms
// LENGTH: Keep concise (1-2 sentences) for game integration
// AI SYSTEMS: Use for cultural competency assessment and awareness building
}
// ================================================================================================
// AI IMPLEMENTATION GUIDELINES FOR VOCABULARY
// ================================================================================================
/*
COMPLEXITY DETECTION ALGORITHM:
==============================
1. Check if value is string -> Level 1 (Minimal)
2. Check if object has only 'translation' and 'type' -> Level 2 (Basic)
3. Check if has 'pronunciation' OR 'image' (not both) -> Level 3 (Medium)
4. Check if has multiple media fields -> Level 4 (Rich)
5. Check if has 'conjugation' or 'grammarNotes' -> Level 5 (Comprehensive)
6. Check if has 'cultural_note' -> Level 6 (Advanced)
GAME COMPATIBILITY MATRIX:
=========================
Basic Flashcards: Level 1+
Visual Matching: Level 3+ (with image)
Audio Pronunciation: Level 3+ (with pronunciation or audio)
Grammar Exercises: Level 5+ (with conjugation)
Cultural Games: Level 6+ (with cultural_note)
Advanced Multimedia: Level 4+ (with multiple media)
ERROR HANDLING:
==============
- Missing audio files: Fall back to text-to-speech
- Missing image files: Use default placeholder or skip visual components
- Invalid IPA pronunciation: Use simplified phonetic or skip pronunciation features
- Malformed conjugation: Fall back to basic form without conjugation exercises
PERFORMANCE OPTIMIZATION:
========================
- Lazy load media files (audio, images) only when needed
- Cache processed vocabulary data for faster game startup
- Preload critical media for smooth gameplay experience
- Use progressive image loading for better perceived performance
*/
},
// ========================================================================================================
// GRAMMAR SYSTEM - STRUCTURED PEDAGOGY
// ========================================================================================================
// The grammar system implements a comprehensive pedagogical framework for step-by-step language
// instruction. It follows educational best practices with alternating explanation and practice phases,
// prerequisite tracking, and competency-based progression. This system is designed for dedicated
// grammar learning applications rather than general content games.
//
// PEDAGOGICAL FRAMEWORK:
// =====================
// 1. SCAFFOLDED LEARNING: Each lesson builds on previous knowledge with clear prerequisites
// 2. INTERLEAVED PRACTICE: Explanations alternate with exercises for optimal retention
// 3. COMPETENCY MAPPING: Clear learning objectives and measurable outcomes
// 4. ADAPTIVE DIFFICULTY: Multiple exercise types accommodate different learning styles
// 5. IMMEDIATE FEEDBACK: Explanations provided for every exercise answer
//
// IMPLEMENTATION NOTES FOR AI SYSTEMS:
// ===================================
// - This system requires a dedicated grammar learning interface
// - Steps must be completed in order - do not allow skipping
// - Track completion status for prerequisite validation
// - Provide rich feedback using explanation fields
// - Adapt presentation based on user performance and learning style
//
"grammar": {
// ================================================================================================
// FOUNDATIONAL GRAMMAR LESSON EXAMPLE
// ================================================================================================
// This lesson demonstrates the complete structure for grammar instruction, including all
// possible fields and educational components. AI systems should use this as a template
// for grammar lesson implementation.
"present_simple_be": { // LESSON IDENTIFIER: Must be unique within this content module
// NAMING CONVENTION: Use descriptive, hierarchical naming
// VALIDATION: Must match the object key for consistency
// === LESSON METADATA ===
"id": "present_simple_be", // REQUIRED: Exact duplicate of object key (for validation)
"title": "Present Simple - Verb 'to be'", // REQUIRED: Human-readable lesson title for UI display
"difficulty": 3, // REQUIRED: Lesson difficulty on 1-10 scale
// GUIDELINE: Should align with overall module difficulty ±2 levels
"prerequisite": null, // REQUIRED: Reference to prerequisite lesson ID, or null if foundational
// VALIDATION: AI must verify prerequisite completion before allowing access
// DEPENDENCY CHAIN: Must not create circular dependencies
"estimated_time": 15, // REQUIRED: Estimated completion time in minutes
// USAGE: Help learners plan study sessions and set expectations
// ACCURACY: Should be realistic for average learner at stated difficulty level
// === LEARNING OBJECTIVES ===
"learning_objectives": [ // REQUIRED: Array of clear, measurable learning goals
// SPECIFICATION: Use action verbs (conjugate, identify, form, apply)
// ASSESSMENT: Each objective should be testable through lesson exercises
// GRANULARITY: 3-5 objectives per lesson for optimal focus
"Conjugate 'to be' in present tense", // Specific skill: verb conjugation
"Use 'to be' in affirmative sentences", // Application: positive statements
"Form questions with 'to be'" // Synthesis: interrogative transformation
],
// === INSTRUCTIONAL SEQUENCE ===
// CRITICAL: Steps must be completed in order. AI systems should enforce sequential progression
// PEDAGOGY: Alternates between explanation (input) and exercise (practice) for optimal learning
// ADAPTIVITY: AI can adjust pacing based on user performance but must maintain sequence
"steps": [
// ========================================================================================
// EXPLANATION STEP EXAMPLE
// ========================================================================================
// Explanation steps provide new information, concepts, and examples before practice
{
"type": "explanation", // REQUIRED: "explanation" or "exercise"
"order": 1, // REQUIRED: Sequential integer, must start at 1
"title": "Introduction to 'be'", // REQUIRED: Brief title for this instructional step
"content": "The verb 'to be' is the most important verb in English. It has three forms in present tense.",
// REQUIRED: Main instructional content
// GUIDELINES: Clear, concise language appropriate for difficulty level
// LENGTH: 1-3 sentences for explanations, longer for complex concepts
"translation": "Le verbe 'être' est le verbe le plus important en anglais. Il a trois formes au présent.",
// REQUIRED: Translation in user's native language
// USAGE: Ensures comprehension for non-native speakers
// QUALITY: Should be natural, not literal translation
"examples": [ // OPTIONAL: Array of illustrative examples
{
"original": "I am happy",
"userLanguage": "Je suis heureux"
},
{
"original": "You are smart",
"userLanguage": "Tu es intelligent"
},
{
"original": "She is tall",
"userLanguage": "Elle est grande"
}
]
},
// ========================================================================================
// EXERCISE STEP - MULTIPLE CHOICE
// ========================================================================================
// Exercise steps provide immediate practice of concepts just taught
{
"type": "exercise",
"order": 2,
"exercise_type": "multiple_choice", // REQUIRED: Specific exercise format
// AVAILABLE TYPES: multiple_choice, transformation,
// fill_blanks, classification, conjugation, matching
"title": "Choose the correct form", // REQUIRED: Clear instruction for the exercise
"questions": [ // REQUIRED: Array of question objects
{
"question": "I ___ a student", // The exercise prompt with blank to fill
"options": ["am", "is", "are"], // Array of possible answers (2-5 options recommended)
"correct": "am", // The correct answer (must match one option exactly)
"explanation": "Use 'am' with 'I'" // REQUIRED: Feedback explaining why this answer is correct
// PEDAGOGY: Reinforces the grammatical rule
},
{
"question": "She ___ my friend",
"options": ["am", "is", "are"],
"correct": "is",
"explanation": "Use 'is' with 'she', 'he', 'it'"
},
{
"question": "They ___ teachers",
"options": ["am", "is", "are"],
"correct": "are",
"explanation": "Use 'are' with 'they', 'we', 'you'"
}
]
},
// ========================================================================================
// ADVANCED EXPLANATION WITH PATTERNS
// ========================================================================================
// More complex explanations can include structured patterns and detailed examples
{
"type": "explanation",
"order": 3,
"title": "Negative forms",
"content": "To make negative sentences with 'be', add 'not' after the verb. We often use contractions.",
"translation": "Pour faire des phrases négatives avec 'être', ajoutez 'not' après le verbe. On utilise souvent des contractions.",
"examples": [
{
"original": "I am not tired",
"userLanguage": "Je ne suis pas fatigué",
"contraction": "I'm not tired" // OPTIONAL: Shows contracted form
},
{
"original": "He is not here",
"userLanguage": "Il n'est pas ici",
"contraction": "He isn't here"
},
{
"original": "We are not ready",
"userLanguage": "Nous ne sommes pas prêts",
"contraction": "We aren't ready"
}
]
},
// ========================================================================================
// EXERCISE STEP - TRANSFORMATION
// ========================================================================================
// Transformation exercises require converting one form to another
{
"type": "exercise",
"order": 4,
"exercise_type": "transformation",
"title": "Make these sentences negative",
"questions": [
{
"original": "I am busy", // Source sentence to transform
"correct": "I am not busy", // Primary correct answer
"alternative_correct": ["I'm not busy"] // OPTIONAL: Array of acceptable alternatives
// USAGE: Accommodates contractions, word order variations
},
{
"original": "She is happy",
"correct": "She is not happy",
"alternative_correct": ["She isn't happy"]
},
{
"original": "They are at home",
"correct": "They are not at home",
"alternative_correct": ["They aren't at home"]
}
]
},
// ========================================================================================
// EXPLANATION WITH STRUCTURAL PATTERNS
// ========================================================================================
// Advanced explanations can include formal patterns and systematic rules
{
"type": "explanation",
"order": 5,
"title": "Questions with 'be'",
"content": "To make questions, put the 'be' verb before the subject. The word order changes.",
"translation": "Pour faire des questions, mettez le verbe 'être' avant le sujet. L'ordre des mots change.",
"pattern": { // OPTIONAL: Formal grammatical patterns
"statement": "Subject + be + complement", // Pattern for statements
"question": "Be + subject + complement + ?" // Pattern for questions
// USAGE: Helps visual learners understand structural relationships
// EXTENSION: Can include negative patterns, other transformations
},
"examples": [
{
"statement": "You are ready", // Statement form
"question": "Are you ready?", // Question form
"answer": "Yes, I am / No, I'm not" // OPTIONAL: Expected response patterns
},
{
"statement": "He is a doctor",
"question": "Is he a doctor?",
"answer": "Yes, he is / No, he isn't"
}
]
},
// ========================================================================================
// CONTEXTUAL EXERCISE
// ========================================================================================
// Exercises can include context to make practice more meaningful and engaging
{
"type": "exercise",
"order": 6,
"exercise_type": "fill_blanks",
"title": "Complete the conversation",
"context": "A conversation between two people meeting for the first time", // OPTIONAL: Situational context
// USAGE: Makes exercises more engaging and realistic
// BENEFITS: Provides cultural context and practical application
"questions": [
{
"sentence": "Hi! ___ you a new student?",
"correct": "Are",
"options": ["Are", "Is", "Am"] // Can include options for guidance
},
{
"sentence": "Yes, I ___. My name ___ Sarah.",
"correct": ["am", "is"], // Multiple blanks require array of answers
"options": ["am/is", "is/am", "are/are"] // Can show combined options for clarity
},
{
"sentence": "___ you from France?",
"correct": "Are",
"options": ["Are", "Is", "Am"]
}
]
}
],
// === LESSON SUMMARY AND REINFORCEMENT ===
// Provides consolidation and reference material for the completed lesson
"summary": {
"key_points": [ // REQUIRED: Essential takeaways from lesson
// FORMAT: Concise bullet points (3-7 items)
// CONTENT: Core rules, patterns, or concepts taught
"I am, you are, he/she/it is, we are, they are", // Conjugation pattern
"Negative: add 'not' after 'be'", // Negation rule
"Questions: put 'be' before subject" // Question formation rule
],
"common_mistakes": [ // OPTIONAL: Frequent errors with corrections
// PEDAGOGY: Helps learners avoid typical pitfalls
// FORMAT: incorrect → correct with explanation
{
"incorrect": "I are happy",
"correct": "I am happy",
"explanation": "Use 'am' with 'I'"
},
{
"incorrect": "She am tired",
"correct": "She is tired",
"explanation": "Use 'is' with 'she'"
}
]
}
}
// ================================================================================================
// ADDITIONAL GRAMMAR LESSON EXAMPLE
// ================================================================================================
// Demonstrates prerequisite system and lesson sequencing
// "present_simple_verbs": { // Second lesson building on first
// "id": "present_simple_verbs",
// "title": "Present Simple - Regular Verbs",
// "difficulty": 4, // Slightly harder than prerequisite
// "prerequisite": "present_simple_be", // Must complete "be" lesson first
// "estimated_time": 20, // Longer, more complex lesson
// "learning_objectives": [
// "Use present simple for habits and facts",
// "Add 's' for he/she/it",
// "Form negatives with don't/doesn't"
// ],
// // ... additional steps following same pattern
// }
// ================================================================================================
// AI IMPLEMENTATION GUIDELINES FOR GRAMMAR
// ================================================================================================
/*
PREREQUISITE VALIDATION:
======================
- Check completion status before allowing lesson access
- Display prerequisite chain to learners
- Recommend review if prerequisite scores are low
- Prevent circular dependencies in lesson design
STEP SEQUENCING:
===============
- Enforce strict sequential progression (no skipping)
- Save progress after each completed step
- Allow review of previous steps within same lesson
- Resume from last incomplete step on lesson restart
EXERCISE TYPE HANDLING:
=====================
multiple_choice: Present options, validate single selection
transformation: Accept input, check against correct and alternatives
fill_blanks: Handle single or multiple blanks per question
classification: Sort items into categories
conjugation: Provide base verb, expect correct form
matching: Connect items from different columns
FEEDBACK SYSTEMS:
================
- Always show explanation after answer (correct or incorrect)
- Provide immediate feedback, not delayed
- Use explanations to reinforce grammatical concepts
- Adapt feedback tone to learner's proficiency level
PERFORMANCE TRACKING:
===================
- Track completion time for each step
- Monitor error rates by exercise type
- Identify struggling concepts for review recommendations
- Generate progress reports for learner motivation
ERROR HANDLING:
==============
- Handle malformed lesson data gracefully
- Provide fallback content for missing steps
- Validate answer formats before processing
- Log errors for content improvement feedback
*/
},
// ========================================================================================================
// TEXT CONTENT - FLEXIBLE INTEGRATION
// ========================================================================================================
// The text content section provides reading materials that can optionally be enhanced with exercises.
// This flexible design allows content creators to start with simple reading texts and progressively
// add interactive elements. AI systems should detect the presence of exercise fields and enable
// appropriate interactive features while gracefully handling text-only content.
//
// DESIGN PHILOSOPHY:
// ==================
// 1. CONTENT FIRST: Texts are valuable on their own, exercises are enhancement
// 2. OPTIONAL INTERACTION: Any text can become interactive by adding exercise fields
// 3. MULTIPLE EXERCISE TYPES: Supports comprehension questions and fill-in-blanks in same text
// 4. CONTEXTUAL LEARNING: Exercises draw from the actual text content for authenticity
// 5. PROGRESSIVE ENHANCEMENT: Basic reading → comprehension → interactive completion
//
"texts": [
// ================================================================================================
// BASIC TEXT WITH COMPREHENSION
// ================================================================================================
// Demonstrates text with reading comprehension questions of multiple types
{
"title": "My Daily Routine", // REQUIRED: Display title for the text
// USAGE: Shown in content browsers, reading interfaces
// LENGTH: Keep concise and descriptive
"content": "I wake up at 7 AM every day. First, I brush my teeth and take a shower. Then I have breakfast with my family. After breakfast, I go to work by bus. I work from 9 AM to 5 PM. In the evening, I cook dinner and watch TV. I go to bed at 10 PM.",
// REQUIRED: Main text content for reading
// LANGUAGE: Should be in original_lang specified in metadata
// COMPLEXITY: Appropriate for stated difficulty level
// LENGTH: 50-500 words recommended for optimal engagement
"translation": "Je me réveille à 7h tous les jours. D'abord, je me brosse les dents et prends une douche. Ensuite je prends le petit déjeuner avec ma famille. Après le petit déjeuner, je vais au travail en bus. Je travaille de 9h à 17h. Le soir, je cuisine le dîner et regarde la télé. Je me couche à 22h.",
// REQUIRED: Complete translation in user_lang
// QUALITY: Should be natural, culturally appropriate translation
// USAGE: Learning support, comprehension verification, cultural adaptation
// OPTIONAL: Reading comprehension questions
// ACTIVATION: AI systems should detect presence of this field and enable comprehension mode
// VARIETY: Mix question types for comprehensive assessment
"questions": [
{
"question": "What time does the person wake up?", // Factual recall question
"type": "multiple_choice", // QUESTION TYPES: multiple_choice, ai_interpreted
"options": ["6 AM", "7 AM", "8 AM", "9 AM"], // 3-5 options recommended
"correctAnswer": "7 AM" // Must match one option exactly
// AI PROCESSING: Straightforward validation, immediate feedback possible
},
{
"question": "Describe the person's evening routine", // Open-ended comprehension
"type": "ai_interpreted", // Requires AI evaluation
"evaluationPrompt": "Check if answer mentions cooking dinner and watching TV"
// REQUIRED for ai_interpreted: Guidance for AI evaluator
// SPECIFICITY: Clear criteria for acceptable answers
// FLEXIBILITY: Allow for paraphrasing and varied expression
},
{
"question": "How does the person get to work?", // Detail extraction
"type": "multiple_choice",
"options": ["by car", "by bus", "on foot", "by train"],
"correctAnswer": "by bus"
},
{
"question": "What do you think about this daily routine? Is it healthy?", // Critical thinking
"type": "ai_interpreted",
"evaluationPrompt": "Accept thoughtful opinions about the routine's health aspects, whether positive or negative, as long as reasoning is provided"
}
],
// OPTIONAL: Fill-in-the-blank exercises based on the text content
// PEDAGOGY: Reinforces vocabulary and grammar from authentic reading material
// INTEGRATION: Blanks should come from actual text sentences for authenticity
"fillInBlanks": [
{
"sentence": "I wake up ___ 7 AM every day", // Direct quote from text with blank
"options": ["at", "in", "on"], // Preposition practice
"correctAnswer": "at",
"explanation": "Use 'at' with specific times" // Grammar rule reinforcement
},
{
"sentence": "I ___ breakfast with my family", // Vocabulary reinforcement
"options": ["have", "make", "do"], // Collocations practice
"correctAnswer": "have",
"explanation": "'Have breakfast' is the correct collocation"
},
{
"sentence": "The daily routine seems very ___", // Open-ended vocabulary practice
"type": "open_ended", // No fixed options
"acceptedAnswers": ["organized", "structured", "regular", "busy", "normal"], // Multiple valid answers
"aiPrompt": "Accept descriptive adjectives that could reasonably describe a daily routine"
}
]
},
// ================================================================================================
// CONTENT-RICH TEXT EXAMPLE
// ================================================================================================
// Demonstrates more complex text with cultural elements and varied exercise types
{
"title": "The Four Seasons",
"content": "There are four seasons in a year: spring, summer, autumn, and winter. Spring is warm and flowers bloom. Summer is hot and sunny. Autumn is cool and leaves change colors. Winter is cold and it sometimes snows.",
"translation": "Il y a quatre saisons dans une année: le printemps, l'été, l'automne et l'hiver. Le printemps est chaud et les fleurs fleurissent. L'été est chaud et ensoleillé. L'automne est frais et les feuilles changent de couleur. L'hiver est froid et il neige parfois.",
// VOCABULARY INTEGRATION: Questions can reference vocabulary from other sections
"questions": [
{
"question": "How many seasons are there in a year?",
"type": "multiple_choice",
"options": ["three", "four", "five", "six"],
"correctAnswer": "four"
},
{
"question": "Which season do you like best and why?", // Personal connection
"type": "ai_interpreted",
"evaluationPrompt": "Accept any season choice with reasonable explanation about weather, activities, or personal preferences"
}
],
"fillInBlanks": [
{
"sentence": "There are _____ seasons in a year",
"options": ["three", "four", "five", "six"],
"correctAnswer": "four",
"explanation": "Spring, summer, autumn, and winter make four seasons"
},
{
"sentence": "Spring is _____ and flowers bloom",
"type": "open_ended",
"acceptedAnswers": ["warm", "nice", "pleasant", "mild"],
"aiPrompt": "Check if answer describes spring weather positively"
}
]
}
// ================================================================================================
// TEXT-ONLY EXAMPLE (Minimal Configuration)
// ================================================================================================
// Demonstrates that texts can exist without exercises for simple reading practice
// {
// "title": "Simple Reading Practice",
// "content": "This is a simple text for reading practice. It has no exercises attached.",
// "translation": "Ceci est un texte simple pour la pratique de lecture. Il n'a pas d'exercices attachés."
// // NO questions or fillInBlanks fields - just reading material
// // AI SYSTEMS: Should present this as reading-only content
// }
// ================================================================================================
// AI IMPLEMENTATION GUIDELINES FOR TEXTS
// ================================================================================================
/*
CONTENT DETECTION:
=================
- Check for presence of 'questions' field to enable comprehension mode
- Check for presence of 'fillInBlanks' field to enable interactive completion
- Present text-only content in reading mode without interactive elements
- Combine both modes if both fields are present
QUESTION TYPE HANDLING:
======================
multiple_choice: Present options clearly, validate selection
ai_interpreted: Use evaluationPrompt for AI assessment, provide detailed feedback
Mix types within same text for varied assessment
FILL-IN-BLANKS PROCESSING:
=========================
Standard format: Present options, validate selection
Open-ended format: Use AI evaluation with acceptedAnswers as guidance
Hybrid approach: Accept predefined answers OR AI evaluation for flexibility
CONTENT ADAPTATION:
==================
- Adjust reading difficulty presentation based on user level
- Provide vocabulary support for difficult words
- Enable translation toggle for comprehension support
- Track reading time and comprehension scores
EXERCISE INTEGRATION:
====================
- Present reading first, then exercises (or interleaved for advanced users)
- Reference text content in exercise feedback
- Allow re-reading during exercise completion
- Highlight relevant text sections for answers
ACCESSIBILITY:
=============
- Support text-to-speech for reading content
- Provide font size adjustment
- Enable high contrast mode for visual accessibility
- Support keyboard navigation for exercises
*/
],
// ========================================================================================================
// AUDIO-ONLY CONTENT - PURE LISTENING
// ========================================================================================================
// This section is specifically for audio content WITHOUT accompanying text or transcripts.
// The key distinction is that learners must rely solely on listening skills without textual support.
// Content that has both audio AND text should be placed in the texts[] or dialogues[] sections instead.
//
// PEDAGOGICAL PURPOSE:
// ===================
// 1. PURE LISTENING SKILLS: Develops audio comprehension without visual text cues
// 2. REAL-WORLD SIMULATION: Mimics authentic listening situations (conversations, announcements, etc.)
// 3. AUDIO DISCRIMINATION: Trains ear to distinguish sounds, accents, and speech patterns
// 4. CONTEXTUAL INFERENCE: Builds ability to understand meaning from audio context alone
//
// CONTENT GUIDELINES:
// ==================
// - Audio should be clear and professionally recorded
// - Background noise should be minimal unless part of the exercise design
// - Duration should be appropriate for difficulty level (30 seconds to 3 minutes)
// - Multiple speakers can be used for realistic conversation practice
//
"audio": [
// ================================================================================================
// AMBIENT LISTENING EXERCISE
// ================================================================================================
// Tests ability to identify context and extract information from environmental audio cues
{
"title": "Mystery Conversation - Restaurant", // REQUIRED: Descriptive title for the exercise
"audioFile": "audio/listening/restaurant_sounds.mp3", // REQUIRED: Path to audio file
// SPECIFICATION: MP3, WAV, or OGG format
// QUALITY: Clear audio, appropriate volume levels
// DURATION: 30 seconds to 2 minutes recommended
"type": "ambient_listening", // REQUIRED: Type of listening exercise
// TYPES: ambient_listening, sound_identification,
// pronunciation_exercise, dictation, conversation_analysis
"description": "Listen to the ambient sounds and conversation", // OPTIONAL: Brief description of what to expect
// USAGE: Helps set learner expectations
// CONTENT: Should not give away answers
"questions": [ // REQUIRED: Array of listening comprehension questions
{
"question": "Where does this conversation take place?", // Context identification
"type": "multiple_choice",
"options": ["Restaurant", "Office", "School", "Park"],
"correctAnswer": "Restaurant"
// PEDAGOGY: Tests ability to identify setting from audio context clues
},
{
"question": "How many people are speaking?", // Audio discrimination
"type": "ai_interpreted",
"evaluationPrompt": "Accept numeric answers indicating number of distinct voices"
// CHALLENGE: Requires distinguishing between different speakers
},
{
"question": "What is the mood or atmosphere of the conversation?", // Inference skills
"type": "ai_interpreted",
"evaluationPrompt": "Accept descriptions of mood such as friendly, formal, rushed, relaxed, etc."
// ADVANCED SKILL: Reading emotional context from audio cues
}
]
},
// ================================================================================================
// SOUND IDENTIFICATION EXERCISE
// ================================================================================================
// Focuses on recognizing specific sounds and their sequence in daily life contexts
{
"title": "Sound Recognition - Morning Routine",
"audioFile": "audio/sounds/morning_routine.mp3",
"type": "sound_identification",
"description": "Listen and identify the morning routine sounds in order",
"questions": [
{
"question": "What sounds did you hear in order?", // Sequencing challenge
"type": "ai_interpreted",
"evaluationPrompt": "Check for mentions of alarm clock, shower, coffee brewing, breakfast preparation sounds in logical sequence"
// COGNITIVE SKILL: Memory and sequencing from audio information
},
{
"question": "Which sound happened first?", // Specific identification
"type": "multiple_choice",
"options": ["Alarm clock", "Shower running", "Coffee brewing", "Door closing"],
"correctAnswer": "Alarm clock"
},
{
"question": "How long do you think this morning routine takes?", // Time estimation
"type": "ai_interpreted",
"evaluationPrompt": "Accept reasonable time estimates between 15-45 minutes with basic reasoning"
}
]
},
// ================================================================================================
// PRONUNCIATION DISCRIMINATION EXERCISE
// ================================================================================================
// Specialized for training phonetic discrimination and pronunciation awareness
{
"title": "Pronunciation Discrimination - Minimal Pairs",
"audioFile": "audio/pronunciation/minimal_pairs.mp3",
"type": "pronunciation_exercise",
"description": "Listen to similar sounding words and identify differences",
"word_pairs": [ // OPTIONAL: Specific to pronunciation exercises
["ship", "sheep"], // Minimal pair examples
["live", "leave"], // Helps learners focus on specific sound differences
["cat", "cut"] // Used for targeted pronunciation training
],
"questions": [
{
"question": "Which word did you hear first in the first pair?",
"type": "multiple_choice",
"options": ["ship", "sheep"],
"correctAnswer": "ship"
// PRECISION SKILL: Distinguishing minimal sound differences
},
{
"question": "How many different word pairs did you identify?",
"type": "multiple_choice",
"options": ["2", "3", "4", "5"],
"correctAnswer": "3"
// COUNTING SKILL: Audio attention and memory
}
]
},
// ================================================================================================
// DICTATION EXERCISE EXAMPLE
// ================================================================================================
// Pure dictation without visual text support - advanced listening skill
{
"title": "Simple Dictation - Numbers and Time",
"audioFile": "audio/dictation/numbers_time.mp3",
"type": "dictation",
"description": "Listen and write down exactly what you hear",
"questions": [
{
"question": "Write the time you heard", // Exact transcription required
"type": "ai_interpreted",
"evaluationPrompt": "Accept variations of 'three thirty', '3:30', 'half past three' for the time mentioned"
// PRECISION: Tests ability to capture specific information accurately
},
{
"question": "How many numbers were mentioned in total?", // Quantitative listening
"type": "multiple_choice",
"options": ["3", "4", "5", "6"],
"correctAnswer": "4"
}
]
}
// ================================================================================================
// AI IMPLEMENTATION GUIDELINES FOR AUDIO
// ================================================================================================
/*
AUDIO FILE HANDLING:
===================
- Validate audio file existence before presenting exercise
- Provide audio controls: play, pause, rewind, adjust speed
- Support multiple playback attempts (typically 2-3 times)
- Handle audio loading errors gracefully with user-friendly messages
EXERCISE TYPE PROCESSING:
========================
ambient_listening: Focus on context and environment recognition
sound_identification: Emphasize specific sound recognition and sequencing
pronunciation_exercise: Use word_pairs data for focused phonetic training
dictation: Require exact or near-exact transcription accuracy
conversation_analysis: Analyze speaker interactions and communication patterns
QUESTION RESPONSE HANDLING:
==========================
multiple_choice: Standard validation against correct answer
ai_interpreted: Use evaluationPrompt for flexible assessment
Allow partial credit for complex listening tasks
Provide rich feedback referencing specific audio segments when possible
ACCESSIBILITY AND USABILITY:
============================
- Provide volume controls and audio quality indicators
- Support keyboard shortcuts for audio control
- Enable subtitle toggle ONLY for accessibility needs (not for exercise content)
- Implement progress tracking for long audio files
ADAPTIVE FEATURES:
=================
- Allow playback speed adjustment (0.75x to 1.25x)
- Provide difficulty progression (start with clear audio, add background noise)
- Track listening patterns to identify problem areas
- Suggest replay strategies for improved comprehension
*/
],
// ========================================================================================================
// CULTURAL CONTENT - COMPREHENSIVE CONTEXT
// ========================================================================================================
// The cultural section provides rich contextual information that enhances language learning with
// cultural awareness and cross-cultural understanding. This content supports advanced pedagogical
// goals beyond pure language mechanics, helping learners understand the cultural framework in
// which the language operates.
//
// PEDAGOGICAL OBJECTIVES:
// ======================
// 1. CULTURAL COMPETENCY: Understanding cultural norms, values, and practices
// 2. CONTEXTUAL LANGUAGE USE: Learning when and how to use language appropriately
// 3. CROSS-CULTURAL AWARENESS: Comparing and contrasting different cultural approaches
// 4. AUTHENTIC COMMUNICATION: Preparing for real-world cultural interactions
// 5. CULTURAL SENSITIVITY: Developing respect and understanding for cultural differences
//
"cultural": {
// ================================================================================================
// POETRY AND LITERARY WORKS
// ================================================================================================
// Literary content provides cultural insights through traditional and contemporary works
"poems": [
{
"title": "Roses Are Red", // REQUIRED: Title of the literary work
"content": "Roses are red,\nViolets are blue,\nSugar is sweet,\nAnd so are you.",
// REQUIRED: Full text of the poem/literary work
// FORMAT: Use \n for line breaks in poetry
// PRESERVATION: Maintain original formatting and structure
"translation": "Les roses sont rouges,\nLes violettes sont bleues,\nLe sucre est doux,\nEt toi aussi.",
// REQUIRED: Translation preserving poetic structure
// CHALLENGE: Maintain rhythm and rhyme when possible
// CULTURAL ADAPTATION: May require cultural equivalent rather than literal translation
"audio": "audio/poems/roses.mp3", // OPTIONAL: Audio recitation of the poem
// QUALITY: Should demonstrate proper pronunciation and rhythm
// SPEAKER: Native speaker with clear articulation
"image": "images/cultural/roses_poem_illustration.jpg", // OPTIONAL: Visual illustration
// CONTENT: Should enhance understanding or cultural context
// STYLE: Can be artistic, historical, or educational
"type": "nursery_rhyme", // REQUIRED: Classification of literary work
// TYPES: nursery_rhyme, classic_poem, song, proverb,
// folk_tale, modern_poetry, traditional_chant
"cultural_context": "Traditional English nursery rhyme pattern, often used to teach basic rhyming and poetry structure to children.",
// REQUIRED: Explanation of cultural significance
// CONTENT: Historical background, social context, usage patterns
// AUDIENCE: Should be accessible to language learners
"learning_focus": ["rhyme_patterns", "basic_vocabulary", "rhythm"]
// OPTIONAL: Specific pedagogical elements highlighted
// USAGE: Guides teachers and AI systems on educational applications
// VALUES: linguistic features, cultural concepts, learning skills
}
],
// ================================================================================================
// PROVERBS AND SAYINGS
// ================================================================================================
// Traditional wisdom expressions that reveal cultural values and thinking patterns
"proverbs": [
{
"original": "The early bird catches the worm", // REQUIRED: Proverb in original language
"userLanguage": "L'avenir appartient à ceux qui se lèvent tôt",
// REQUIRED: Translation (may be cultural equivalent, not literal)
"meaning": "People who wake up early and start working have better chances of success",
// REQUIRED: Plain language explanation of the proverb's meaning
// AUDIENCE: Should be clear to non-native speakers
// DEPTH: Explain both literal and metaphorical meanings
"image": "images/cultural/early_bird_illustration.jpg", // OPTIONAL: Visual representation
// CONTENT: Can be literal (bird with worm) or metaphorical (early worker)
"cultural_context": "Common English saying emphasizing the value of being proactive and starting early",
// REQUIRED: Cultural significance and usage context
// SCOPE: When, where, and by whom this proverb is commonly used
"equivalent_proverbs": { // OPTIONAL: Cross-cultural equivalent expressions
"french": "L'avenir appartient à ceux qui se lèvent tôt", // Direct cultural equivalent
"literal": "Le premier oiseau attrape le ver" // Literal translation for comparison
// USAGE: Helps learners understand cultural translation vs. literal translation
// EXPANSION: Can include equivalents from multiple cultures
}
}
],
// ================================================================================================
// UNIFIED CULTURAL FACTS SYSTEM
// ================================================================================================
// Comprehensive system for various cultural elements: traditions, holidays, food, customs, etc.
// This unified approach allows for consistent data structure across different cultural domains.
"culture_facts": [
// ============================================================================================
// TRADITION EXAMPLE
// ============================================================================================
{
"name": "Tea Time", // REQUIRED: Name of the cultural element
"category": "tradition", // REQUIRED: Type of cultural element
// CATEGORIES: tradition, holiday, food, custom,
// celebration, social_norm, business_practice, educational_practice
"description": "Traditional British custom of drinking tea in the afternoon, usually around 4 PM",
// REQUIRED: Clear, factual description
// AUDIENCE: Accessible to non-native speakers and cultural outsiders
"translation": "L'heure du thé - tradition britannique de boire le thé l'après-midi, généralement vers 16h",
// REQUIRED: Translation with cultural adaptation
// APPROACH: May include explanatory additions for cultural clarity
"image": "images/cultural/tea_time.jpg", // OPTIONAL: Representative photograph or illustration
// CONTENT: Should show authentic cultural practice
// QUALITY: High quality, culturally respectful representation
"cultural_significance": "Social ritual that brings people together, often includes biscuits or small cakes",
// OPTIONAL: Deeper cultural meaning and social function
// DEPTH: Explains WHY this practice is culturally important
"vocabulary_related": ["tea", "biscuit", "afternoon", "tradition", "social"],
// OPTIONAL: Associated vocabulary for language learning
// INTEGRATION: Links cultural content with vocabulary learning
// USAGE: Can be used for themed vocabulary exercises
"region": "uk" // OPTIONAL: Geographic/cultural region identifier
// VALUES: uk, us, australia, canada, global, etc.
// USAGE: Helps learners understand cultural scope and variation
},
// ============================================================================================
// HOLIDAY EXAMPLE
// ============================================================================================
{
"name": "Christmas",
"category": "holiday",
"date": "December 25th", // OPTIONAL: Specific date for holidays and celebrations
// FORMAT: Natural language date description
// CULTURAL VARIATION: Note when dates vary by culture/region
"description": "Major Christian holiday celebrating the birth of Jesus Christ",
"translation": "Noël - grande fête chrétienne célébrant la naissance de Jésus-Christ",
"image": "images/cultural/christmas_celebration.jpg",
"customs": ["gift_giving", "family_gatherings", "christmas_tree", "caroling"],
// OPTIONAL: Associated practices and traditions
// FORMAT: Array of short descriptive phrases
// USAGE: Vocabulary building and cultural understanding
"vocabulary_related": ["Christmas", "gift", "tree", "family", "celebration"],
"region": "global" // Indicates widespread cultural adoption
},
// ============================================================================================
// FOOD EXAMPLE
// ============================================================================================
{
"name": "Fish and Chips",
"category": "food",
"description": "Traditional British dish of battered fish with fried potatoes",
"translation": "Poisson-frites - plat britannique traditionnel de poisson en pâte avec des pommes de terre frites",
"image": "images/cultural/fish_and_chips.jpg",
"cultural_context": "Popular working-class meal, often served in newspaper wrapping",
// OPTIONAL: Social and historical context
// CONTENT: Class associations, historical development, social significance
"vocabulary_related": ["fish", "chips", "batter", "traditional", "popular"],
"region": "uk",
"ingredients": ["fish", "potatoes", "batter", "oil"],
// OPTIONAL: Specific to food items
// USAGE: Cooking vocabulary, dietary information
"typical_sides": ["mushy_peas", "tartar_sauce", "malt_vinegar"]
// OPTIONAL: Additional food vocabulary and cultural eating patterns
},
// ============================================================================================
// HOLIDAY WITH REGIONAL VARIATION
// ============================================================================================
{
"name": "Thanksgiving",
"category": "holiday",
"date": "Fourth Thursday in November", // US-specific date format
"description": "American holiday celebrating gratitude and harvest",
"translation": "Action de grâce - fête américaine célébrant la gratitude et la récolte",
"image": "images/cultural/thanksgiving_dinner.jpg",
"customs": ["family_dinner", "turkey_meal", "gratitude_sharing", "football_watching"],
"vocabulary_related": ["thanksgiving", "turkey", "grateful", "harvest", "family"],
"region": "us" // Region-specific cultural element
}
// ============================================================================================
// ADDITIONAL CULTURAL CATEGORY EXAMPLES
// ============================================================================================
// Additional categories can include:
// - business_practice: "Bowing in Japanese business meetings"
// - social_norm: "Queuing politely in British culture"
// - educational_practice: "Raising hand to speak in American classrooms"
// - celebration: "Quinceañera in Latin American culture"
// - custom: "Removing shoes before entering homes in many Asian cultures"
]
// ================================================================================================
// AI IMPLEMENTATION GUIDELINES FOR CULTURAL CONTENT
// ================================================================================================
/*
CULTURAL SENSITIVITY:
====================
- Present cultural information respectfully and accurately
- Avoid stereotypes and overgeneralizations
- Include cultural variations within same regions/countries
- Acknowledge cultural evolution and contemporary changes
CONTENT ORGANIZATION:
====================
- Use category field for systematic organization and filtering
- Enable region-based filtering for location-specific learning
- Cross-reference vocabulary_related with main vocabulary section
- Link cultural facts to relevant exercises and activities
MULTIMEDIA INTEGRATION:
======================
- Validate image files and provide meaningful alt text
- Support audio pronunciation for cultural terms
- Enable interactive cultural comparison exercises
- Provide visual cultural timelines for historical context
PEDAGOGICAL APPLICATIONS:
========================
- Create cultural awareness quizzes using culture_facts data
- Develop comparative culture exercises across regions
- Integrate cultural vocabulary into standard language games
- Generate discussion prompts for cultural exchange
ACCESSIBILITY AND INCLUSION:
===========================
- Provide multiple cultural perspectives on shared practices
- Include contemporary as well as traditional cultural elements
- Support learners from diverse cultural backgrounds
- Enable cultural reflection and comparison exercises
*/
},
// ========================================================================================================
// SENTENCES WITH COMPREHENSIVE PARAMETERS
// ========================================================================================================
// The sentences section serves as a versatile, unified system for various language exercises including
// translation practice, grammar correction, and contextual learning. This design eliminates redundancy
// by using a single data structure with rich parameters to support multiple exercise types.
//
// DESIGN PHILOSOPHY:
// ==================
// 1. UNIFIED STRUCTURE: One sentence format supports multiple exercise types
// 2. RICH PARAMETERS: Extensive metadata enables sophisticated exercise generation
// 3. CORRECTION INTEGRATION: Includes both correct forms and common errors
// 4. CONTEXTUAL CLASSIFICATION: Sentences tagged for situational appropriateness
// 5. PROGRESSIVE COMPLEXITY: From simple translation to advanced error correction
//
"sentences": [
// ================================================================================================
// BASIC SENTENCE EXAMPLES
// ================================================================================================
// Simple sentences with fundamental classification for basic exercises
{
"original": "Hello, how are you?", // REQUIRED: Source language sentence
"userLanguage": "Bonjour, comment allez-vous?", // REQUIRED: Target language translation
"type": "greeting", // REQUIRED: Functional classification
// TYPES: greeting, question, statement, command, exclamation,
// request, invitation, apology, thanks, goodbye
"formality": "neutral" // OPTIONAL: Register and appropriateness level
// VALUES: formal, neutral, informal, casual, intimate
// USAGE: Teaches sociolinguistic appropriateness
},
{
"original": "I like to read books",
"userLanguage": "J'aime lire des livres",
"type": "preference_statement", // Semantic classification
"tense": "present_simple" // OPTIONAL: Grammatical tense identification
// VALUES: present_simple, present_continuous, past_simple, etc.
// USAGE: Grammar-focused exercises and tense practice
},
{
"original": "The weather is nice today",
"userLanguage": "Il fait beau aujourd'hui",
"type": "observation",
"topic": "weather" // OPTIONAL: Thematic classification
// VALUES: weather, food, family, work, travel, health, etc.
// USAGE: Thematic vocabulary exercises and conversation practice
},
// ================================================================================================
// CORRECTION-ENABLED SENTENCES
// ================================================================================================
// Sentences with comprehensive error correction data for grammar instruction
{
"original": "I am happy today", // CORRECT version serves as the teaching target
"userLanguage": "Je suis heureux aujourd'hui",
"type": "correction_target", // REQUIRED: Indicates this sentence has error correction data
"correction_data": { // REQUIRED for correction_target type
"incorrect_versions": [ // Array of common mistakes and their analysis
{
"text": "I are happy today", // The incorrect sentence learners might produce
"error_type": "subject_verb_agreement", // Classification of the grammatical error
// TYPES: subject_verb_agreement, tense_error, word_order,
// article_error, preposition_error, spelling_error, etc.
"explanation": "Use 'am' with pronoun 'I', not 'are'",
// REQUIRED: Clear explanation of why it's wrong
// PEDAGOGY: Should teach the underlying rule
"difficulty": 2 // OPTIONAL: How hard this error is to catch (1-10 scale)
// USAGE: Adaptive error presentation based on learner level
},
{
"text": "I is happy today",
"error_type": "subject_verb_agreement",
"explanation": "Use 'am' with pronoun 'I', not 'is'",
"difficulty": 1 // Easier error to spot than the previous one
}
],
"grammar_focus": "be_verb_conjugation", // OPTIONAL: Main grammatical concept being taught
// INTEGRATION: Links to grammar section lessons
// VALUES: Should match grammar lesson IDs when possible
"common_mistake": true // OPTIONAL: Boolean indicating if this is a frequent error
// USAGE: Prioritize common mistakes in error correction exercises
}
},
{
"original": "She doesn't like apples", // Another correction example with different error types
"userLanguage": "Elle n'aime pas les pommes",
"type": "correction_target",
"correction_data": {
"incorrect_versions": [
{
"text": "She don't like apples",
"error_type": "subject_verb_agreement",
"explanation": "Use 'doesn't' with he/she/it, not 'don't'",
"difficulty": 3
},
{
"text": "She not like apples",
"error_type": "auxiliary_verb_missing",
"explanation": "Need auxiliary verb 'doesn't' for negative statements",
"difficulty": 4
}
],
"grammar_focus": "negative_present_simple",
"common_mistake": true
}
},
{
"original": "I can swim", // Modal verb correction example
"userLanguage": "Je sais nager",
"type": "correction_target",
"correction_data": {
"incorrect_versions": [
{
"text": "I can to swim",
"error_type": "infinitive_after_modal",
"explanation": "After modal verbs like 'can', use base form without 'to'",
"difficulty": 5
}
],
"grammar_focus": "modal_verbs",
"common_mistake": true
}
},
// ================================================================================================
// CONTEXTUALLY RICH SENTENCES
// ================================================================================================
// Sentences with extensive contextual metadata for sophisticated exercises
{
"original": "Could you please pass the salt?",
"userLanguage": "Pourriez-vous me passer le sel, s'il vous plaît?",
"type": "polite_request",
"formality": "formal",
"topic": "dining",
"situation": "restaurant_meal", // OPTIONAL: Specific situational context
// VALUES: restaurant_meal, business_meeting, family_dinner,
// casual_conversation, phone_call, etc.
// USAGE: Situational language practice and appropriateness training
"cultural_note": "Polite request format commonly used in formal dining situations"
// OPTIONAL: Cultural usage information
// INTEGRATION: Links sentence usage to cultural practices
},
{
"original": "I'm running late for the meeting",
"userLanguage": "Je suis en retard pour la réunion",
"type": "statement",
"formality": "neutral",
"topic": "work",
"situation": "business_context",
"tense": "present_continuous",
"emotion": "stress" // OPTIONAL: Emotional context
// VALUES: happiness, stress, anger, excitement, sadness, etc.
// USAGE: Emotional expression exercises and empathy building
}
// ================================================================================================
// SPECIALIZED SENTENCE TYPES
// ================================================================================================
// Examples of sentences optimized for specific learning objectives
// PRONUNCIATION FOCUS:
// {
// "original": "She sells seashells by the seashore",
// "userLanguage": "Elle vend des coquillages au bord de mer",
// "type": "tongue_twister",
// "pronunciation_focus": ["s_sound", "sh_sound"],
// "difficulty_pronunciation": 8
// }
// IDIOM TEACHING:
// {
// "original": "It's raining cats and dogs",
// "userLanguage": "Il pleut des cordes",
// "type": "idiom",
// "literal_meaning": "It's raining very heavily",
// "cultural_origin": "English weather expressions"
// }
// CONDITIONAL STRUCTURES:
// {
// "original": "If I were rich, I would travel the world",
// "userLanguage": "Si j'étais riche, je voyagerais autour du monde",
// "type": "conditional_statement",
// "conditional_type": "second_conditional",
// "grammar_focus": "hypothetical_situations"
// }
// ================================================================================================
// AI IMPLEMENTATION GUIDELINES FOR SENTENCES
// ================================================================================================
/*
EXERCISE TYPE GENERATION:
========================
- Use type field to generate appropriate exercise formats
- Leverage correction_data for error identification games
- Apply formality/situation filters for contextual appropriateness training
- Combine multiple parameters for complex exercise generation
CORRECTION EXERCISE PROCESSING:
==============================
- Present incorrect_versions for learners to identify and correct
- Use difficulty ratings for adaptive error presentation
- Provide rich feedback using explanation fields
- Track error_type patterns for personalized grammar focus
CONTEXTUAL EXERCISE INTEGRATION:
===============================
- Group sentences by topic for thematic learning sessions
- Filter by situation for role-play and scenario practice
- Use formality levels for register awareness training
- Apply cultural_note data for cross-cultural communication exercises
PARAMETER-BASED FILTERING:
=========================
- Enable complex queries: "formal greetings for business situations"
- Support multi-parameter filtering: topic + formality + tense
- Provide parameter-based difficulty progression
- Generate themed exercise sets using metadata combinations
ADAPTIVE LEARNING FEATURES:
==========================
- Track learner performance by error_type for focused practice
- Adapt sentence selection based on cultural background
- Provide situational appropriateness feedback
- Generate personalized correction exercise sequences
*/
],
// ========================================================================================================
// MATCHING EXERCISES - DUAL SYSTEM ARCHITECTURE
// ========================================================================================================
// The matching section implements a dual system that supports both traditional two-column matching
// (for backward compatibility) and a flexible multi-column system (for advanced exercises).
// This design ensures existing content continues to work while enabling sophisticated new exercise types.
//
// ARCHITECTURAL BENEFITS:
// ======================
// 1. BACKWARD COMPATIBILITY: Existing two-column exercises continue to work unchanged
// 2. PROGRESSIVE ENHANCEMENT: Content creators can migrate to multi-column format when needed
// 3. FLEXIBLE COMPLEXITY: Support for 2-N column exercises with single data structure
// 4. UNIVERSAL APPLICABILITY: Same system works for vocabulary, grammar, geography, logic, etc.
// 5. CLEAR TYPE DISTINCTION: Explicit type field prevents processing confusion
//
"matching": [
// ================================================================================================
// TYPE 1: TRADITIONAL TWO-COLUMN MATCHING
// ================================================================================================
// Classic left-right matching format for simple correspondence exercises
// MAINTAINED FOR: Backward compatibility, simple vocabulary matching, basic concept pairs
{
"title": "Match Animals to Their Sounds", // REQUIRED: Exercise title for display
"type": "two_column_matching", // REQUIRED: Explicit type declaration
// PROCESSING: AI systems should detect this type and use legacy matching interface
"leftColumn": ["Cat", "Dog", "Cow", "Bird"], // REQUIRED: Items for left side of matching interface
// ORDER: Can be randomized by game engine for variety
"rightColumn": ["Woof", "Meow", "Tweet", "Moo"], // REQUIRED: Items for right side of matching interface
// COUNT: Should match leftColumn count for 1:1 matching
"correctPairs": [ // REQUIRED: Array defining correct matches
{ "left": "Cat", "right": "Meow" }, // Each pair object specifies one correct connection
{ "left": "Dog", "right": "Woof" }, // VALUES: Must exactly match items from left/right columns
{ "left": "Cow", "right": "Moo" },
{ "left": "Bird", "right": "Tweet" }
]
// GAME MECHANICS: Drag-and-drop, click-to-connect, or tap-based matching
// VALIDATION: Check learner connections against correctPairs array
// FEEDBACK: Immediate validation with visual/audio feedback
},
{
"title": "Match Colors in English and French", // Another traditional matching example
"type": "two_column_matching",
"leftColumn": ["Red", "Blue", "Green", "Yellow"],
"rightColumn": ["Bleu", "Vert", "Rouge", "Jaune"],
"correctPairs": [
{ "left": "Red", "right": "Rouge" },
{ "left": "Blue", "right": "Bleu" },
{ "left": "Green", "right": "Vert" },
{ "left": "Yellow", "right": "Jaune" }
]
},
// ================================================================================================
// TYPE 2: MULTI-COLUMN MATCHING SYSTEM
// ================================================================================================
// Flexible N-column system for complex relationships and sentence construction
// APPLICATIONS: Grammar construction, complex relationships, logical sequences, categorization
{
"title": "Build Correct Sentences", // REQUIRED: Descriptive title for complex exercise
"type": "multi_column_matching", // REQUIRED: Identifies this as flexible column system
"columns": [ // REQUIRED: Array of column definitions (minimum 2, no maximum)
{
"id": 1, // REQUIRED: Numeric identifier for referencing in valid_combinations
// SPECIFICATION: Use simple integers starting from 1
// UNIQUENESS: Must be unique within this exercise
"name": "Subject", // OPTIONAL: Display label for column header
// USAGE: Shown in game interface to guide learners
// OMISSION: Can be left out for unlabeled columns
"items": ["I", "She", "They", "We"] // REQUIRED: Array of items available in this column
// FLEXIBILITY: Any number of items, any content type
},
{
"id": 2,
"name": "Verb",
"items": ["am", "is", "are", "are"] // Note: "are" appears twice for multiple subjects
},
{
"id": 3,
"name": "Complement",
"items": ["happy", "a teacher", "students", "friends"]
}
],
"valid_combinations": [ // REQUIRED: Array of correct multi-column combinations
// REFERENCE: Uses column IDs as keys, item text as values
{"1": "I", "2": "am", "3": "happy"}, // Valid sentence: "I am happy"
{"1": "I", "2": "am", "3": "a teacher"}, // Valid sentence: "I am a teacher"
{"1": "She", "2": "is", "3": "happy"}, // Valid sentence: "She is happy"
{"1": "She", "2": "is", "3": "a teacher"}, // Valid sentence: "She is a teacher"
{"1": "They", "2": "are", "3": "students"}, // Valid sentence: "They are students"
{"1": "They", "2": "are", "3": "friends"}, // Valid sentence: "They are friends"
{"1": "We", "2": "are", "3": "students"}, // Valid sentence: "We are students"
{"1": "We", "2": "are", "3": "friends"} // Valid sentence: "We are friends"
]
// GAME MECHANICS: Sequential selection across columns, drag-and-drop assembly, or tap-to-build
// VALIDATION: Check learner's column selections against valid_combinations array
// PARTIAL VALIDATION: Can check partial combinations for immediate feedback
// COMPLEXITY SCALING: More columns = more complex relationships and grammar concepts
},
// ================================================================================================
// MULTI-COLUMN WITHOUT COLUMN NAMES
// ================================================================================================
// Demonstrates flexibility by omitting optional column names
{
"title": "Match Country Information",
"type": "multi_column_matching",
"columns": [
{
"id": 1,
"name": "Country", // Has name for clear identification
"items": ["France", "Spain", "Italy", "Germany"]
},
{
"id": 2,
"name": "Capital", // Has name for educational clarity
"items": ["Paris", "Madrid", "Rome", "Berlin"]
},
{
"id": 3,
// NO "name" field - demonstrates optional nature
// INTERFACE: Game can show "Column 3" or use generic label
"items": ["French", "Spanish", "Italian", "German"]
}
],
"valid_combinations": [
{"1": "France", "2": "Paris", "3": "French"},
{"1": "Spain", "2": "Madrid", "3": "Spanish"},
{"1": "Italy", "2": "Rome", "3": "Italian"},
{"1": "Germany", "2": "Berlin", "3": "German"}
]
}
// ================================================================================================
// ADVANCED MULTI-COLUMN EXAMPLES
// ================================================================================================
// Additional examples showing the system's versatility
// COMPLEX GRAMMAR CONSTRUCTION (5 columns):
// {
// "title": "Build Complex English Sentences",
// "type": "multi_column_matching",
// "columns": [
// {"id": 1, "name": "Subject", "items": ["I", "She", "They"]},
// {"id": 2, "name": "Auxiliary", "items": ["don't", "doesn't", "do"]},
// {"id": 3, "name": "Main Verb", "items": ["eat", "like", "want"]},
// {"id": 4, "name": "Object", "items": ["fish", "coffee", "chocolate"]},
// {"id": 5, "name": "Time", "items": ["often", "never", "sometimes"]}
// ],
// "valid_combinations": [
// {"1": "I", "2": "don't", "3": "eat", "4": "fish", "5": "often"},
// {"1": "She", "2": "doesn't", "3": "like", "4": "coffee", "5": "never"}
// ]
// }
// LOGICAL CATEGORIZATION (4 columns):
// {
// "title": "Categorize by Properties",
// "type": "multi_column_matching",
// "columns": [
// {"id": 1, "name": "Animal", "items": ["Dog", "Fish", "Bird"]},
// {"id": 2, "name": "Habitat", "items": ["Land", "Water", "Air"]},
// {"id": 3, "name": "Movement", "items": ["Walks", "Swims", "Flies"]},
// {"id": 4, "name": "Sound", "items": ["Barks", "Silent", "Chirps"]}
// ],
// "valid_combinations": [
// {"1": "Dog", "2": "Land", "3": "Walks", "4": "Barks"},
// {"1": "Fish", "2": "Water", "3": "Swims", "4": "Silent"},
// {"1": "Bird", "2": "Air", "3": "Flies", "4": "Chirps"}
// ]
// }
// ================================================================================================
// AI IMPLEMENTATION GUIDELINES FOR MATCHING
// ================================================================================================
/*
TYPE DETECTION AND PROCESSING:
==============================
- Check 'type' field first to determine processing approach
- two_column_matching: Use traditional left-right interface
- multi_column_matching: Use flexible column-based interface
- Validate data structure matches declared type
TWO-COLUMN PROCESSING:
=====================
- Present leftColumn and rightColumn in separate interface areas
- Randomize order for variety while maintaining correctPairs validation
- Support drag-and-drop, click-to-connect, or touch-based matching
- Validate against correctPairs array for immediate feedback
MULTI-COLUMN PROCESSING:
=======================
- Dynamically generate interface based on columns array length
- Use column 'name' fields for headers when provided
- Fall back to generic labels ("Column 1", "Column 2") when name absent
- Reference valid_combinations using column IDs as keys
VALIDATION STRATEGIES:
=====================
- For two-column: Direct lookup in correctPairs array
- For multi-column: Check learner selection against valid_combinations
- Support partial validation for multi-column exercises
- Provide immediate feedback for correct and incorrect combinations
INTERFACE ADAPTATION:
====================
- Scale interface layout based on number of columns
- Adapt to different screen sizes and orientations
- Support keyboard navigation for accessibility
- Provide clear visual feedback for selections and validation
EXERCISE GENERATION:
===================
- Use multi-column system for sentence construction exercises
- Apply two-column system for simple vocabulary matching
- Generate exercises of varying complexity based on column count
- Support themed exercises using column categorization
*/
],
// ========================================================================================================
// DIALOGUES - CONVERSATIONAL CONTENT SYSTEM
// ========================================================================================================
// The dialogues section provides structured conversational content for communication skills development.
// This system supports both text-only conversations and audio-synchronized dialogues with precise timing.
// It serves as the primary location for content that combines audio WITH text (unlike the audio section
// which is for audio-only content).
//
// PEDAGOGICAL APPLICATIONS:
// ========================
// 1. CONVERSATION PRACTICE: Role-play and dialogue repetition exercises
// 2. PRONUNCIATION TRAINING: Audio-text synchronization for pronunciation practice
// 3. CONTEXTUAL LEARNING: Language use in realistic social situations
// 4. CULTURAL COMMUNICATION: Appropriate language use in different cultural contexts
// 5. LISTENING COMPREHENSION: Following conversations with textual support
//
"dialogues": [
// ================================================================================================
// TEXT-ONLY DIALOGUE EXAMPLE
// ================================================================================================
// Simple conversational content without audio for reading and role-play practice
{
"title": "At the Restaurant", // REQUIRED: Descriptive title for the dialogue
// USAGE: Shown in content browsers and exercise interfaces
// CONTEXT: Should indicate setting or situation
"conversation": [ // REQUIRED: Array of dialogue turns/exchanges
// STRUCTURE: Sequential turns between speakers
// FLEXIBILITY: Any number of turns, any number of speakers
{
"speaker": "Waiter", // REQUIRED: Speaker identification
// FORMAT: Can be names, roles, or generic labels (A, B, C)
// CONSISTENCY: Use same identifier throughout dialogue
"original": "Good evening! Welcome to our restaurant.",
// REQUIRED: Speaker's utterance in source language
// NATURALNESS: Should reflect authentic conversational language
"userLanguage": "Bonsoir! Bienvenue dans notre restaurant."
// REQUIRED: Translation in learner's target language
// CULTURAL ADAPTATION: Should reflect appropriate cultural norms
},
{
"speaker": "Customer",
"original": "Thank you. Can I see the menu please?",
"userLanguage": "Merci. Puis-je voir le menu s'il vous plaît?"
},
{
"speaker": "Waiter",
"original": "Of course! Here you are. What would you like to drink?",
"userLanguage": "Bien sûr! Voici. Que voulez-vous boire?"
}
]
// USAGE APPLICATIONS:
// - Reading comprehension exercises
// - Role-play practice (learners take different speaker roles)
// - Translation practice
// - Cultural appropriateness training
// - Conversation pattern recognition
},
// ================================================================================================
// AUDIO-SYNCHRONIZED DIALOGUE
// ================================================================================================
// Advanced dialogue with audio track and precise timing for multimedia learning
{
"title": "Daily Routine Conversation",
"audio": "audio/conversations/daily_routine.mp3", // OPTIONAL: Audio file containing spoken dialogue
// SPECIFICATION: Should contain clear recording of entire conversation
// QUALITY: Professional recording with distinct speakers
// SYNCHRONIZATION: Must match conversation array content exactly
"conversation": [
{
"speaker": "A", // Generic speaker labels for role-play flexibility
"original": "What time do you wake up?",
"userLanguage": "À quelle heure te réveilles-tu?",
"timestamp": 0.5 // OPTIONAL: Time in seconds when this line begins in audio
// PRECISION: Allows for precise audio-text synchronization
// APPLICATIONS: Pronunciation practice, listening comprehension
},
{
"speaker": "B",
"original": "I usually wake up at 7 AM.",
"userLanguage": "Je me réveille habituellement à 7h.",
"timestamp": 3.2 // Next speaker's line starts at 3.2 seconds
},
{
"speaker": "A",
"original": "That's early! I wake up at 8:30.",
"userLanguage": "C'est tôt! Je me réveille à 8h30.",
"timestamp": 6.8
},
{
"speaker": "B",
"original": "I like to exercise before work.",
"userLanguage": "J'aime faire de l'exercice avant le travail.",
"timestamp": 11.1
},
{
"speaker": "A",
"original": "That's a good habit!",
"userLanguage": "C'est une bonne habitude!",
"timestamp": 14.5
}
]
// ADVANCED APPLICATIONS:
// - Audio-text synchronization exercises
// - Pronunciation training with native speaker models
// - Listening comprehension with textual support
// - Speed and rhythm training
// - Accent and intonation practice
}
// ================================================================================================
// ADDITIONAL DIALOGUE EXAMPLES
// ================================================================================================
// Examples showing various dialogue types and complexity levels
// BUSINESS CONVERSATION:
// {
// "title": "Job Interview",
// "audio": "audio/conversations/job_interview.mp3",
// "conversation": [
// {
// "speaker": "Interviewer",
// "original": "Tell me about your work experience.",
// "userLanguage": "Parlez-moi de votre expérience professionnelle.",
// "timestamp": 1.0,
// "formality": "formal", // Additional metadata for register training
// "cultural_note": "Direct questioning is normal in American job interviews"
// },
// {
// "speaker": "Candidate",
// "original": "I have five years of experience in marketing.",
// "userLanguage": "J'ai cinq ans d'expérience en marketing.",
// "timestamp": 4.5,
// "formality": "formal"
// }
// ]
// }
// CASUAL CONVERSATION:
// {
// "title": "Friends Meeting",
// "conversation": [
// {
// "speaker": "Alex",
// "original": "Hey! How's it going?",
// "userLanguage": "Salut! Comment ça va?",
// "formality": "casual",
// "emotion": "friendly"
// },
// {
// "speaker": "Jordan",
// "original": "Pretty good! Want to grab some coffee?",
// "userLanguage": "Plutôt bien! Tu veux prendre un café?",
// "formality": "casual",
// "speech_act": "invitation"
// }
// ]
// }
// CULTURAL CONTEXT DIALOGUE:
// {
// "title": "British Tea Time",
// "cultural_context": "Traditional British afternoon tea customs",
// "conversation": [
// {
// "speaker": "Host",
// "original": "Would you care for some tea?",
// "userLanguage": "Prendriez-vous du thé?",
// "cultural_note": "Formal invitation typical in British tea culture"
// },
// {
// "speaker": "Guest",
// "original": "That would be lovely, thank you.",
// "userLanguage": "Ce serait merveilleux, merci.",
// "cultural_note": "Polite acceptance maintaining formal register"
// }
// ]
// }
// ================================================================================================
// AI IMPLEMENTATION GUIDELINES FOR DIALOGUES
// ================================================================================================
/*
AUDIO SYNCHRONIZATION:
=====================
- Use timestamp data for precise audio-text alignment
- Support playback controls: play, pause, rewind, segment replay
- Enable click-to-play functionality for individual dialogue lines
- Provide speed adjustment (0.5x to 1.5x) for pronunciation practice
ROLE-PLAY FUNCTIONALITY:
=======================
- Allow learners to select and practice different speaker roles
- Provide recording capability for pronunciation practice
- Compare learner pronunciation with original audio when available
- Support turn-taking exercises with audio cues
COMPREHENSION EXERCISES:
=======================
- Generate comprehension questions based on dialogue content
- Create fill-in-the-blank exercises using dialogue text
- Develop role-appropriate response generation exercises
- Support dialogue completion and continuation activities
CULTURAL INTEGRATION:
====================
- Use cultural_note data for cross-cultural communication training
- Highlight formality and register variations within dialogues
- Provide cultural context explanations for communication patterns
- Enable comparative dialogue analysis across cultures
PROGRESSIVE DIFFICULTY:
======================
- Start with text-only dialogues for reading comprehension
- Progress to audio-supported dialogues for listening skills
- Advance to role-play and production exercises
- Culminate in free conversation based on dialogue patterns
ACCESSIBILITY FEATURES:
======================
- Provide subtitle toggle for hearing-impaired users
- Support keyboard navigation for audio controls
- Enable adjustable text size for visual accessibility
- Offer translation toggle for comprehension support
*/
]
// ========================================================================================================
// FINAL IMPLEMENTATION NOTES
// ========================================================================================================
/*
GLOBAL VALIDATION RULES:
========================
1. Required fields must be present and non-empty
2. Optional fields can be omitted entirely
3. File paths should be validated for existence before use
4. Language codes should follow ISO 639-1 standard
5. Difficulty scales should be consistent (1-10 integers)
6. Cross-references (like prerequisite IDs) should be validated
ERROR HANDLING STRATEGIES:
=========================
1. Missing required fields: Log error and skip content item
2. Missing optional fields: Continue processing with graceful degradation
3. Invalid file paths: Use fallbacks or skip media-dependent features
4. Malformed data: Log error details for content creator feedback
5. Unknown fields: Ignore silently to support future extensibility
PERFORMANCE OPTIMIZATION:
========================
1. Lazy load media files (audio, images) only when needed
2. Cache processed content data for faster subsequent access
3. Pre-validate content structure on load for quick error detection
4. Use efficient data structures for fast content lookup and filtering
5. Implement progressive loading for large content modules
LOCALIZATION SUPPORT:
====================
1. All user-facing text should support translation
2. Cultural content should adapt to learner's cultural context
3. Date, time, and number formats should follow locale conventions
4. Audio content should support multiple accent variations when possible
5. Interface elements should support right-to-left languages when applicable
EXTENSIBILITY FRAMEWORK:
=======================
1. New exercise types can be added without breaking existing content
2. Additional metadata fields can be added to any content section
3. New content sections can be added at the root level
4. Custom field validation can be implemented for specific use cases
5. Plugin architecture should support third-party content enhancements
QUALITY ASSURANCE:
=================
1. Content should be reviewed by native speakers for linguistic accuracy
2. Cultural content should be validated by cultural experts
3. Audio quality should meet professional standards for educational use
4. Visual content should be tested for accessibility and cultural sensitivity
5. Exercise difficulty should be validated through learner testing
*/
}
Reference in New Issue View Git Blame Copy Permalink