# How the co-op-translator GitHub Action Automates Translations for 40+ Languages

> Learn how the co-op-translator GitHub Action automates translations for 40+ languages. Effortlessly sync your multilingual content with every push to main.

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

---

**The co-op-translator GitHub Action automates multilingual content synchronization by running a matrix workflow that processes English source files through Azure's co-op-translator service and commits translated outputs to language-specific directories on every push to main.**

The microsoft/AI-For-Beginners repository leverages the **co-op-translator GitHub Action** to maintain synchronized educational content across more than 40 languages without manual intervention. This automation ensures that every lesson, notebook, and quiz update in the English source immediately propagates to global learners through a fully configured CI pipeline defined in the repository's workflow files.

## Workflow Architecture and Trigger Mechanism

The automation centers on [`.github/workflows/translate.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/.github/workflows/translate.yml), which defines the continuous integration pipeline for translation generation according to the microsoft/AI-For-Beginners source code.

### Event-Based Execution

The workflow triggers on two distinct events to maintain content freshness. The process initiates on every `push` to the `main` branch and upon updates to `pull_request` targets. This ensures that merged contributions and proposed changes both undergo translation processing immediately, preventing language versions from drifting out of sync with the English source.

### Matrix Strategy for 40+ Languages

The workflow employs a job matrix that enumerates all supported language codes, creating parallel execution jobs for each target language. The matrix includes codes such as `ar`, `zh-CN`, `zh-TW`, `fr`, `de`, `es`, `hi`, `it`, `ja`, `ko`, `pt-BR`, `ru`, `sv`, `tr`, and `vi`, covering the full spectrum of 40+ supported languages. Each matrix entry spawns an isolated job that processes the entire source directory for one specific language.

## The Translation Pipeline Execution

Each matrix job executes the official `azure/co-op-translator` action with specific directory configurations that map source content to localized outputs.

### Source and Target Configuration

The action receives three critical parameters: `source_dir` pointing to the repository root containing English Markdown files, `target_lang` populated from the matrix variable, and `output_dir` directing translated content to `./translations/${{ matrix.language }}/`.

```yaml
- name: Run co‑op‑translator
  uses: azure/co-op-translator@v1
  with:
    source_dir: ./
    target_lang: ${{ matrix.language }}
    output_dir: ./translations/${{ matrix.language }}

```

### Output Directory Structure

Translated files populate dedicated language folders under the `translations/` directory. For example, Traditional Chinese translations reside in `translations/zh-TW/`, while Spanish content appears in `translations/es/`. This structure maintains clean separation between language versions while preserving the original file hierarchy from the source directory.

## Automated Commit and Verification Workflow

After translation generation, the workflow handles version control operations and quality assurance to ensure repository integrity.

### Git Operations with Bot Identity

The workflow configures Git authentication using the standard GitHub Actions bot credentials. It stages all generated translation files, creates commits with descriptive messages identifying the target language, and pushes changes back to the repository.

```yaml
- name: Commit translations
  run: |
    git config user.name "github-actions[bot]"
    git config user.email "github-actions[bot]@users.noreply.github.com"
    git add .
    git commit -m "🤖 Automated translations for ${{ matrix.language }} via co‑op‑translator"
    git push

```

### Build Verification

Following translation commits, the pipeline executes `npm run lint` within the `etc/quiz-app/` directory to validate that translated Markdown content does not introduce syntax errors or break the Vue.js quiz application build process. This verification step ensures that localized content remains functional within the interactive learning components.

## Configuration and Metadata Management

The co-op-translator action generates persistent metadata files that track translation state and configuration across workflow runs.

### Per-Language Configuration Files

Each language directory contains a [`.co-op-translator.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/.co-op-translator.json) file that stores language-specific metadata. For instance, [`translations/zh-TW/.co-op-translator.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/translations/zh-TW/.co-op-translator.json) maintains configuration data for the Traditional Chinese translation set, enabling the action to track versioning and translation mappings across subsequent runs. These files serve as markers for the action to determine which files require updates versus full regeneration.

## Summary

- The **co-op-translator GitHub Action** processes content through a matrix workflow supporting 40+ languages including Arabic, Chinese, French, German, Spanish, and Hindi.
- The workflow file [`.github/workflows/translate.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/.github/workflows/translate.yml) triggers on pushes to `main` and pull request updates, ensuring continuous synchronization.
- Each language job uses the `azure/co-op-translator@v1` action with configurable source and output directories.
- Translated content commits automatically via the GitHub Actions bot with standardized messages.
- The pipeline includes lint verification for the `etc/quiz-app/` Vue application to prevent translation-induced build failures.
- Metadata files at `translations/<lang>/.co-op-translator.json` maintain translation state across runs.

## Frequently Asked Questions

### How does the co-op-translator action handle new files added to the repository?

When contributors add new lessons or documentation to the English source, the workflow detects these files during the next trigger event. The action processes all files in the configured `source_dir`, generating corresponding translations in the target language directories regardless of whether the files are new or modified, ensuring comprehensive coverage across all 40+ supported languages.

### Can the translation workflow be manually triggered or scheduled?

While the analyzed configuration triggers on push and pull request events, GitHub Actions supports `workflow_dispatch` inputs and `schedule` cron triggers. Repository maintainers could extend [`.github/workflows/translate.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/.github/workflows/translate.yml) to include these event types for on-demand or nightly translation batches without modifying the core action logic or the co-op-translator service integration.

### What happens if a translation fails for a specific language?

The matrix strategy isolates each language job, meaning a failure in one language (such as `ja` for Japanese) does not block translations for other languages (like `es` for Spanish). The failed job logs appear in the GitHub Actions interface, allowing maintainers to retry specific language jobs without rerunning the entire 40+ language matrix, which preserves pipeline efficiency while maintaining robustness.

### Where are the translated quiz application assets stored?

Translated assets for the Vue.js quiz application reside within the `etc/quiz-app/` directory structure. The workflow runs `npm run lint` against this application after translation commits to ensure that localized strings and Markdown content render correctly within the interactive quiz interface, validating that the co-op-translator output maintains compatibility with the application's build system.