Class_generator/english_exemple_commented.json

{
    // ========================================
    // EDUCATIONAL CONTENT MODULE SPECIFICATION
    // ========================================
    // This JSON defines a complete content module for language learning applications.
    // All fields are OPTIONAL unless explicitly marked as REQUIRED.
    // Systems should gracefully handle missing fields and adapt functionality accordingly.

    // === CORE METADATA (REQUIRED) ===
    // Essential identification and configuration data
    "id": "english_class_demo_complete_example",  // REQUIRED: Unique identifier (lowercase, underscores)
    "name": "English Class Demo - Complete Example",  // REQUIRED: Human-readable display name
    "description": "Comprehensive example showcasing all content structure possibilities",  // REQUIRED: Brief description
    "difficulty": 6,  // REQUIRED: Integer 1-10 (1=absolute beginner, 10=native level)
    "original_lang": "english",      // REQUIRED: ISO language code of source content
    "user_lang": "french",           // REQUIRED: ISO language code for translations
    "icon": "assets/icons/uk-flag.svg",  // OPTIONAL: Path to icon file (relative or absolute)
    "icon_fallback": "🇬🇧",             // REQUIRED if icon specified: Emoji fallback for missing files

    // === CLASSIFICATION SYSTEM ===
    // Used for content discovery, filtering, and game compatibility assessment
    "tags": [
        // Content characteristics - systems can filter/search using these
        "beginner-friendly",    // Suitable for beginners (difficulty ≤ 4)
        "audio-rich",          // Contains significant audio content (>50% items have audio)
        "grammar-focus",       // Emphasizes grammar learning (has grammar section)
        "cultural-content",    // Includes cultural context (has cultural section)
        "interactive",         // Has interactive exercises (matching, corrections, etc.)
        "daily-life",          // Real-world applicable content
        "conversation",        // Dialogue-based learning (has dialogues section)
        "multimedia"           // Multiple content types (text, audio, visual)
    ],

    // === LEARNING OBJECTIVES ===
    // Skills and competencies this module addresses - used for progress tracking
    "skills_covered": [
        "vocabulary_recognition",     // Identifying and understanding words
        "vocabulary_production",      // Using words correctly in context
        "listening_comprehension",    // Understanding spoken language
        "reading_comprehension",      // Understanding written text
        "pronunciation",              // Correct sound production
        "grammar_application",        // Using grammar rules correctly
        "cultural_awareness",         // Understanding cultural context
        "conversation_skills",        // Interactive dialogue ability
        "translation",               // Converting between languages
        "pattern_recognition",        // Identifying linguistic patterns
        "error_correction",          // Identifying and fixing mistakes
        "audio_discrimination"       // Distinguishing between sounds
    ],

    // ========================================
    // VOCABULARY SECTION - PROGRESSIVE COMPLEXITY
    // ========================================
    // Word definitions with varying levels of detail. Systems should adapt based on available data.
    "vocabulary": {

        // LEVEL 1: MINIMAL (Translation only)
        // Simplest form - just word and translation string
        // Usage: Basic vocabulary games, simple matching
        "cat": "chat",
        "dog": "chien",
        "house": "maison",

        // LEVEL 2: BASIC (Essential data)
        // Translation + grammatical type
        // Usage: Games that need word categorization
        "book": {
            "translation": "livre",
            "type": "noun"  // Values: noun, verb, adjective, adverb, greeting, number, etc.
        },

        "read": {
            "translation": "lire",
            "type": "verb"
        },

        // LEVEL 3: MEDIUM (Enhanced with media OR pronunciation)
        // Add ONE media type: pronunciation OR image
        // Usage: Games with visual or audio components
        "apple": {
            "translation": "pomme",
            "type": "noun",
            "pronunciation": "/ˈæp.əl/",  // IPA phonetic notation (recommended format)
            "image": "images/vocabulary/apple.jpg"  // Path to image file
        },

        "beautiful": {
            "translation": "beau/belle",
            "type": "adjective",
            "pronunciation": "/ˈbjuː.tɪ.fəl/",
            "examples": ["The sunset is beautiful"]  // Array of usage examples
        },

        // LEVEL 4: RICH (Multi-media)
        // Multiple media types for enhanced learning
        // Usage: Advanced vocabulary games, multimedia lessons
        "elephant": {
            "translation": "éléphant",
            "type": "noun",
            "pronunciation": "/ˈel.ɪ.fənt/",
            "audio": "audio/vocabulary/elephant.mp3",  // Audio pronunciation file
            "image": "images/vocabulary/elephant.jpg", // Visual representation
            "examples": [
                "The elephant is huge",
                "Elephants have good memory"
            ]
        },

        // LEVEL 5: COMPREHENSIVE (Full linguistic data)
        // Maximum detail for advanced language learning
        // Usage: Professional language learning, detailed grammar games
        "run": {
            "translation": "courir",
            "type": "verb",
            "pronunciation": "/rʌn/",
            "audio": "audio/vocabulary/run.mp3",
            "image": "images/vocabulary/run_action.gif",  // Can be GIF for actions
            "examples": [
                "I run in the park every morning",
                "She runs faster than me",
                "They ran to catch the bus"
            ],
            "grammarNotes": "Irregular verb: run/runs/running/ran/run",  // Teaching notes
            "conjugation": {  // Verb forms for grammar games
                "present": ["run", "runs"],
                "past": "ran",
                "participle": "run",
                "continuous": "running"
            },
            "difficulty_context": "Physical action verb - easy to demonstrate"  // Teaching hints
        },

        // LEVEL 6: ADVANCED (Cultural context)
        // Includes cultural and contextual information
        // Usage: Cultural awareness games, advanced language courses
        "breakfast": {
            "translation": "petit-déjeuner",
            "type": "noun",
            "pronunciation": "/ˈbrek.fəst/",
            "audio": "audio/vocabulary/breakfast.mp3",
            "image": "images/vocabulary/breakfast.jpg",
            "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"
        }
    },

    // ========================================
    // GRAMMAR SYSTEM - STRUCTURED LESSONS
    // ========================================
    // Step-by-step grammar instruction with alternating explanations and exercises
    // NOTE: This system is for dedicated grammar games/apps, not general content games
    "grammar": {
        "present_simple_be": {  // Lesson identifier (must be unique)
            "id": "present_simple_be",  // Same as key for validation
            "title": "Present Simple - Verb 'to be'",  // Display title
            "difficulty": 3,  // 1-10 scale
            "prerequisite": null,  // null = no prerequisite, or reference another lesson id
            "estimated_time": 15,  // Estimated minutes to complete
            "learning_objectives": [  // Clear, measurable goals
                "Conjugate 'to be' in present tense",
                "Use 'to be' in affirmative sentences",
                "Form questions with 'to be'"
            ],

            // Sequential learning steps - MUST be in order
            "steps": [
                {
                    "type": "explanation",  // Types: "explanation" or "exercise"
                    "order": 1,  // Integer ordering (must be sequential)
                    "title": "Introduction to 'be'",
                    "content": "The verb 'to be' is the most important verb in English. It has three forms in present tense.",
                    "translation": "Le verbe 'être' est le verbe le plus important en anglais. Il a trois formes au présent.",
                    "examples": [  // Array of example objects
                        { "original": "I am happy", "userLanguage": "Je suis heureux" },
                        { "original": "You are smart", "userLanguage": "Tu es intelligent" },
                        { "original": "She is tall", "userLanguage": "Elle est grande" }
                    ]
                },
                {
                    "type": "exercise",
                    "order": 2,
                    "exercise_type": "multiple_choice",  // Exercise types: multiple_choice, transformation, fill_blanks, classification, conjugation
                    "title": "Choose the correct form",
                    "questions": [  // Array of question objects
                        {
                            "question": "I ___ a student",
                            "options": ["am", "is", "are"],  // Array of choices
                            "correct": "am",  // Single correct answer
                            "explanation": "Use 'am' with 'I'"  // Feedback for learner
                        },
                        {
                            "question": "She ___ my friend",
                            "options": ["am", "is", "are"],
                            "correct": "is",
                            "explanation": "Use 'is' with 'she', 'he', 'it'"
                        }
                    ]
                },
                {
                    "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 contraction form
                        }
                    ]
                },
                {
                    "type": "exercise",
                    "order": 4,
                    "exercise_type": "transformation",
                    "title": "Make these sentences negative",
                    "questions": [
                        {
                            "original": "I am busy",  // Source sentence
                            "correct": "I am not busy",  // Primary correct answer
                            "alternative_correct": ["I'm not busy"]  // Array of acceptable alternatives
                        }
                    ]
                }
            ],

            // Lesson summary and reinforcement
            "summary": {
                "key_points": [  // Main takeaways
                    "I am, you are, he/she/it is, we are, they are",
                    "Negative: add 'not' after 'be'",
                    "Questions: put 'be' before subject"
                ],
                "common_mistakes": [  // Frequent errors with corrections
                    {
                        "incorrect": "I are happy",
                        "correct": "I am happy",
                        "explanation": "Use 'am' with 'I'"
                    }
                ]
            }
        }
    },

    // ========================================
    // TEXT CONTENT - FLEXIBLE USAGE
    // ========================================
    // Text-based content that can optionally include exercises
    "texts": [
        {
            "title": "My Daily Routine",  // Display title
            "content": "I wake up at 7 AM every day. First, I brush my teeth and take a shower...",  // Main text
            "translation": "Je me réveille à 7h tous les jours. D'abord, je me brosse les dents...",  // Full translation

            // OPTIONAL: Add comprehension questions to any text
            "questions": [
                {
                    "question": "What time does the person wake up?",
                    "type": "multiple_choice",  // Types: multiple_choice, ai_interpreted
                    "options": ["6 AM", "7 AM", "8 AM", "9 AM"],
                    "correctAnswer": "7 AM"
                },
                {
                    "question": "Describe the person's evening routine",
                    "type": "ai_interpreted",  // Requires AI evaluation
                    "evaluationPrompt": "Check if answer mentions cooking dinner and watching TV"  // Prompt for AI evaluator
                }
            ],

            // OPTIONAL: Add fill-in-the-blank exercises to any text
            "fillInBlanks": [
                {
                    "sentence": "I wake up ___ 7 AM every day",
                    "options": ["at", "in", "on"],  // Multiple choice options
                    "correctAnswer": "at",
                    "explanation": "Use 'at' with specific times"
                },
                {
                    "sentence": "The routine is very ___",
                    "type": "open_ended",  // Open-ended answer
                    "acceptedAnswers": ["good", "nice", "healthy", "regular"],  // Acceptable answers
                    "aiPrompt": "Check if answer describes routine positively"  // AI evaluation prompt
                }
            ]
        }
    ],

    // ========================================
    // AUDIO-ONLY CONTENT
    // ========================================
    // Pure listening exercises WITHOUT transcripts
    // NOTE: Audio WITH text should go in texts[] or dialogues[] sections
    "audio": [
        {
            "title": "Mystery Conversation - Restaurant",
            "audioFile": "audio/listening/restaurant_sounds.mp3",  // Audio file path
            "type": "ambient_listening",  // Types: ambient_listening, sound_identification, pronunciation_exercise
            "description": "Listen to the ambient sounds and conversation",  // Optional description
            "questions": [  // Listening comprehension questions
                {
                    "question": "Where does this conversation take place?",
                    "type": "multiple_choice",
                    "options": ["Restaurant", "Office", "School", "Park"],
                    "correctAnswer": "Restaurant"
                },
                {
                    "question": "How many people are speaking?",
                    "type": "ai_interpreted",
                    "evaluationPrompt": "Accept numeric answers indicating number of distinct voices"
                }
            ]
        },
        {
            "title": "Pronunciation Discrimination",
            "audioFile": "audio/pronunciation/minimal_pairs.mp3",
            "type": "pronunciation_exercise",
            "description": "Listen to similar sounding words and identify differences",
            "word_pairs": [  // For pronunciation exercises
                ["ship", "sheep"],
                ["live", "leave"],
                ["cat", "cut"]
            ]
        }
    ],

    // ========================================
    // CULTURAL CONTENT - RICH CONTEXT
    // ========================================
    // Cultural material with educational value and context
    "cultural": {
        // Poetry and literary works
        "poems": [
            {
                "title": "Roses Are Red",
                "content": "Roses are red,\nViolets are blue,\nSugar is sweet,\nAnd so are you.",
                "translation": "Les roses sont rouges,\nLes violettes sont bleues...",
                "audio": "audio/poems/roses.mp3",  // Optional audio recitation
                "image": "images/cultural/roses_poem_illustration.jpg",  // Optional illustration
                "type": "nursery_rhyme",  // Types: nursery_rhyme, classic_poem, song, etc.
                "cultural_context": "Traditional English nursery rhyme pattern...",
                "learning_focus": ["rhyme_patterns", "basic_vocabulary", "rhythm"]  // Educational objectives
            }
        ],

        // Proverbs and sayings
        "proverbs": [
            {
                "original": "The early bird catches the worm",
                "userLanguage": "L'avenir appartient à ceux qui se lèvent tôt",
                "meaning": "People who wake up early and start working have better chances of success",
                "image": "images/cultural/early_bird_illustration.jpg",
                "cultural_context": "Common English saying emphasizing the value of being proactive...",
                "equivalent_proverbs": {  // Cross-cultural equivalents
                    "french": "L'avenir appartient à ceux qui se lèvent tôt",
                    "literal": "Le premier oiseau attrape le ver"
                }
            }
        ],

        // Unified cultural facts system
        "culture_facts": [
            {
                "name": "Tea Time",
                "category": "tradition",  // Categories: tradition, holiday, food, custom, etc.
                "description": "Traditional British custom of drinking tea in the afternoon, usually around 4 PM",
                "translation": "L'heure du thé - tradition britannique...",
                "image": "images/cultural/tea_time.jpg",
                "cultural_significance": "Social ritual that brings people together...",
                "vocabulary_related": ["tea", "biscuit", "afternoon", "tradition", "social"],  // Related vocabulary
                "region": "uk"  // Geographic association (uk, us, global, etc.)
            },
            {
                "name": "Christmas",
                "category": "holiday",
                "date": "December 25th",  // Optional date field for holidays
                "description": "Major Christian holiday celebrating the birth of Jesus Christ",
                "translation": "Noël - grande fête chrétienne...",
                "image": "images/cultural/christmas_celebration.jpg",
                "customs": ["gift_giving", "family_gatherings", "christmas_tree", "caroling"],  // Associated customs
                "vocabulary_related": ["Christmas", "gift", "tree", "family", "celebration"],
                "region": "global"
            },
            {
                "name": "Fish and Chips",
                "category": "food",
                "description": "Traditional British dish of battered fish with fried potatoes",
                "translation": "Poisson-frites - plat britannique traditionnel...",
                "image": "images/cultural/fish_and_chips.jpg",
                "cultural_context": "Popular working-class meal, often served in newspaper wrapping",
                "vocabulary_related": ["fish", "chips", "batter", "traditional", "popular"],
                "region": "uk",
                "ingredients": ["fish", "potatoes", "batter", "oil"],  // For food items
                "typical_sides": ["mushy_peas", "tartar_sauce", "malt_vinegar"]
            }
        ]
    },

    // ========================================
    // SENTENCES WITH PARAMETERS
    // ========================================
    // Generic sentence structure used for various exercises including corrections
    "sentences": [
        {
            "original": "Hello, how are you?",  // Source language sentence
            "userLanguage": "Bonjour, comment allez-vous?",  // Target language translation
            "type": "greeting",  // Sentence classification
            "formality": "neutral"  // Additional parameter
        },
        {
            "original": "I like to read books",
            "userLanguage": "J'aime lire des livres",
            "type": "preference_statement",
            "tense": "present_simple"
        },

        // Sentences with correction exercise data
        {
            "original": "I am happy today",  // CORRECT version
            "userLanguage": "Je suis heureux aujourd'hui",
            "type": "correction_target",  // Indicates this is for correction exercises
            "correction_data": {
                "incorrect_versions": [  // Array of common mistakes
                    {
                        "text": "I are happy today",  // Incorrect version
                        "error_type": "subject_verb_agreement",  // Classification of error
                        "explanation": "Use 'am' with pronoun 'I', not 'are'",
                        "difficulty": 2  // Difficulty of catching this error (1-10)
                    },
                    {
                        "text": "I is happy today",
                        "error_type": "subject_verb_agreement",
                        "explanation": "Use 'am' with pronoun 'I', not 'is'",
                        "difficulty": 1  // Easier to spot
                    }
                ],
                "grammar_focus": "be_verb_conjugation",  // Grammar topic
                "common_mistake": true  // Boolean: is this a frequent error?
            }
        }
    ],

    // ========================================
    // MATCHING EXERCISES - DUAL SYSTEM
    // ========================================
    // Two types of matching exercises: traditional 2-column and flexible multi-column
    "matching": [

        // TYPE 1: Traditional two-column matching (backward compatibility)
        {
            "title": "Match Animals to Their Sounds",
            "type": "two_column_matching",  // Explicit type declaration
            "leftColumn": ["Cat", "Dog", "Cow", "Bird"],  // Left side items
            "rightColumn": ["Woof", "Meow", "Tweet", "Moo"],  // Right side items
            "correctPairs": [  // Valid connections
                { "left": "Cat", "right": "Meow" },
                { "left": "Dog", "right": "Woof" },
                { "left": "Cow", "right": "Moo" },
                { "left": "Bird", "right": "Tweet" }
            ]
        },

        // TYPE 2: Multi-column matching (new flexible system)
        {
            "title": "Build Correct Sentences",
            "type": "multi_column_matching",  // Flexible N-column system
            "columns": [  // Array of columns (minimum 2, no maximum)
                {
                    "id": 1,  // REQUIRED: Numeric identifier for referencing
                    "name": "Subject",  // OPTIONAL: Display label (can be omitted)
                    "items": ["I", "She", "They", "We"]  // REQUIRED: Items in this column
                },
                {
                    "id": 2,
                    "name": "Verb",
                    "items": ["am", "is", "are", "are"]
                },
                {
                    "id": 3,
                    "name": "Complement",
                    "items": ["happy", "a teacher", "students", "friends"]
                }
            ],
            "valid_combinations": [  // Valid combinations using column IDs
                {"1": "I", "2": "am", "3": "happy"},  // References by column ID
                {"1": "I", "2": "am", "3": "a teacher"},
                {"1": "She", "2": "is", "3": "happy"},
                {"1": "She", "2": "is", "3": "a teacher"},
                {"1": "They", "2": "are", "3": "students"},
                {"1": "They", "2": "are", "3": "friends"},
                {"1": "We", "2": "are", "3": "students"},
                {"1": "We", "2": "are", "3": "friends"}
            ]
        },

        // TYPE 2 Example without column names (demonstrates flexibility)
        {
            "title": "Match Country Information",
            "type": "multi_column_matching",
            "columns": [
                {
                    "id": 1,
                    "name": "Country",
                    "items": ["France", "Spain", "Italy", "Germany"]
                },
                {
                    "id": 2,
                    "name": "Capital",
                    "items": ["Paris", "Madrid", "Rome", "Berlin"]
                },
                {
                    "id": 3,
                    // NO "name" field - demonstrates optional nature
                    "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"}
            ]
        }
    ],

    // ========================================
    // DIALOGUES - CONVERSATIONAL CONTENT
    // ========================================
    // Structured conversations between speakers
    // NOTE: Audio WITH text belongs here, not in audio[] section
    "dialogues": [
        {
            "title": "At the Restaurant",  // Dialogue title
            "conversation": [  // Array of turns in conversation
                {
                    "speaker": "Waiter",  // Speaker identification
                    "original": "Good evening! Welcome to our restaurant.",
                    "userLanguage": "Bonsoir! Bienvenue dans notre restaurant."
                },
                {
                    "speaker": "Customer",
                    "original": "Thank you. Can I see the menu please?",
                    "userLanguage": "Merci. Puis-je voir le menu s'il vous plaît?"
                }
            ]
        },

        // Dialogue with synchronized audio
        {
            "title": "Daily Routine Conversation",
            "audio": "audio/conversations/daily_routine.mp3",  // Audio file with spoken dialogue
            "conversation": [
                {
                    "speaker": "A",
                    "original": "What time do you wake up?",
                    "userLanguage": "À quelle heure te réveilles-tu?",
                    "timestamp": 0.5  // OPTIONAL: Time in audio file (seconds)
                },
                {
                    "speaker": "B",
                    "original": "I usually wake up at 7 AM.",
                    "userLanguage": "Je me réveille habituellement à 7h.",
                    "timestamp": 3.2
                }
            ]
        }
    ]

    // ========================================
    // IMPLEMENTATION NOTES FOR AI SYSTEMS
    // ========================================
    /*
    FIELD OPTIONALITY:
    - All fields are optional unless marked REQUIRED
    - Systems should gracefully handle missing fields
    - Adapt functionality based on available data richness

    VOCABULARY LEVELS:
    - Level 1 (string): Basic games only
    - Level 2-3 (basic object): Standard games
    - Level 4-6 (rich object): Advanced features

    EXERCISE TYPES:
    - multiple_choice: Fixed options with single correct answer
    - transformation: Convert one form to another
    - fill_blanks: Complete sentences with missing words
    - classification: Categorize items into groups
    - conjugation: Verb form exercises
    - ai_interpreted: Requires AI evaluation with prompt

    AUDIO PLACEMENT:
    - audio[]: ONLY for content without transcripts
    - texts[]/dialogues[]: For content WITH transcripts
    - vocabulary.*.audio: Individual word pronunciation

    MATCHING SYSTEMS:
    - two_column_matching: Traditional left-right matching
    - multi_column_matching: Flexible N-column system with numeric IDs

    CULTURAL CONTENT:
    - poems[]: Literary works with cultural context
    - proverbs[]: Sayings with cross-cultural equivalents
    - culture_facts[]: Unified system for traditions, holidays, food, customs

    ERROR HANDLING:
    - Missing files (audio, images): Use fallbacks or skip features
    - Invalid references: Ignore and continue with available content
    - Malformed data: Log errors but don't crash, use defaults

    EXTENSIBILITY:
    - New exercise types can be added without breaking existing systems
    - Additional fields can be added to any section
    - New sections can be added at root level
    - Systems should ignore unknown fields gracefully
    */
}