How to Set Up Translations for the AI for Beginners Repository: A Complete Guide

To set up translations for the AI for Beginners repository, create a language folder under translations/ using an ISO-639-1 code, mirror the English directory structure, translate quiz files in assets/translations/, register the locale in index.js, and update the language selector in App.vue.

The Microsoft AI for Beginners curriculum supports multiple languages through a structured translation workflow. Whether you are localizing lessons for French, Spanish, or Japanese, the repository maintains consistency by separating language-specific content into dedicated directories and configuring the interactive quiz app to recognize new locales. This guide explains exactly how to set up translations for the AI for Beginners repository using the established contribution patterns documented in CONTRIBUTING.md and the quiz app source code.

Prerequisites and Repository Structure

Before adding a new language, familiarize yourself with the bilingual architecture of the repository. The curriculum separates static lesson content from interactive quiz data, requiring updates to both systems for full localization.

Understanding the Translation Architecture

The repository uses two primary locations for translated content:

• translations/<lang>/ – Contains Markdown lesson files (.md) and Jupyter notebooks (.ipynb) organized by section (e.g., lessons/3-NeuralNetworks/)
• assets/translations/<lang>/ – Contains JavaScript quiz files (.js) that power the interactive assessment component

All language folders must use ISO-639-1 two-letter codes (e.g., fr for French, es for Spanish, ja for Japanese) to ensure compatibility with the quiz application's locale detection system.

Step-by-Step Translation Setup

Follow these six steps to integrate a new language into both the lesson curriculum and the quiz application.

1. Create the Language Directory Structure

Begin by duplicating the existing English structure to preserve the exact file hierarchy. Use the cp -r command to copy translations/en/ to your target language code.

# Example: Creating the French translation structure

cp -r translations/en translations/fr

This command replicates the entire lessons/ subdirectory layout, ensuring that translated notebooks maintain the same relative paths as their English counterparts.

2. Translate Lesson Content

Inside your new language folder, replace all English content with translated equivalents:

• Translate all .md files in the lesson directories
• Translate all .ipynb Jupyter notebooks, preserving code cells but localizing markdown cells
• Maintain the original directory layout (lessons/<section>/<file>) to prevent broken links

Do not rename files; the quiz app and cross-references depend on consistent filenames across all language versions.

3. Localize Quiz Files

Each of the 40 lessons includes a corresponding quiz. Localize these by duplicating the English quiz hierarchy:

# Create the quiz directory for your language

cp -r assets/translations/en assets/translations/fr

Translate every *.js file inside assets/translations/<lang>/. Each file exports a quiz object containing questions, answers, and explanations. Refer to etc/quiz-app/README.md for detailed schema requirements and validation rules.

4. Register the Locale in the Quiz App

The quiz application dynamically loads translations through a central registry. Open assets/translations/index.js and import your new quiz files following the existing pattern:

// Add imports for the new language (French example)
import * as frQuiz0 from './fr/quiz0.js';
import * as frQuiz1 from './fr/quiz1.js';
import * as frQuiz2 from './fr/quiz2.js';
// ... continue for all 40 quizzes

export const quizzes = {
  en: { /* existing English imports */ },
  fr: {
    quiz0: frQuiz0,
    quiz1: frQuiz1,
    quiz2: frQuiz2,
    // ... map all quiz IDs to their imports
  },
};

This registration makes the translated quizzes available to the Vue.js application at runtime.

5. Update the Language Selector UI

Users switch languages through a dropdown in the quiz interface. Modify etc/quiz-app/src/App.vue to include your new locale:

<select v-model="currentLocale">
  <option value="en">English</option>
  <option value="fr">Français</option>
  <option value="es">Español</option>
  <!-- Add your new language option here -->
</select>

Ensure the value attribute matches exactly the folder name used in translations/ and assets/translations/ (e.g., fr, es, ja).

6. Append Locale Parameters to Lesson Links

To ensure lessons load the correct translated quiz, append the ?loc=<lang> query parameter to all lesson-to-quiz links:

<!-- Example link in a French lesson notebook -->
<a href="lesson/3-NeuralNetworks/03-Frameworks.ipynb?loc=fr">Frameworks (FR)</a>

This parameter instructs the quiz app to initialize with the specified locale, displaying the translated questions rather than defaulting to English.

Testing and Verification

Before submitting your contribution, verify the integration locally:

1. Run the Vue application from the etc/quiz-app/ directory to confirm the language selector displays your new option
2. Navigate through translated lessons to ensure all internal links resolve correctly
3. Test quiz loading by appending ?loc=<your-lang> to the URL and verifying that questions render in the target language
4. Check for missing files by comparing your translations/<lang>/ directory against translations/en/ to ensure no lessons were omitted

Once verified, commit your changes under the appropriate language folders and open a pull request following the guidelines in CONTRIBUTING.md.

Summary

Setting up translations for the AI for Beginners repository requires coordination between static content and interactive components:

• Mirror the English structure by copying translations/en/ to translations/<iso-code>/
• Translate both lessons and quizzes, placing quiz JavaScript files in assets/translations/<iso-code>/
• Register imports in assets/translations/index.js to make quizzes available to the application
• Update the UI in etc/quiz-app/src/App.vue to add the language selector option
• Use locale query parameters (?loc=<lang>) in lesson links to direct users to translated quizzes

Frequently Asked Questions

What ISO code format should I use for new translations?

Use ISO-639-1 two-letter language codes (e.g., fr for French, de for German, zh for Chinese). The quiz application and folder structure rely on these standardized codes for routing and file resolution. Avoid using regional variants (e.g., fr-CA) unless specifically supported by the application architecture.

Do I need to translate all 40 quizzes to submit a pull request?

While the curriculum contains 40 quizzes corresponding to each lesson, you should aim to translate all quiz files in assets/translations/<lang>/ before submitting. Partial translations may be accepted for review, but complete localization ensures consistency across the learning experience. The index.js registry must import every quiz file for your language to prevent runtime errors.

How does the quiz app know which translation to display?

The quiz application determines the active locale through two mechanisms: the language selector dropdown in App.vue (which sets a reactive currentLocale variable), and the ?loc=<lang> query parameter appended to URLs. When a user navigates from a translated lesson to a quiz, the query parameter overrides the default and loads the corresponding JavaScript quiz object from the registry in assets/translations/index.js.

Where can I find the official contribution guidelines?

The official contribution workflow is documented in CONTRIBUTING.md at the repository root. This file specifies that all translations must reside in the translations/ directory using existing folder names as templates, and directs contributors to the quiz app README (etc/quiz-app/README.md) for specific instructions on localizing interactive assessments. Always reference these documents before beginning translation work.

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