Language Configuration

Each target language can have specific translation rules that are automatically included in Claude’s prompts. These rules handle language-specific typography, punctuation conventions, and stylistic guidelines.

Supported languages¶

Current rules¶

Chinese (Simplified) — zh-cn¶

• Use proper full-width Chinese punctuation marks (，：。！？) not ASCII punctuation (,.!?) in prose text

Farsi — fa¶

• Use proper Persian punctuation marks (، ؛ ؟) without any RTL directionality markup

• Keep technical terms and code examples in English/Latin script

• Use formal/academic Persian style appropriate for educational content

French — fr¶

• Use French guillemets « » (with a non-breaking space inside each) for quotations rather than straight or curly double quotes

• Insert a non-breaking space before the high punctuation marks ; : ! ? as required by French typography

• Use the impersonal academic register of French course materials rather than calquing the English direct address (“On pose $T = 200$”, “L’objectif de cet exercice est de…”)

• Do not calque English discourse formulas word-for-word — render the function, not the words (“We can and will examine…” → “Nous verrons plus loin…”)

• In display math and exercise hints, translate ordinary English words used as descriptive symbols ($aire = \pi * rayon^2$); never rename identifiers that executable code defines or uses. Where code comments are being localized (the code-comments localization rule), the same descriptive-symbol translation applies there

• Prefer natural French sentence structure over mirroring the English — fidelity is owed to meaning and technical content, not to English syntax

The register and anti-calque rules encode the first native-editor review of machine output (Emile, lecture-python-programming.fr PRs #24/#25, August 2026); each generalises a correction made at least twice across those lectures.

How rules are applied¶

Language rules are appended to every translation prompt as numbered rules after the standard instructions. For example, when translating to zh-cn, Claude’s prompt includes:

CRITICAL RULES:
1. Preserve all MyST Markdown formatting...
2. DO NOT translate code, math, URLs...
...
9. Use proper full-width Chinese punctuation marks (，：。！？) not ASCII punctuation

Rules apply to all translation modes: UPDATE (incremental sync), NEW (full file), and RESYNC (drift recovery).

Supported languages¶

The GitHub Action validates target-language against its configured language list — currently en, zh-cn, fa, fr, and ml — and fails immediately, before any work happens, on anything else. Adding a language means adding a LANGUAGE_CONFIGS entry in src/language-config.ts (a glossary alone does not enable a language); the drift test in language-config.test.ts keeps this page’s list in sync with the code.

The CLI (translate init, forward, backward) never validates the language code: any code works there, with no language-specific rules applied for unconfigured codes.

Malayalam — ml¶

Malayalam is keep-English-dominant, unlike every other configured language. Technical and domain terms stay in their original English/Latin form rather than being translated or transliterated; only the connective prose is Malayalam, with case-suffixes and sandhi attached to the English roots (economy-യിലെ, bond-ന്റെ, supply-യും). Section headings stay in English.

The reason is register, not convenience: Kerala has no Malayalam-medium STEM university or active classroom term bank, and learners meet these terms in English from first exposure — so translating them reads archaic rather than accessible. This is native-speaker guidance recorded in issue #70 and implemented in #71, and it inverts the full-translation pattern zh-cn and fa follow. The glossary’s role flips accordingly: it is a small everyday-word consistency list (52 terms) rather than a technical dictionary.

Adding a new language¶

To add rules for a new language, edit src/language-config.ts:

export const LANGUAGE_CONFIGS: Record<string, LanguageConfig> = {
  'zh-cn': { /* ... */ },
  'fa': { /* ... */ },

  // Add new language:
  'ja': {
    code: 'ja',
    name: 'Japanese',
    additionalRules: [
      'Use proper Japanese punctuation marks (、。「」)',
    ],
  },
};

Each language configuration has:

• code — Language code (matches the target-language input)

• name — Human-readable language name

• additionalRules — Array of rules appended to translation prompts

After adding a language configuration, you should also:

1. Create a glossary file at glossary/{code}.json (see Glossary)

2. Add test cases for the new language

3. Rebuild the action (npm run build)