# How to Set Up Translations for the AI for Beginners Repository: A Complete Guide > Learn how to set up translations for the AI for Beginners repository. Follow this guide to add new languages and expand the project's reach effortlessly. - Repository: [Microsoft/AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners) - Tags: how-to-guide - Published: 2026-08-22 --- **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`](https://github.com/microsoft/AI-For-Beginners/blob/main/index.js), and update the language selector in [`App.vue`](https://github.com/microsoft/AI-For-Beginners/blob/main/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`](https://github.com/microsoft/AI-For-Beginners/blob/main/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//`** – Contains Markdown lesson files (`.md`) and Jupyter notebooks (`.ipynb`) organized by section (e.g., `lessons/3-NeuralNetworks/`) - **`assets/translations//`** – 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. ```bash # 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/
/`) 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: ```bash # Create the quiz directory for your language cp -r assets/translations/en assets/translations/fr ``` Translate every `*.js` file inside `assets/translations//`. Each file exports a quiz object containing questions, answers, and explanations. Refer to [`etc/quiz-app/README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/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`](https://github.com/microsoft/AI-For-Beginners/blob/main/assets/translations/index.js) and import your new quiz files following the existing pattern: ```javascript // 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`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/src/App.vue) to include your new locale: ```html ``` 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=` query parameter to all lesson-to-quiz links: ```html Frameworks (FR) ``` 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=` to the URL and verifying that questions render in the target language 4. **Check for missing files** by comparing your `translations//` 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`](https://github.com/microsoft/AI-For-Beginners/blob/main/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//` - **Translate both lessons and quizzes**, placing quiz JavaScript files in `assets/translations//` - **Register imports** in [`assets/translations/index.js`](https://github.com/microsoft/AI-For-Beginners/blob/main/assets/translations/index.js) to make quizzes available to the application - **Update the UI** in [`etc/quiz-app/src/App.vue`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/src/App.vue) to add the language selector option - **Use locale query parameters** (`?loc=`) 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//` before submitting. Partial translations may be accepted for review, but complete localization ensures consistency across the learning experience. The [`index.js`](https://github.com/microsoft/AI-For-Beginners/blob/main/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`](https://github.com/microsoft/AI-For-Beginners/blob/main/App.vue) (which sets a reactive `currentLocale` variable), and the **`?loc=` 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`](https://github.com/microsoft/AI-For-Beginners/blob/main/assets/translations/index.js). ### Where can I find the official contribution guidelines? The official contribution workflow is documented in [`CONTRIBUTING.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/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`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/README.md)) for specific instructions on localizing interactive assessments. Always reference these documents before beginning translation work.