# How to Add New Quiz Translations Using the Co-op-Translator GitHub Action Workflow

> Easily add new quiz translations using the Co-op-Translator GitHub Action. Create a JSON file, register it in index.js, and let the action sync content via Pull Request.

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

---

**You add new quiz translations by creating a language-specific JSON file in `etc/quiz-app/src/assets/translations`, registering it in [`index.js`](https://github.com/microsoft/AI-For-Beginners/blob/main/index.js), and letting the Co-op-Translator GitHub Action automatically sync content when you open a Pull Request.**

The **microsoft/AI-For-Beginners** repository includes a Vue 2-based quiz application located in `etc/quiz-app`. All quiz strings are stored as JSON files under `etc/quiz-app/src/assets/translations`. When contributors add support for new languages, the repository's GitHub Action runs the **Co-op-Translator** workflow to maintain synchronization between source English files and translated assets.

## Understanding the Quiz Translation Architecture

The quiz application relies on a centralized translation system where each language maintains its own JSON dictionary. The source of truth resides in [`etc/quiz-app/src/assets/translations/en.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/src/assets/translations/en.json), containing the master English strings and question structures. According to the quiz app documentation in [`etc/quiz-app/README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/README.md), new translations require creating corresponding folder structures and registering them in the translation index.

The Co-op-Translator Action—defined in [`.github/workflows/translation.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/.github/workflows/translation.yml)—monitors changes to the English source files and automatically invokes the Azure Co-op-Translator service to generate or update translation assets when pull requests are opened.

## Step-by-Step Guide to Adding a New Language

### Create the Language Directory Structure

Inside `etc/quiz-app/src/assets/translations`, create a new folder named with the **ISO language code** you want to support. For example, create `es` for Spanish or `fr` for French.

```bash
cd etc/quiz-app/src/assets/translations
mkdir fr

```

As documented in the quiz app README, new translations are added by establishing the appropriate folder structure within the `assets/translations` directory.

### Copy and Translate the English Source Content

Copy the contents of the original English translation ([`etc/quiz-app/src/assets/translations/en.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/src/assets/translations/en.json)) into a new file named `<lang>.json` in your created folder. Preserve the exact key hierarchy; only the string values require translation.

**Critical constraints when translating:**

- **Do not translate boolean literals** (`true`, `false`)
- **Preserve all placeholder tokens** exactly as they appear in the source
- Maintain the JSON structure and nesting levels

```bash
cp en.json fr/fr.json

# Edit fr.json to translate string values while keeping structural elements intact

```

The README confirms that the original quizzes reside in `assets/translations/en`, serving as the source for all derivative translations.

### Register the Translation in the Index Module

Open [`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) and add an import statement for your new JSON file. Then expose it in the exported `translations` object to make the language available in the Vue application.

```javascript
// etc/quiz-app/src/assets/translations/index.js
import en from './en.json';
import fr from './fr.json';   // New import

export const translations = {
    en,
    fr,                       // New language registration
};

```

The README explicitly instructs contributors to edit [`index.js`](https://github.com/microsoft/AI-For-Beginners/blob/main/index.js) to import new translation files, ensuring the quiz application can access the localized content.

### Submit Changes and Trigger the Workflow

Commit your new folder, translated JSON file, and updated [`index.js`](https://github.com/microsoft/AI-For-Beginners/blob/main/index.js) to a feature branch, then open a Pull Request. The GitHub Action defined in [`.github/workflows/translation.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/.github/workflows/translation.yml) automatically executes when the PR detects changes to:

- Files in `lessons/**`
- [`etc/quiz-app/src/assets/translations/en.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/src/assets/translations/en.json)

The workflow runs the Azure Co-op-Translator Action (`azure/co-op-translator`), which reads the source English files, sends them to the translation service, and updates or creates the corresponding translation files in your branch.

```yaml
name: Translate Content

on:
  pull_request:
    paths:
      - 'lessons/**'
      - 'etc/quiz-app/src/assets/translations/en.json'

jobs:
  co-op-translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Co-op-Translator
        uses: azure/co-op-translator@v1
        with:
          source-dir: 'etc/quiz-app/src/assets/translations/en'
          target-dir: 'etc/quiz-app/src/assets/translations'
          languages: 'fr,es,de'

```

Once the workflow completes and CI checks pass, reviewers can approve the PR. After merging, the translated quiz becomes available in the newly added language.

## Summary

- **Location matters**: Store translation files in `etc/quiz-app/src/assets/translations/<lang>.json` using ISO language codes.
- **Source integrity**: Always copy from [`en.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/en.json) and preserve keys, booleans, and placeholders.
- **Registration required**: Update [`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) to import and export the new language module.
- **Automation enabled**: The Co-op-Translator GitHub Action in [`.github/workflows/translation.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/.github/workflows/translation.yml) processes changes automatically on Pull Requests.
- **Service dependency**: The workflow utilizes the Azure Co-op-Translator service documented at `github.com/Azure/co-op-translator`.

## Frequently Asked Questions

### What file format does the quiz app use for translations?

The application uses **JSON files** with a nested key-value structure. Each language has its own JSON file (e.g., [`es.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/es.json), [`fr.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/fr.json)) stored in `etc/quiz-app/src/assets/translations/`. The English source file [`en.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/en.json) defines the schema that all other language files must follow exactly.

### Can I manually translate without using the Co-op-Translator Action?

Yes. You can manually create the JSON translation file and register it in [`index.js`](https://github.com/microsoft/AI-For-Beginners/blob/main/index.js) without waiting for the automated workflow. However, the Co-op-Translator Action will still run on your Pull Request to ensure consistency and may update your translations if the source English content has changed since you created your branch.

### Which files trigger the translation workflow?

According to the workflow configuration in [`.github/workflows/translation.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/.github/workflows/translation.yml), the Co-op-Translator Action triggers on pull requests that modify files in `lessons/**` or specifically change [`etc/quiz-app/src/assets/translations/en.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/src/assets/translations/en.json). Changes to existing non-English translation files alone do not trigger the automated translation process.

### How do I handle placeholder tokens and boolean values in translations?

**Never translate boolean literals** (`true`, `false`) or placeholder tokens found in the English source strings. Copy these elements exactly as they appear in [`en.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/en.json). The quiz application depends on these values remaining in their original format for proper functionality, while only the human-readable string content should be localized.