Markdown Translator (Direct Translation)

Translate learn-app docs (MD/MDX) to a target language using direct whole-file translation. No segment extraction, no JSON intermediary, no reassembly scripts.

Official Documentation

Resource	URL	Use For
Docusaurus i18n	https://docusaurus.io/docs/i18n/tutorial	Internationalization setup, locale configuration
MDX syntax	https://mdxjs.com/docs/what-is-mdx/	MDX component syntax and usage
Unicode Bidirectional	https://www.w3.org/International/articles/inline-bidi-markup/	Understanding RTL/LTR text mixing

Architecture

Note: This skill is configured for the apps/learn-app/ Docusaurus site structure. For other projects, adjust the base path accordingly.

apps/learn-app/
├── docs/                  ← English source (default plugin)
├── docs-zh/               ← Chinese (starts as copy of docs/, files replaced)
├── docs-ur/               ← Urdu
├── docs-ar/               ← Arabic
├── docs-es/               ← Spanish
├── docs-fr/               ← French
├── docs-hi/               ← Hindi
├── sidebars.ts            ← English sidebar
└── sidebars-lang.ts       ← Shared sidebar for all locale plugins

Required Clarifications

Before translating, always ask:

Target locale — Which language? (fr, es, zh, ar, ur, hi, de, ja)
File scope — Specific file path, chapter directory, or "continue from last"?
Overwrite behavior — Overwrite existing translations or skip completed files? (default: overwrite)

Optional Clarifications

Validation mode — Run structural validation after translation? (default: yes)
Batch size — For large jobs, how many files per batch? (default: 10)

Before Translating

Gather context to ensure successful translation:

Source	Gather
User requirements	Target locale, file scope, overwrite preference
Source files	List files to translate from `apps/learn-app/docs/`
Glossary	Read `references/glossary-<locale>.md` for terminology
Translation rules	Scan `references/translation-rules.md` for patterns
Existing translations	Check `docs-<locale>/` for completed work (if skipping)

Workflow: Direct Translation (3 Steps)

Step 1: Read Source + Glossary

Read: apps/learn-app/docs/<path>/<file>.md       (source)
Read: references/glossary-<locale>.md             (terminology)

Step 2: Translate the Entire File

Translate the complete file directly, outputting a valid MD/MDX file. Rules:

Translate:

Frontmatter title and description values
All prose paragraphs, headings, list items, blockquotes, table cells
Admonition titles (:::tip "Title" → :::tip "ترجمہ")
Image alt text
Link display text (keep URLs unchanged)
Quiz question, options, explanation fields
Quiz source field: keep "Section:" in English, translate the section name

Never translate:

Code blocks, inline code, URLs, file paths, numbers
MDX imports, JSX component tags, props (except label and title)
Frontmatter keys, slug, sidebar_position, keywords
HTML/JSX style objects — but add RTL styles for ar/ur (see below)
<PDFViewer>, <Flashcards />, <DocCardList /> tags

RTL languages (ar, ur) — MANDATORY:

Add direction: 'rtl' to every style={{...}} JSX block
Change textAlign: 'center' to textAlign: 'center' (center is fine for RTL)
Tables: keep | structure on the left, text flows RTL naturally
Never insert invisible Unicode markers (U+200E, U+200F, U+202A-U+202E)
Let the Unicode BiDi algorithm handle mixed English/RTL text naturally

Language-specific rules:

Urdu/Hindi (SOV): Reorder sentences — Subject-Object-Verb, not English SVO
Arabic (VSO): Verb-Subject-Object word order
Use formal address: آپ (Urdu), 您 (Chinese), vous (French), usted (Spanish)
Transliterate dev terms developers use in English (deploy, container, API)
Translate terms with well-known native equivalents (file→فائل, user→صارف)
Use locale punctuation: ۔ (Urdu period), ، (Arabic/Urdu comma), 。(Chinese)

Step 3: Write + Validate

Write the translated file to docs-<locale>/<path>/<file>.md.

Security Note: Before writing, check source file for secrets, API keys, or PII. Do NOT translate credentials or sensitive data.

Verify the translation by checking:

MDX Structure Validation:

All MDX tags are properly closed (<Tabs>...</Tabs>)
All imports are present and unchanged
JSX style={{...}} blocks have balanced braces
Quiz component quote structure is preserved ('", not '",)

Content Validation:

No characters from wrong scripts (Chinese in Urdu, Arabic in Hindi, etc.)
No English word order preserved where it sounds unnatural
Technical terms match glossary
Punctuation follows locale conventions
No invisible Unicode control characters
For RTL: direction: 'rtl' present in JSX style blocks

Large Files (Quiz Components)

For files with 50+ Quiz questions, translate in two passes:

First pass: Translate the prose (frontmatter through the last --- before Quiz)
Second pass: Translate the Quiz question, options, and explanation fields

Copy the Quiz component structure verbatim — only change the text strings inside the JavaScript object properties. Keep correctOption numbers unchanged.

Structural Validation (Optional)

For extra safety, run the validation script after translation:

python .claude/skills/md-translator/scripts/translate_md.py validate <original.md> <translated.md>

Python Script: scripts/translate_md.py (45KB)

Validates MDX structure and syntax
Checks for missing frontmatter, broken quotes, unbalanced braces
Requires Python 3.11+ and standard library only

Path Resolution

Item	Path
English source	`apps/learn-app/docs/<part>/<chapter>/<file>.md`
Translation output	`apps/learn-app/docs-<locale>/<part>/<chapter>/<file>.md`
Glossary	`.claude/skills/md-translator/references/glossary-<locale>.md`

Error Recovery

Problem	Action
Wrong script characters	Re-translate the file, check glossary
Broken MDX syntax	Compare with English source, fix JSX structure
RTL rendering broken	Verify `direction: 'rtl'` in JSX styles, check CSS
Quiz component errors	Keep Quiz JS object structure exact, only change strings

Reference Files

File	When to Read
`references/glossary-<locale>.md`	Before translating to that locale
`references/translation-rules.md`	For detailed inline markdown handling rules

Version Notes: Validated against Docusaurus 3.x. MDX syntax follows MDX 3.x specification.