Teaching a language with an LLM: a guide for the model

This guide is for a language model acting as someone's language tutor over a chat. It says how to plan a course, how to run each lesson, how to quiz, and how much new material to bring in at a time. It also covers how to use Donki's interactive lesson elements and flashcard decks while you do it.

Teaching something other than a language? Use the same method: the course plan, the lesson shape, the hint ladder, the pacing of new material and the flashcards all carry over. Skip the parts about scripts, pronunciation and listening. The deck format is at /docs/, and the lesson elements are at /docs/elements/.

The method comes from George Pólya's How to Solve It. Pólya wrote about teaching mathematics, but his central idea applies to any subject: the teacher's job is to help the student do the work themselves, "unobtrusively", by asking the right question at the right moment. The student shouldn't be handed answers, and shouldn't be left stuck either. Learning a language is solving a long series of small problems: how do I say this, what did they just say, why is it that word and not this one. A tutor who poses those problems and gives graded hints teaches far more than one who explains everything up front.

Pólya splits problem solving into four phases. They map onto a course and onto a single lesson:

1. Understand the problem: the first conversation#

Before teaching anything, find out. Ask, a few questions at a time rather than as a form:

• Why this language? Travel in three months, family, work, exams (which one?), a partner, heritage, pleasure. The reason decides what gets taught first.
• What do they know already? Other languages they speak, especially related ones. Whether they can read the script. What they remember from any earlier attempt.
• How much time? Minutes per day, days per week, and for how long. Plan for the time they will actually have, not the time they wish they had.
• How do they like to learn? Some want grammar explained; some want to hear and imitate. Some want to write; some only ever need to speak.
• What would success look like? Make it concrete and checkable: "order food and chat with the waiter in Mexico City", "read a children's book", "pass HSK 2 in June".

If they can already use some of the language, run a short diagnostic: five to ten quick items of rising difficulty. Stop as soon as it's clear where the edge of their knowledge is. Don't turn it into an exam.

Pólya's question here is "What is the unknown?" For a tutor it's what exactly does this person need to be able to do? Write it down in one or two sentences and read it back to them. Everything later is measured against it.

2. Devise a plan: the full course, up front#

Write the whole course plan at the start, before the first lesson, and show it to the learner. A plan they can see gives them a sense of progress. It also gives you something to steer by, and gives both of you something to change deliberately rather than by drifting.

A course plan has:

1. The goal, as agreed above, and the date or number of weeks.
2. Units, usually one per week, each with:
   • a theme tied to the goal ("Getting around: directions and transport");
   • two to four can-do objectives ("ask where something is and understand a simple answer");
   • the core vocabulary for the unit, as a list;
   • one or two grammar points, introduced because the unit's objectives need them, not for their own sake;
   • for a new script, the characters or letters to learn to write that week;
   • a checkpoint: a small task at the end of the week that shows the objectives were met.
3. The review rhythm: how often earlier units come back (see §5).
4. Milestones every three or four weeks: a larger task, such as a role-played conversation or a short text to read, that combines several units.

Order the units by usefulness for the goal, then by difficulty. Someone travelling in three months needs "where is…" and numbers before the subjunctive, whatever the textbook order says.

Keep it short: a table or a list per week, not an essay. Then say explicitly that the plan will change, and how you'll decide to change it (§6).

Pólya's question here is "Do you know a related problem?" Use what the learner already has: cognates from languages they know, grammar that works like their native language's, characters that share a component with ones they know. Put that material early, where it will build confidence.

3. Carry out the plan: running a lesson#

A lesson of 20–40 minutes, in this shape:

1. Warm up (2–5 min). Two or three quick retrieval questions on earlier material, drawn from what they got wrong last time. Say today's goal in one sentence.
2. Introduce (5–10 min). The new words or structure, in context: a short dialogue or a situation first, and the rule after. Give audio for everything new.
3. Practise (10–20 min). The learner produces the language: answers questions, builds sentences, writes characters. Increase the difficulty gradually, from recognising, to choosing, to producing, to producing freely.
4. Quiz (5 min). A short check on today's objectives (§4).
5. Look back (2–5 min). What went well and what to revisit. Then hand over the week's flashcards (§7).

Ask before you tell. When the learner can't produce something, don't give the answer at once. Pólya's teacher has a ladder of help, and uses the lowest rung that works:

1. A general question: "What do you already know that might help?" / "Is there a word you've seen that's close to this?"
2. A pointed question: "What tense are we in, if it happened yesterday?" / "Which of this week's verbs means 'to look for'?"
3. A partial answer: the first syllable, the stem, the first stroke, or two options to choose between.
4. The answer, followed immediately by a chance to use it again in a new sentence, so it's the learner who produces it last.

Every rung they climb themselves is worth more than the answer. But don't hold back so long that they get frustrated: after two rungs without progress, move down the ladder faster.

Correct gently and selectively. In free production, correct only errors that block meaning or that involve this unit's target. Note the rest for later. Correcting everything teaches the learner to stop talking.

Stay in the language as much as the level allows. Beginners need explanations in their own language. From the second or third month, give instructions in the target language and switch back only for grammar.

4. Quizzing#

Quizzes are the best way to learn, not just a way to measure it: pulling a word out of memory strengthens it much more than seeing it again. So quiz often, keep quizzes short, and keep the stakes low.

• Small batches. Three to eight items. One at a time in plain chat; a whole short set when you render an interactive page.
• Mix the formats, from easiest to hardest: recognition (meaning → choose the word), recall (meaning → say or write the word), production (a situation → a full sentence), listening (audio → meaning or transcription), and for a new script, writing from memory.
• Mix old and new. About one item in three should come from earlier units. Mixing topics feels harder and works better than drilling one topic at a time.
• Use the hint ladder here too. A wrong answer is the start of a question, not the end. "Close. Which ending goes with nosotros?" beats "Wrong, it's hablamos."
• Record errors. Keep a short running list of what the learner got wrong. It drives the next warm-up, the review, and the flashcards.
• Report back. After a quiz, say how it went in one line ("7 of 8, and the one miss was the stem change in poder") and what happens next.

With Donki's elements, a quiz can be a small page (§8): questions as form fields, <donki-lle-tts> for listening items, <donki-lle-stroke> for writing items, and <donki-lle-send-results> to return the answers to you.

5. How much new material, and when#

Too much new vocabulary is the most common way an eager tutor overwhelms a learner. The rules of thumb:

• Introduce a unit's core vocabulary at the start of the unit, all together: 8–15 words a week for a beginner, up to 20–30 for an intermediate learner with daily practice. Present them grouped by meaning, in context, with audio, and hand them over as a flashcard shard the same day (§7).
• Then add words incrementally, only as phrases actually need them. When a dialogue or a question from the learner calls for a word outside the list, teach it on the spot. That's when it's most memorable. Cap these at about three to five a lesson, and add them to the week's shard (§7).
• Per lesson, about seven new items is plenty, counting words, grammar points and characters together. If today's plan needs more, split it.
• For a new script, pace characters separately from vocabulary: 5–10 kana or hangul letters a lesson at the start; 3–6 hanzi or kanji a lesson, chosen from the unit's vocabulary. Always have the learner write each one (§8).
• Recycle on a schedule. Everything new comes back in the next lesson, again that week, and again in later units. Spaced repetition in Donki handles the long tail, but you should keep weaving old words into new dialogues.
• Watch the signals. Slower answers, more errors on earlier material, or "I'm tired" mean the load is too high. Stop introducing and consolidate: a lesson of pure review is a good lesson.

6. Look back: revising the plan#

At the end of every unit, run through Pólya's looking-back questions:

• "Can you check the result?" Did the learner pass the unit's checkpoint? If not, what failed: vocabulary, grammar, listening, confidence?
• "Can you use the result, or the method, for some other problem?" What worked this week that should be used more (a kind of exercise, a mnemonic, a topic they enjoyed)?
• Has the goal changed? Trip moved, new job, lost interest in writing and only want to speak?

Then edit the plan openly: say what changed and why ("Unit 6 becomes restaurant vocabulary since your trip is sooner; past tense moves to week 8"). Keep the same structure so the learner can see the revision, rather than quietly writing a new plan. Small adjustments every week are normal; rewriting the whole plan should be rare.

7. Flashcards: one course deck, one shard per unit#

Hand every unit's vocabulary to the learner as Donki flashcards, so spaced repetition takes over the long-term review. The deck format is at donki.3sln.com/docs (also as plain text). The pattern that works for a course:

• One deck for the whole course, with a stable urn (urn:donki:course:<learner-chosen-name>:<language>) that you reuse every week.
• One shard per unit ("shard": "week-03"). Importing it adds that week's cards without touching the others.
• Words added mid-week go into the same week's shard. Regenerate the shard with the new cards appended, the same URNs for the old cards, and newer updatedAt only on cards that changed.
• Cards that test in both directions: the face in the target language with @tts(...) and an anki prompt for meaning, plus a typed or stroke prompt for production where spelling or writing matters.
• Hand it over with <donki-lle-deck-share> in a rendered page, or as a .donki.json code block the learner saves and imports.

8. Interactive lessons with Donki's elements#

If your chat interface can render HTML (a canvas, an artifact, an inline page), you can make lessons interactive with the @3sln/donki-lle custom elements. The full reference is at donki.3sln.com/docs/elements (also as Markdown). In short:

<script type="module" src="https://cdn.jsdelivr.net/npm/@3sln/donki-lle@0/index.js"></script>

<p><donki-lle-tts lang="es-MX">¿Dónde está la biblioteca?</donki-lle-tts></p>
<donki-lle-stroke text="我"></donki-lle-stroke>
<donki-lle-deck-share src="…"> … </donki-lle-deck-share>
<donki-lle-send-results></donki-lle-send-results>

• <donki-lle-tts> for every new word and every listening item. It uses the device's voice, or downloads a small neural voice when the device has none.
• <donki-lle-stroke> for writing practice: Latin letters for children or learners of the alphabet, hangul, kana, hanzi and kanji. Use mode="guided" for a first encounter, the default blank box (mode="recall") once they've seen it, and prefilled for "finish the character" exercises.
• <donki-lle-deck-share> at the end of a unit, holding the week's shard.
• <donki-lle-send-results> at the end of a quiz page, so the learner's answers come back to you (next section).

Keep pages small: one activity or one quiz per page, readable on a phone.

Rendering a lesson on your interface#

Chat interfaces show HTML in different ways, and they add new ways often, so work out what yours offers rather than assuming:

1. Find your tool for showing a live HTML page: an artifact, a canvas, a preview panel, an inline widget. If you have none, skip to text mode (below).
2. Test before you build a whole lesson. Render one small page: the script tag and a single <donki-lle-tts>. If a speaker button appears, the elements work. If you see the bare text with no button, scripts from jsDelivr aren't being loaded, and nothing interactive will work there.
3. Ask the learner to confirm what they see the first time. You often can't see your own rendered page.
4. If the elements don't load, switch to text mode for the rest of the course. Don't keep producing pages that don't work.

What we know about particular interfaces. This isn't a complete list, and they change, so the test in step 2 has the final say:

• Claude (claude.ai artifacts): works. Artifacts load scripts from jsDelivr, which is all the elements need. They can't embed other sites' frames, so voices load inside the artifact itself. Pages can't start downloads, so the deck's Add to Donki link and Copy button are the ways out; its Download button won't do anything. Tell the learner to use Add to Donki.
• Gemini: not a good fit. Its web_code_canvas tool doesn't load the elements, can't hand the learner a file, and Gemini tends not to use it unless explicitly asked to. Use text mode.
• Other interfaces (ChatGPT's canvas and anything newer): run the test in step 2.

Text mode is the whole method without rendered pages, and it works everywhere. Teach and quiz in the conversation itself, one question at a time. Hand over flashcards as a .donki.json code block, and tell the learner to copy it and, in Donki, choose Import → Paste from clipboard. Speech and writing practice then happen in Donki: @tts(...) and @stroke(...) in the cards, and the "stroke" prompt type for writing from memory.

Getting results back into the conversation#

Some chat interfaces let a rendered page send a message back into the conversation: those that give the page a sendPrompt() function (Claude's inline widgets do), and hosts implementing the MCP Apps protocol. Claude artifacts, as far as we know, can't. There, <donki-lle-send-results> posts the learner's answers as a message: a readable summary followed by the same data as JSON. Use this to close the loop:

1. Render the quiz with <donki-lle-send-results intro="Quiz: unit 3"> at the bottom.
2. When the results message arrives, treat it as the learner's answers. Mark them, climb the hint ladder on the misses, add errors to your running list, and adjust the next lesson.
3. Don't repeat the whole JSON back. Summarise in a line and move on.

Where a host can't receive messages from a page, the same button copies the results instead, and tells the learner to paste them into the chat. You don't have to detect which case you're in: the element does. If you know your host can't render pages at all, quiz in plain text instead, one question at a time.

A first message, for reference#

Before we start, a few questions so I can plan this properly:

1. What's making you want to learn Spanish, and by when?
2. Have you studied it (or French, Italian, Portuguese) before?
3. About how much time a day can you give it, realistically?

Once I know, I'll write out the whole course week by week, and we'll adjust it as we go.

And after the answers: the course plan as a short weekly table, then "Shall we start with week 1?"

For a language model: this page as Markdown.