Multi-Language Translation Workflow in the Microsoft AI-For-Beginners Curriculum

The Microsoft AI-For-Beginners repository implements a dual-track translation system where lesson content lives in translations/<language-code>/ directories and quiz interface strings are managed as JSON files in etc/quiz-app/src/assets/translations/, requiring manual registration in index.js to activate new languages.

The microsoft/AI-For-Beginners project supports community-driven localization through a structured multi-language translation workflow. This architecture separates educational content from application interfaces, allowing contributors to translate markdown lessons and Vue.js quiz components using distinct but complementary processes defined in etc/TRANSLATIONS.md.

Lesson Content Translation Structure

Translated lessons follow a strict directory mirroring convention to maintain organizational parity with the English source.

Directory Layout and Conventions

All lesson translations reside under the top-level translations/<language-code>/ folder. Each language directory must replicate the exact folder hierarchy found in the repository root. For example, Spanish translations for lessons appear under translations/es/lessons/ while maintaining the same subdirectory structure as the original English content.

According to the source guide at etc/TRANSLATIONS.md, contributors must adhere to specific formatting rules:

• Do not translate the literal values true and false — these must remain in English regardless of the target language
• Preserve the original markdown file names and directory paths exactly
• Place all translated content within the appropriate translations/<lang>/ subtree

Quiz Application Localization

The Vue.js quiz application handles UI text through modular JSON translation files rather than inline content.

JSON File Structure and Location

Quiz translations are stored in etc/quiz-app/src/assets/translations/ with each language represented by a separate file following the naming convention <lang>.json. For instance, French translations reside in etc/quiz-app/src/assets/translations/fr.json, while English source strings live in en.json within the same directory.

Each JSON file must contain the exact same key structure as the English source to ensure the application can resolve all UI strings correctly.

Registering New Languages in the Index Module

After creating a new translation file, you must register it in the central etc/quiz-app/src/assets/translations/index.js module. This step imports the language data and exports it for the Vue.js application to consume.

To add Italian (it) support, modify the index file as follows:

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

export const translations = {
  en,
  fr,
  it,  // Register the new language
  // additional languages...
};

The application dynamically loads these translations based on user selection, so proper registration in the index.js exports is critical for the language to appear in the UI.

Automated Translation Pipeline

The repository leverages GitHub Actions to streamline the translation process through the Co-op Translator tool. This automation generates machine-translated drafts for supported languages, which contributors then review and refine before submitting pull requests. While the automated workflow handles initial content generation, human review remains mandatory for quality assurance before merging.

Summary

• Lesson translations live in translations/<language-code>/ and must mirror the original directory structure exactly
• Quiz translations are JSON files located in etc/quiz-app/src/assets/translations/<lang>.json following the <lang>.json naming convention
• The central index at etc/quiz-app/src/assets/translations/index.js must be updated with new imports and exports for each added language
• Boolean literals (true and false) must never be translated, per the guidelines in etc/TRANSLATIONS.md
• Co-op Translator provides automated draft generation via GitHub Actions, but requires manual review and correction

Frequently Asked Questions

Where should I place translated lesson files?

Place all translated lesson content under translations/<language-code>/ using the exact same folder hierarchy and file names as the English source. For example, if the English lesson is at lessons/1-Intro/README.md, the Spanish version belongs at translations/es/lessons/1-Intro/README.md.

How do I add a new language to the quiz application?

Create a new JSON file named <lang>.json in etc/quiz-app/src/assets/translations/ containing all translation keys from en.json, then import and export that module in etc/quiz-app/src/assets/translations/index.js to register it with the Vue.js application.

Should I translate boolean values like true and false?

No. According to the translation guidelines in etc/TRANSLATIONS.md, you must not translate the literals true and false. These values remain in English across all language files to maintain consistency with the application's logic processing.

What automation supports the translation workflow?

The repository uses a GitHub Action that runs the Co-op Translator to generate machine-translated drafts automatically. Contributors review these drafts for accuracy and cultural appropriateness before submitting them as pull requests for final integration.

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