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

> Learn to contribute multi-language support and translations to the AI-For-Beginners project. Add new languages easily via markdown files and quiz data registration. No code changes needed.

- Repository: [Microsoft/AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners)
- Tags: how-to-guide
- Published: 2026-08-03

---

**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](https://github.com/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)](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`](https://github.com/microsoft/AI-For-Beginners/blob/main/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.

```json
{
  "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)](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/src/assets/translations/index.js), lines 1-8:

```javascript
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)](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/src/App.vue), lines 12-16:

```html
<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)](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:

```bash
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`](https://github.com/microsoft/AI-For-Beginners/blob/main/index.js), and a dropdown option in [`App.vue`](https://github.com/microsoft/AI-For-Beginners/blob/main/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)](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`](https://github.com/microsoft/AI-For-Beginners/blob/main/index.js) to import it, and [`App.vue`](https://github.com/microsoft/AI-For-Beginners/blob/main/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/`.