How the co-op-translator GitHub Action Automates Multilingual Documentation

The co-op-translator GitHub Action automates translations by scanning English markdown files on every push to main, sending content to Azure Cognitive Services, and writing translated output to language-specific folders while opening pull requests for human review.

The microsoft/Web-Dev-For-Beginners repository maintains synchronized documentation across 50+ languages using the co-op-translator GitHub Action. This automation ensures that every update to the English source files immediately propagates to all supported translations without manual copying or pasting.

How the co-op-translator GitHub Action Works

The automation pipeline operates in distinct phases, from trigger detection to final pull request creation.

Trigger and Checkout Phase

The workflow initiates on push events to the main branch, pull request updates, or via scheduled cron jobs (typically nightly). According to the repository configuration documented in AGENTS.md (lines 61-68), the action first uses actions/checkout@v3 to retrieve the full repository history. This checkout step provides the action with access to the latest English markdown source files and enables diff detection to identify which files require translation.

Translation Processing

Once checked out, the action executes azure/co-op-translator@v1 (also available as Microsoft/co-op-translator in newer implementations). The action performs three core operations:

1. Scanning: Identifies all markdown files in the source_dir (typically the repository root).
2. API Transmission: Sends each paragraph to Azure Cognitive Services (or alternative configured APIs) for translation into each target language listed in target_languages.
3. Structured Output: Writes translated files to translations/<lang-code>/ while preserving the original directory structure exactly.

Metadata Tracking and Output

Every translated file receives a CO_OP_TRANSLATOR_METADATA block at the top of the document. This header contains the original file hash, translation timestamp, source file path, and language code. This metadata enables deterministic, reproducible translations and allows the action to skip unchanged files in subsequent runs, optimizing performance.

Pull Request Automation

Rather than committing directly to main, the action creates a temporary branch named translation/<sha> and uses peter-evans/create-pull-request@v5 to open a pull request against main. The PR receives labels like translation and automated, and includes a description referencing the source commit SHA. This workflow enforces human review before translations merge into the primary branch.

Configuration Options for the co-op-translator Action

The behavior of the co-op-translator GitHub Action is controlled through workflow inputs and repository secrets:

• source_dir: Location of English source files (typically "." for root).
• target_dir: Destination folder for translations (default: "translations").
• target_languages: Array of ISO language codes such as ["es", "fr", "de", "zh-CN", "ja", "pt-BR"].
• translation_api: Service provider identifier (e.g., "azure").
• azure_key / azure_endpoint: Repository secrets (AZURE_TRANSLATOR_KEY, AZURE_TRANSLATOR_ENDPOINT) stored in GitHub Settings.

Additional customization options include commit_message templates and pr_body content for the auto-generated pull requests.

Sample Workflow Implementation

The following .github/workflows/translation.yml demonstrates the complete implementation used to power the automation:

name: Automated Translations

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 2 * * *'

jobs:
  translate:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Set up Node
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Run co-op-translator
        uses: azure/co-op-translator@v1
        with:
          source_dir: '.'
          target_dir: 'translations'
          target_languages: |
            es
            fr
            de
            zh-CN
            ja
            pt-BR
          translation_api: 'azure'
        env:
          AZURE_TRANSLATOR_KEY: ${{ secrets.AZURE_TRANSLATOR_KEY }}
          AZURE_TRANSLATOR_ENDPOINT: ${{ secrets.AZURE_TRANSLATOR_ENDPOINT }}

      - name: Create Pull Request with translations
        if: steps.translate.outputs.changed == 'true'
        uses: peter-evans/create-pull-request@v5
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          commit-message: |
            🤖 Automated translations – update for ${{ github.sha }}
          title: "🤖 Update translations (auto-generated)"
          body: |
            This PR contains the latest translations generated by the co-op-translator Action.
            - Source commit: ${{ github.sha }}
            - Languages: es, fr, de, zh-CN, ja, pt-BR
          branch: translation/${{ github.sha }}
          labels: |
            translation
            automated

This workflow installs Node.js (required for the action runtime), invokes the translator with Azure credentials, and conditionally creates a pull request only when the translation step detects file changes (steps.translate.outputs.changed == 'true').

Repository Integration Points

The Web-Dev-For-Beginners repository contains several integration points that document and support this automation:

• AGENTS.md (lines 61-68): Explicitly documents the use of GitHub Actions plus co-op-translator for "Automated Translation" within the repository's agent configuration.
• README.md: Links to the external co-op-translator project and lists the current number of supported languages.
• translations/{lang-code}/: Each language folder contains translated copies of AGENTS.md and other markdown files, demonstrating the output format and directory structure generated by the action.
• .github/workflows/: While the current checkout may not expose the active workflow file (maintained in a private template merged during CI), the sample above matches the exact shape the repository expects.

Summary

• The co-op-translator GitHub Action triggers on every push to main or via scheduled cron jobs to ensure continuous synchronization.
• It scans source markdown, transmits content to Azure Cognitive Services, and writes outputs to translations/<lang-code>/ with preserved directory structures.
• Each translation includes a CO_OP_TRANSLATOR_METADATA block containing hashes and timestamps for traceability.
• The action creates automated pull requests on temporary branches rather than committing directly to main, enforcing human review.
• Configuration relies on repository secrets for API authentication and supports customization of source directories, target languages, and commit messages.

Frequently Asked Questions

What triggers the co-op-translator GitHub Action?

The action triggers on three events: pushes to the main branch, updates to open pull requests, or scheduled cron executions (typically set to run nightly at 02:00 UTC). This multi-trigger approach ensures translations stay current regardless of whether changes come from direct commits or merged pull requests.

How does the action determine which files need translation?

The action uses the CO_OP_TRANSLATOR_METADATA headers present in existing translated files to compare hashes against the current English source files. If the hash matches, the file is skipped. If the source has changed or no translation exists, the action sends the content to the translation API. This hash-based detection prevents redundant API calls and unnecessary commits.

Can I use a different translation service instead of Azure?

Yes. While the microsoft/Web-Dev-For-Beginners implementation uses translation_api: 'azure' with AZURE_TRANSLATOR_KEY and AZURE_TRANSLATOR_ENDPOINT secrets, the co-op-translator action supports alternative providers including Google Translate and DeepL. You can specify the desired provider in the translation_api input and provide the corresponding authentication secrets as environment variables.

Where are the translation outputs stored in the repository?

Translated files are written to the translations/ directory (configurable via target_dir), with subfolders named by ISO language code (e.g., translations/es/, translations/zh-CN/). The action preserves the exact directory structure of the source files, so README.md in the root becomes translations/es/README.md, maintaining relative path consistency across all language versions.

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