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

You add new quiz translations by creating a language-specific JSON file in etc/quiz-app/src/assets/translations, registering it in 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, containing the master English strings and question structures. According to the quiz app documentation in 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—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.

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) 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

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 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.

// 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 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 to a feature branch, then open a Pull Request. The GitHub Action defined in .github/workflows/translation.yml automatically executes when the PR detects changes to:

• Files in lessons/**
• 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.

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 and preserve keys, booleans, and placeholders.
• Registration required: Update 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 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, fr.json) stored in etc/quiz-app/src/assets/translations/. The English source file 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 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, 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. 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. 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.

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