How to Add a New Language to the AI-for-Beginners Project: A Complete Workflow Guide

The AI-for-Beginners translation workflow requires creating parallel folder structures for lesson content, adding JSON quiz translations, and registering the language in the Vue quiz app's locale system.

The Microsoft AI-for-Beginners repository is architected as a multilingual learning platform where every language exists in two synchronized layers: static Markdown curriculum and interactive quiz data. Contributors who want to add a new language must update three distinct components—the lesson translations, the quiz JSON files, and the UI locale selector—to ensure a seamless learner experience.

Core Translation Architecture

The repository separates language content into lesson materials and quiz application data. This design allows the Vue-based quiz app (etc/quiz-app/) to dynamically load language-specific content while maintaining a unified codebase.

Each language follows ISO 639-1 two-letter codes (e.g., pt for Portuguese, es for Spanish) for consistent identification across all systems.

Step 1: Create the Translation Folder Structure

New languages begin in the translations/<lang>/ directory, which mirrors the original English folder hierarchy exactly.

Directory Layout

translations/
├── pt/                          # Portuguese example

│   └── lessons/
│       ├── 1-Intro/
│       │   ├── README.pt.md
│       │   └── assignment.pt.md
│       ├── 2-Symbolic/
│       │   ├── README.pt.md
│       │   └── assignment.pt.md
│       └── …

File Naming Requirements

File Type	Pattern	Example
Lesson README	README.<lang>.md	README.pt.md
Assignment	assignment.<lang>.md	assignment.pt.md

The official translation guidelines in [etc/TRANSLATIONS.md](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/TRANSLATIONS.md) specify that folder structure must remain identical to the English source to preserve relative links and asset paths.

Step 2: Add Quiz Translations

The quiz application loads questions from JSON files in etc/quiz-app/src/assets/translations/. Each language requires its own subdirectory with lesson-specific JSON files.

Quiz JSON Structure

Create etc/quiz-app/src/assets/translations/<lang>/lesson-1.json following this exact schema:

[
  {
    "title": "Introdução ao AI",
    "quiz": [
      {
        "questionText": "Qual é o objetivo da aprendizagem profunda?",
        "answerOptions": [
          { "answerText": "Reconhecer padrões", "isCorrect": true },
          { "answerText": "Criar gráficos", "isCorrect": false }
        ]
      }
    ]
  }
]

Critical Translation Rules

• Preserve boolean values: Never translate true/false in isCorrect fields—these must remain English literals for JavaScript evaluation
• Maintain JSON structure: All keys (title, quiz, questionText, answerOptions, answerText, isCorrect) must remain unchanged
• Match lesson numbering: File names like lesson-1.json correspond directly to course module numbers

Reference implementations: [en/lesson-1.json](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/src/assets/translations/en/lesson-1.json) and [es/lesson-1.json](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/src/assets/translations/es/lesson-1.json).

Step 3: Register the Language in the Quiz App

The quiz app centralizes language registration 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). This module exports a messages object that maps ISO codes to imported JSON data.

Required Code Changes

// etc/quiz-app/src/assets/translations/index.js

import englishQuizzes from './en';
import spanishQuizzes from './es';
import portugueseQuizzes from './pt';   // ← new import

const messages = {
  en: englishQuizzes,
  es: spanishQuizzes,
  pt: portugueseQuizzes,                // ← new entry
};

export default messages;

The messages object is consumed by the Vue I18n plugin, enabling runtime language switching based on URL parameters.

Step 4: Add the Language to the Locale Selector

The UI dropdown that controls language selection lives in [etc/quiz-app/src/App.vue](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/src/App.vue). The component binds a <select> element to the locale reactive property, which drives both the translation loading and URL query updates.

Vue Template Modification

<!-- etc/quiz-app/src/App.vue -->
<select v-model="locale">
  <option>en</option>
  <option>es</option>
  <option>pt</option>   <!-- new option -->
</select>

The locale value is automatically synchronized to the URL as ?loc=<lang>, enabling deep-linking to specific language versions.

Step 5: Update Quiz Links in Translated READMEs

Every quiz hyperlink in translated lesson files must include the loc query parameter. Without this parameter, the quiz app defaults to English regardless of which translated README the user came from.

Correct Link Format

<!-- In translations/pt/lessons/1-Intro/README.pt.md -->
[Tome o Quiz 1](https://red-field-0a6ddfd03.1.azurestaticapps.net/quiz/1?loc=pt)

The ?loc=pt suffix ensures the quiz app initializes with the Portuguese translation loaded. Omitting this parameter causes a language mismatch that breaks the integrated learning experience.

See working examples in the Portuguese lesson directory.

Step 6: Submit Your Contribution

Once all files are prepared, contributors should follow the standard open-source workflow:

1. Fork the microsoft/AI-For-Beginners repository
2. Create a feature branch for the new language
3. Commit all translation files, index.js updates, and App.vue modifications
4. Open a Pull Request referencing the CONTRIBUTING.md guidelines

The Microsoft CLA bot automatically verifies licensing compliance on all submissions.

Key Files Reference

File Path	Purpose
etc/TRANSLATIONS.md	Official translation guidelines and conventions
translations/<lang>/…/README.<lang>.md	Translated lesson content
translations/<lang>/…/assignment.<lang>.md	Translated homework assignments
etc/quiz-app/src/assets/translations/<lang>.json	Language-specific quiz questions
etc/quiz-app/src/assets/translations/index.js	Language registry and export mapping
etc/quiz-app/src/App.vue	Locale selector UI and routing logic

Summary

• Lesson content belongs in translations/<lang>/ with README.<lang>.md and assignment.<lang>.md files
• Quiz data requires JSON files in etc/quiz-app/src/assets/translations/<lang>/ that preserve structure and boolean literals
• App registration demands updates to index.js (import + messages entry) and App.vue (dropdown option)
• Cross-linking depends on ?loc=<lang> query parameters in all quiz hyperlinks
• ISO 639-1 codes (two-letter lowercase) are required for all language identifiers throughout the codebase

Frequently Asked Questions

What ISO standard does the AI-for-Beginners project use for language codes?

The repository requires ISO 639-1 two-letter codes in lowercase (e.g., pt for Portuguese, zh for Chinese). This convention appears in folder names, JSON file imports, the messages object keys, and URL query parameters. Using three-letter codes or uppercase variants will break the quiz app's language detection.

Do I need to translate the quiz JSON keys like questionText and isCorrect?

No. Only the values associated with title, questionText, and answerText should be translated. The JSON keys must remain in English, and boolean values (true/false) must never be translated—these are evaluated by JavaScript. Translating structural keys or boolean literals causes runtime parsing errors.

How does the quiz app know which language to display?

The Vue application reads the loc query parameter from the URL (e.g., ?loc=es). This value is bound to the <select> dropdown in App.vue and passed to the translation loader in index.js. If no loc parameter is present, the app typically defaults to en. The query parameter is also updated when users manually change the dropdown selection.

Can I submit a partial translation for review?

While possible, complete lesson and quiz coverage for at least one full module is strongly preferred. Partial translations create maintenance overhead and learner confusion. The TRANSLATIONS.md guide recommends finishing all files within a lesson folder (both README.<lang>.md and assignment.<lang>.md) before submitting, along with the corresponding quiz JSON and registration updates.

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