How to Add Translations for New Languages Using the co-op-translator GitHub Action

The co-op-translator GitHub Action automates multilingual support in the microsoft/AI-For-Beginners repository by detecting English content changes and generating translated copies in parallel translations/ folders for each configured language.

This guide walks through the exact steps to extend the AI-For-Beginners curriculum to new languages. The repository stores all original instructional material—Markdown lessons, Jupyter notebooks, images, and quiz assets—in English under lessons/, examples/, and etc/quiz-app/. The co-op-translator Action maintains synchronized translations without manual file copying.

How the co-op-translator Action Works

The workflow operates on every push to main and on pull requests that modify English source files. Understanding this pipeline helps when adding new language support.

Translation Pipeline Steps

1. Change detection – Scans for added, removed, or updated content in root documentation directories
2. Configuration lookup – Reads .co-op-translator.json from each language folder
3. Machine translation – Uses configured services (Azure Translator, Google Cloud Translation) to convert English fragments
4. Automated commit – Creates a new branch and opens a pull request with translated content
5. CI validation – Runs scorecard.yml and codeql.yml to catch syntax errors and security issues

The parallel folder structure means lessons/01-intro-to-ai/README.md becomes translations/es/lessons/01-intro-to-ai/README.md for Spanish—mirroring paths exactly.

Adding a New Translation Language

Adding support requires only two manual steps: creating the language directory and adding its configuration file.

Step 1: Create the Language Folder

Create a new subdirectory under translations/ using standard language codes:

mkdir -p translations/es

Supported languages in the repository include zh-TW (Traditional Chinese), ta (Tamil), and others—each with identical internal structure to the English root.

Step 2: Add the Configuration File

Create .co-op-translator.json in your new language folder:

cat > translations/es/.co-op-translator.json <<'EOF'
{
  "language": "es",
  "service": "azure",
  "secretName": "AZURE_TRANSLATOR_KEY"
}
EOF

Critical configuration fields:

Field	Purpose
language	ISO language code matching the folder name
service	Translation provider (azure or google)
secretName	Repository secret containing API credentials

Store the actual API key as an encrypted repository secret—never commit keys directly.

Manually Triggering Translation Runs

For one-off updates or initial population of a new language, use manual workflow dispatch:

# .github/workflows/translate.yml

name: Manual Translation
on:
  workflow_dispatch:
    inputs:
      language:
        description: 'Target language code (e.g., es, fr)'
        required: true
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run co‑op‑translator
        uses: microsoft/co-op-translator@v1
        with:
          language: ${{ github.event.inputs.language }}

Navigate to Actions → Manual Translation → Run workflow in the GitHub UI, enter your language code, and execute. This invokes the same pipeline used for automatic PRs.

Key Files and Their Roles

Understanding the repository structure ensures correct placement of new translation resources:

• translations/ – Root of all language-specific content; each subfolder contains a complete curriculum copy
• translations/<lang>/.co-op-translator.json – Per-language configuration for the Action
• .github/workflows/scorecard.yml – CI pipeline including translation checks
• .github/workflows/codeql.yml – Security analysis for generated translation branches
• CONTRIBUTING.md – Contributor guidelines for translation workflows
• README.md – Repository overview with automated translation notes

Maintaining Translation Quality

The co-op-translator Action reduces manual overhead but does not eliminate human review. Generated pull requests should be reviewed by native speakers for:

• Technical terminology accuracy
• Code snippet preservation (variables and syntax must remain unchanged)
• Cultural appropriateness of examples

The repository's CI pipelines catch structural issues, but linguistic quality requires community validation.

Summary

• One folder, one config file – Adding translations/<lang>/ plus .co-op-translator.json enables automatic translation
• Parallel structure – All translated content mirrors original English paths exactly
• Automated synchronization – Pushes to main trigger translation updates for all configured languages
• Secure credential handling – API keys live in repository secrets, never in committed files
• Manual override available – Workflow dispatch enables on-demand translation runs

Frequently Asked Questions

What translation services does co-op-translator support?

The Action supports Azure Translator and Google Cloud Translation as backends. Configure your preferred service in .co-op-translator.json using the service field, and store the corresponding API key as a repository secret referenced by secretName.

Do I need to manually copy files when adding a new language?

No. After creating the language folder and configuration file, run the manual workflow or push any change to trigger automatic population. The Action creates all necessary files and directory structure without manual copying.

How do I update translations when English source material changes?

Updates happen automatically. When merged PRs modify content in lessons/, examples/, or etc/quiz-app/, the Action detects changes and opens a new PR with synchronized translations for all configured languages.

Can I exclude specific files from translation?

Custom mapping rules in .co-op-translator.json control file inclusion. Refer to the co-op-translator documentation linked in CONTRIBUTING.md for advanced configuration options like path filtering and content-type exclusions.

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