# How to Add a New Language to the AI-for-Beginners Project: A Complete Workflow Guide > Learn the workflow to add new languages to the AI-for-Beginners project. This guide covers folder structures, JSON translations, and app registration for seamless multilingual support. - Repository: [Microsoft/AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners) - Tags: how-to-guide - Published: 2026-08-25 --- **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//` 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..md` | [`README.pt.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/README.pt.md) | | Assignment | `assignment..md` | [`assignment.pt.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/assignment.pt.md) | The official translation guidelines in [[`etc/TRANSLATIONS.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/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//lesson-1.json` following this exact schema: ```json [ { "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`](https://github.com/microsoft/AI-For-Beginners/blob/main/lesson-1.json) correspond directly to course module numbers Reference implementations: [[`en/lesson-1.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/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/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)](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 ```javascript // 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)](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/src/App.vue). The component binds a ` ``` The `locale` value is automatically synchronized to the URL as `?loc=`, 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 ```markdown [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](https://github.com/microsoft/AI-For-Beginners/tree/main/translations/pt/lessons/1-Intro). ## 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](https://github.com/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](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md) guidelines The Microsoft CLA bot automatically verifies licensing compliance on all submissions. ## Key Files Reference | File Path | Purpose | |-----------|---------| | [`etc/TRANSLATIONS.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/TRANSLATIONS.md) | Official translation guidelines and conventions | | `translations//…/README..md` | Translated lesson content | | `translations//…/assignment..md` | Translated homework assignments | | `etc/quiz-app/src/assets/translations/.json` | Language-specific quiz questions | | [`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) | Language registry and export mapping | | [`etc/quiz-app/src/App.vue`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/src/App.vue) | Locale selector UI and routing logic | ## Summary - **Lesson content** belongs in `translations//` with `README..md` and `assignment..md` files - **Quiz data** requires JSON files in `etc/quiz-app/src/assets/translations//` that preserve structure and boolean literals - **App registration** demands updates to [`index.js`](https://github.com/microsoft/AI-For-Beginners/blob/main/index.js) (import + `messages` entry) and [`App.vue`](https://github.com/microsoft/AI-For-Beginners/blob/main/App.vue) (dropdown option) - **Cross-linking** depends on `?loc=` 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 `