How to Contribute Multi-Language Support and Translations to Microsoft AI-For-Beginners

AI-For-Beginners uses a file-based translation pipeline that lets contributors add new languages by placing translated markdown in translations/<lang>/ and registering quiz data in the Vue.js app—no core code changes required.

The microsoft/AI-For-Beginners repository is structured to make localization straightforward. Whether you're translating lesson READMEs or the quiz-app UI, the process follows consistent conventions across two main components: lesson documentation and the interactive quiz interface.

Lesson and Documentation Translations

The repository stores all lesson content as markdown files. Translated versions live alongside the originals using a predictable naming pattern.

Folder Structure and Naming Convention

Create translations under translations/<lang>/ using ISO-639-1 two-letter codes (e.g., es for Spanish, fr for French). According to [etc/TRANSLATIONS.md](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/TRANSLATIONS.md), lines 11-19 specify this format:

translations/
├── es/
│   ├── README.es.md
│   ├── assignment.es.md
│   └── ...
├── fr/
│   ├── README.fr.md
│   └── ...

Each file follows the pattern README.<lang>.md and assignment.<lang>.md. The build system automatically serves these when the folder exists—no configuration changes needed.

Translation Best Practices

• Translate prose only—preserve all code blocks, variable names, and outputs exactly as they appear in the original
• Maintain relative links—ensure internal references still resolve correctly
• Keep frontmatter intact—any YAML headers should remain unchanged except for translated titles

Quiz-App UI Translations

The quiz application lives in etc/quiz-app/ and uses Vue-I18n for runtime localization. Adding a language requires three file edits.

Step 1: Create the Translation JSON

Add a new file at etc/quiz-app/src/assets/translations/<lang>.json. Use en.json as your template. Translate question text and answer strings, but do not translate boolean literals—the app expects true and false in English.

{
  "quiz1": {
    "question": "Votre question traduite ici",
    "answers": [
      "Option A",
      "Option B"
    ],
    "correctAnswer": 0
  }
}

Step 2: Register in the Translation Index

Import and export your new language in [etc/quiz-app/src/assets/translations/index.js](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/src/assets/translations/index.js), lines 1-8:

import englishQuizzes from './en';
import spanishQuizzes from './es';
import frenchQuizzes from './fr';   // <-- add import

const messages = {
  en: englishQuizzes,
  es: spanishQuizzes,
  fr: frenchQuizzes,                // <-- add to map
};

export default messages;

Step 3: Add to the Language Selector

Update the dropdown in [etc/quiz-app/src/App.vue](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/src/App.vue), lines 12-16:

<select v-model="locale">
  <option>en</option>
  <option>es</option>
  <option>fr</option>   <!-- new option -->
</select>

Step 4: Update Quiz Links in Translated READMEs

Append the loc query parameter to direct users to localized quizzes:

https://red-field-0a6ddfd03.1.azurestaticapps.net/quiz/1?loc=fr

This tells the app which JSON payload to load on initialization.

Pull Request Workflow

Follow these steps to submit your contribution:

1. Fork and branch: Create feat/translation-<lang> from main
2. Add files: Include all translated markdown and quiz JSON
3. Validate: Run npm run lint in etc/quiz-app/ to check Vue code
4. Commit clearly: Example: Add French translations for lessons 1-3 and quiz UI
5. Open PR: The CLA-bot will prompt for Microsoft Contributor License Agreement signature per [CONTRIBUTING.md](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md)

Common Pitfalls to Avoid

Issue	Prevention
Translated boolean values	Keep true/false in English in quiz JSON
Inconsistent language codes	Use same code in folder name, file suffix, and dropdown
Broken code samples	Copy code blocks verbatim without translation
Missing loc parameter	Append ?loc=<lang> to quiz URLs in translated READMEs

Local Testing

Verify your work before submitting:

cd etc/quiz-app/
npm install
npm run serve

Select your language from the dropdown and confirm all quizzes render correctly.

Summary

• Lesson translations go in translations/<lang>/ as README.<lang>.md and assignment.<lang>.md
• Quiz translations require a JSON file, registration in index.js, and a dropdown option in App.vue
• Never translate code or boolean values—only natural language content
• Always use ISO-639-1 codes consistently across all files
• Test locally with npm run serve in the quiz-app directory

Frequently Asked Questions

What file naming convention should I follow for translations?

Use README.<lang>.md and assignment.<lang>.md where <lang> is an ISO-639-1 two-letter code. Place these in translations/<lang>/ as specified in [etc/TRANSLATIONS.md](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/TRANSLATIONS.md). The CI system automatically detects and serves files matching this pattern.

Do I need to modify any core application code to add a language?

No. For lessons, simply create the properly named files in translations/<lang>/. For the quiz app, you only modify three files: your new <lang>.json, index.js to import it, and App.vue to add the dropdown option. No changes to quiz logic or lesson rendering are required.

Why must I keep true and false in English in the quiz JSON?

The Vue.js application evaluates answer correctness by comparing user selections against the correctAnswer index and boolean values in the JSON. Translating these literals breaks the evaluation logic. Only translate question text and answer strings, not boolean data types.

How do I link to a translated quiz from my README?

Append ?loc=<lang> to the quiz URL. For example: https://.../quiz/1?loc=es loads the Spanish quiz. The loc parameter maps directly to the JSON filename (without extension) in etc/quiz-app/src/assets/translations/.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}