Polyglotton Lesson Specification

Version: 1.2.0
Last Updated: 2026-01-25
Canonical URL: https://app.polyglotton.com/lesson-specification.md

This document defines the JSON format for Polyglotton language learning lessons. Use this specification when generating lessons with AI or creating them manually.

🔄 Auto-Generated: This file is automatically generated from src/lib/cardTypes/definitions.ts. Do not edit manually.

Lesson Structure

A lesson is a JSON object with metadata and an array of cards:

{
  "id": "unique-lesson-id",
  "title": "Lesson Title in Source Language",
  "titleNative": "Lesson Title in Target Language",
  "level": "A1",
  "sourceLanguage": "en",
  "targetLanguage": "es",
  "collectionId": "my-collection",
  "intro": "Brief introduction to what this lesson covers",
  "learningOutcome": "What the learner will be able to do after this lesson",
  "realWorldContext": "Why this is useful in real life",
  "cards": []
}

Required Fields

Optional Fields

Collection Organization

Use collectionId to organize related lessons into logical groups:

Examples:

• "collectionId": "travel" - Travel-themed lessons
• "collectionId": "business-spanish" - Business Spanish course
• "collectionId": "grammar-essentials" - Grammar fundamentals
• "collectionId": "daily-life" - Everyday situations

Benefits:

• Lessons with the same collectionId appear grouped together in the library
• Users can filter by collection to find related content
• Creates a logical learning progression within a topic

Language Codes

IMPORTANT: Always use ISO 639-1 two-letter language codes.

❌ Wrong: "sourceLanguage": "English"
✅ Correct: "sourceLanguage": "en"

Card Types

All cards share these base fields:

Field Usage Guidelines

Example distinction:

• story: "María walks into a café. The waiter approaches with a smile."
• context: "This phrase is used when ordering food politely in restaurants."

Card Type Examples

Translation Card

{
  "id": "card-001",
  "exerciseType": "translation",
  "source": "Hello, how are you?",
  "target": ["Hola, ¿cómo estás?", "¿Cómo estás?"],
  "story": "You meet your Spanish friend Ana on the street.",
  "context": "Informal greeting used with friends and peers",
  "explanation": "¿Cómo estás? uses the informal 'tú' form"
}

Reverse Translation Card

For reverse translation, the app will show the target text (target language) and the user must type the source text (source language). source and target always refer to the lesson's configured source/target languages, regardless of card type.

{
    "id": "card-002",
    "exerciseType": "reverse",
    "source": "Hello, how are you?", // source language (what user must type)
    "target": ["Hola, ¿cómo estás?", "¿Cómo estás?"], // target language (what is shown)
    "context": "Common greeting response"
}

Multiple Choice Card

{
  "id": "card-003",
  "exerciseType": "multiple_choice",
  "question": "How do you say 'thank you' in Spanish?",
  "options": ["Gracias", "Por favor", "De nada", "Hola"],
  "correctIndex": 0,
  "explanation": "Gracias is the standard way to say thank you"
}

Cloze (Fill in Blank) Card

{
  "id": "card-004",
  "exerciseType": "cloze",
  "source": "Yo ___ café todos los días.",
  "target": ["bebo", "tomo"],
  "story": "You're describing your daily habits to a new friend.",
  "hint": "First person singular verb for drinking",
  "context": "Used when talking about regular habits or routines",
  "explanation": "'Beber' and 'tomar' both mean 'to drink' - 'tomar' is more common in Latin America"
}

Conversation Card

{
    "id": "card-005",
    "exerciseType": "conversation",
    "dialogue": [
        { "speaker": "bot", "text": "Hi! How can I help you today?" },
        { "speaker": "user", "text": "I'd like a coffee, please." },
        { "speaker": "bot", "text": "Sure—small or large?" },
        { "speaker": "user", "text": "Large, please." }
    ],
    "userPrompts": [
        {
            "prompt": "Hi! How can I help you today?",
            "acceptableResponses": [
                "I'd like a coffee, please.",
                "Can I have a coffee, please?"
            ]
        },
        {
            "prompt": "Sure—small or large?",
            "acceptableResponses": ["Large, please.", "A large one, please."]
        }
    ],
    "context": "Ordering at a café"
}

Listening Card

{
    "id": "card-006",
  "exerciseType": "listening",
  "transcript": "Buenos días, ¿qué tal?",
  "question": "What time of day is this greeting for?",
  "options": ["Morning", "Afternoon", "Evening", "Night"],
  "correctIndex": 0
}

Dictation Card

{
    "id": "card-013",
    "exerciseType": "dictation",
    "transcript": "Buenos días, ¿qué tal?", // what the learner hears (used for TTS)
    "correctText": "Buenos días, ¿qué tal?", // what the learner must type
    "audioUrl": "https://example.com/audio.mp3", // optional, ONLY INCLUDE THIS IF YOU HAVE A VALID MP3 URL that is relevant, provided by the user. 
    "story": "A friend greets you in the morning.",
    "context": "Common morning greeting"
}

Matching Card

{
    "id": "card-014",
    "exerciseType": "matching",
    "question": "Match each phrase to its meaning",
    "pairs": [
        { "left": "Buenos días", "right": "Good morning" },
        { "left": "Buenas noches", "right": "Good night" },
        { "left": "Gracias", "right": "Thank you" }
    ],
    "context": "Common everyday phrases"
}

Story Fragment Card

{
    "id": "card-007",
  "exerciseType": "story_fragment",
  "story": "María walks into a café. The waiter approaches her table.",
  "source": "Buenos días, ¿qué le pongo?",
  "question": "What is the waiter asking María?",
  "options": ["What would you like?", "How are you?", "Where are you from?", "What time is it?"],
  "correctIndex": 0
}

Explanation Then Apply Card

{
    "id": "card-008",
  "exerciseType": "explanation_then_apply",
  "explanation": "In Spanish, adjectives must agree in gender and number with the noun they modify.",
  "examples": [
    { "target": "El gato negro", "source": "The black cat (masculine)" },
    { "target": "La gata negra", "source": "The black cat (feminine)" }
  ],
  "challenge": "Choose the correct form: 'La casa ___' (big)",
  "options": ["grande", "grandes", "gran", "grandos"],
  "correctIndex": 0
}

Production Challenge Card

Important grading note: free-form writing is only auto-gradable if you provide either:

1. Exact acceptable answers via acceptableResponses (best when the expected output is a single word/phrase), or
2. Keyword grading via metadata.grading (best when you want to allow longer answers but still validate required elements).

Option A — Exact answers (recommended when there is one correct synonym/phrase)

{
    "id": "card-009",
  "exerciseType": "production_challenge",
  "scenario": "You're at a restaurant and want to order a coffee with milk.",
    "source": "Order a coffee with milk politely",
  "acceptableResponses": [
    "Un café con leche, por favor",
    "¿Me pone un café con leche?",
    "Quiero un café con leche, por favor"
  ],
    "hint": "Include a polite phrase like 'por favor'",
  "context": "Restaurant ordering"
}

Option B — Keyword grading (recommended for longer, freer answers)

Use this when there are many valid paraphrases. The learner can write freely, but the answer must include certain required words/phrases.

⚠️ Field usage (consistent with other card types):

• story: Essential reading/context shown BEFORE answering (e.g., "The text says: '...'")
• hint: Clue/tip shown BEFORE answering (e.g., "It starts with meg-...")
• context: Usage notes shown AFTER answering (e.g., "When to use this phrase")

{
    "id": "card-010",
    "exerciseType": "production_challenge",
    "scenario": "You are explaining what an old dialect word means.",
    "source": "Translate the meaning into the synonym used in the text.",
    "story": "The text says: '...vagy ahogy ők mondták, annyira zsöndítették...'",
    "hint": "It starts with meg-...",
    "acceptableResponses": ["meghizlalták"],
    "context": "This is a regional dialect variation still used in rural Hungary",
    "metadata": {
        "grading": {
            "mode": "keywords",
            "required": ["meghizlalták"]
        }
    }
}

Note: This card type is available but not included in default lesson presets. It can still be used in manually created lessons.

Cultural Insight Card

{
    "id": "card-010",
  "exerciseType": "cultural_insight",
  "culturalInsight": "In Spain, lunch (la comida) is typically the largest meal of the day, served between 2-4 PM. Dinner (la cena) is lighter and eaten around 9-10 PM.",
  "question": "When is the main meal typically served in Spain?",
  "options": ["2-4 PM", "12-1 PM", "6-7 PM", "8-9 AM"],
  "correctIndex": 0,
  "reasoning": "Spanish culture has a different meal schedule than many other countries"
}

Comprehensive Reading Card

{
    "id": "card-012",
  "exerciseType": "comprehensive_reading",
  "readingText": "María vive en Madrid. Ella trabaja en una oficina cerca del centro. Todos los días, toma el metro para ir al trabajo. Le gusta mucho su trabajo porque tiene buenos compañeros.",
  "comprehensionQuestions": [
    {
      "question": "¿Dónde vive María?",
      "type": "multiple_choice",
      "options": ["Madrid", "Barcelona", "Valencia", "Sevilla"],
      "correctIndex": 0
    },
    {
      "question": "¿Cómo va María al trabajo?",
      "type": "multiple_choice",
      "options": ["En metro", "En autobús", "En coche", "A pie"],
      "correctIndex": 0
    },
    {
      "question": "¿Por qué le gusta su trabajo?",
      "type": "short_answer",
      "answer": ["tiene buenos compañeros", "buenos compañeros", "por los compañeros"]
    }
  ]
}

Notes:

• multiple_choice (recommended): Use correctIndex to specify which option is correct (0-indexed). Requires options array.
• short_answer (advanced): Use answer field with a string or array of acceptable answers. More challenging for learners.

Speaking Card

{
  "id": "card-014",
  "exerciseType": "speaking",
  "prompt": "Say this phrase out loud",
  "target": ["Buenos días, ¿cómo está usted?", "Buenos días, ¿cómo está?"],
  "translation": "Good morning, how are you?",
  "hint": "Practice the formal greeting",
  "context": "Use this when greeting someone formally",
  "explanation": "Multiple acceptable pronunciations are supported"
}

Notes:

• target can be a string or array of strings for synonym support
• Speech recognition will accept any of the provided variations

Reordering Card

{
  "id": "card-015",
  "exerciseType": "reordering",
  "shuffledWords": ["es", "libro", "un", "Este"],
  "correctOrder": ["Este", "es", "un", "libro"],
  "translation": "This is a book",
  "hint": "Start with the demonstrative pronoun",
  "context": "Basic sentence structure practice"
}

CEFR Level Guidelines

Best Practices

1. Unique IDs: Every card must have a unique id field (e.g., card-001, card-002)

2. Progressive Difficulty: Start with simpler cards, gradually increase complexity

3. Contextual Learning: Include real-world usage context for each card

4. Multiple Acceptable Answers: For translation cards, provide an array of acceptable answers

5. Cultural Notes: Add cultural context where relevant

6. Intrinsic Motivation: Make content personally relevant and practically useful

7. Language Separation: The source field in cloze cards must contain ONLY target language text. Never mix languages. Use story or context for source language explanations.

8. Language Codes: Always use ISO 639-1 two-letter codes (en, es, de, fr, hu, nl, etc.) NOT full language names

9. Collection Organization: Use collectionId to group related lessons into coherent series or topics

Complete Example

{
  "id": "greetings-basics-01",
  "title": "Basic Greetings",
  "titleNative": "Saludos básicos",
  "level": "A1",
  "sourceLanguage": "en",
  "targetLanguage": "es",
  "collectionId": "spanish-fundamentals",
  "intro": "Learn essential Spanish greetings for everyday situations.",
  "learningOutcome": "You will be able to greet people and introduce yourself in Spanish.",
  "realWorldContext": "These phrases are used daily in Spanish-speaking countries.",
  "cards": [
    {
      "id": "card-001",
      "exerciseType": "translation",
      "source": "Hello",
      "target": ["Hola"],
      "context": "Universal greeting, used any time of day",
      "explanation": "Hola is informal and friendly"
    },
    {
      "id": "card-002",
      "exerciseType": "multiple_choice",
      "question": "How do you say 'Good morning' in Spanish?",
      "options": ["Buenos días", "Buenas tardes", "Buenas noches", "Hola"],
      "correctIndex": 0,
      "explanation": "Buenos días is used until around noon"
    },
    {
      "id": "card-003",
      "exerciseType": "cloze",
      "source": "¿Cómo ___ llamas?",
      "target": ["te"],
      "hint": "Reflexive pronoun for 'tú'",
      "context": "Asking someone's name informally",
      "explanation": "Llamarse is a reflexive verb meaning 'to be called'"
    }
  ]
}

Validation

Lessons are validated using Zod schemas. The app will automatically:

• Normalize language names to ISO codes (e.g., "English" → "en")
• Validate CEFR levels
• Ensure required fields are present
• Check card structure based on exercise type

For the full schema definition, see the source code at: src/lib/schemas/lesson.ts

Generating Lessons with AI

You can use any LLM (ChatGPT, Claude, Gemini, Mistral, etc.) to generate lessons. Simply:

1. Share this specification URL with the AI
2. Describe the lesson you want (topic, level, languages)
3. Ask for JSON output following this specification

Example prompt:

Read https://app.polyglotton.com/lesson-specification.html and generate a Spanish lesson about ordering food at a restaurant, level A2, for English speakers. Include 10 cards with a mix of translation, cloze, and multiple choice exercises.

This specification is maintained at: static/lesson-specification.md
Generated from: src/lib/cardTypes/definitions.ts