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.