translate-lesson
Translate or sync an English lesson/topic into its Spanish twin (or vice-versa) for this Lessons site, keeping frontmatter, slugs, order, headings and interactive-component label props in parity. Span
SKILL.md.claude/skills/translate-lesson/SKILL.md
GitHubTranslate / sync a bilingual twin
Every lesson and topic exists in both en/ and es/ at mirrored paths.
This skill keeps the pair in sync. The source is usually English; reverse the
directions if translating es → en.
⚠️ The es locale is Spanish from Spain (es-ES, Castilian)
All Spanish content is peninsular Spanish (Spain), not Latin-American.
The site declares es-ES (see astro.config.mjs sitemap locales). Write
accordingly:
vosotrosfor informal plural "you";túinformal singular. Avoidustedes/vosregister choices that read as Latin-American.- Castilian vocabulary:
ordenador(notcomputadora),móvil(notcelular),vale(notokay),coche,zumo, etc. - Spain spelling/usage and natural peninsular idioms.
seseo-neutral spelling is fine, but lexical choices must be Spain's. - Humor and analogies (see
lesson-copy) should land for a Spain audience — adapt references, don't translate them literally.
1. Locate the pair
en: src/content/lessons/en/<topic>/<lesson>.mdx
es: src/content/lessons/es/<topic>/<lesson>.mdx ← same topic + lesson slug
Topics mirror the same way under src/content/{topics,lessons}/<lang>/….
Slugs and folder names stay identical across locales — only the prose and
label props are translated, never the URL.
2. Keep frontmatter in parity
Copy the source frontmatter, translate title / description / tagline, and
change only the locale-bound topic reference:
- es lesson:
topic: "es/<topic>"(en uses"en/<topic>"). - Keep
order,minutes,icon,accent,draftidentical to the twin. - Keep
updatedin sync (bump both when content changes).
3. Translate body, preserve structure
- Same number and nesting of
##/###headings (they drive the ToC) — translate the heading text, keep the hierarchy. - Keep all
import { … } from '@/components/react'lines unchanged. - Translate prose,
Callouttitles/bodies,MCQ/Quizquestions, options, and explanations. - Keep math, code blocks, and
client:*directives byte-identical.
4. Localize component label props (critical)
Interactive islands render UI chrome in their props — pass the Spanish labels in the es file:
MCQ:checkLabel="Comprobar",retryLabel="Reintentar"Quiz:questionLabel="Pregunta",ofLabel="de",scoreLabel="Tu puntuación",restartLabel="Reiniciar",nextLabel="Siguiente",backLabel="Atrás"MCQ pretest:pretestLabel="Antes de leer — adivina"(+ the usual MCQ labels)MatchConcepts/Categorize/FillBlank:checkLabel="Comprobar",retryLabel="Reintentar",explanationLabel="Explicación", and translateinstructions(e.g."Coloca cada elemento en su grupo."/"Elige la opción correcta para cada hueco y comprueba.")MindMap: translatetitle,caption,eyebrow="Visión de conjunto",outlineLabel="Esquema", and every nodelabelin theroottree (FillBlanktextblanks — the correct answer AND its distractor options — must all be translated to Spanish)
Confirm exact prop names against src/components/react/* (or DESIGN.md)
before writing — props evolve.
5. Verify parity
bun run check # 0 errors required
Check both twins exist, share slug/order/topic, and have the same heading count. Then regenerate OG cards and stage them:
bun run pre-commit # audit:fix + check + build + og:generate
git add public/og