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

> Learn to add translations for new languages using the co-op-translator GitHub Action. Automate your multilingual content generation for the AI For Beginners repository.

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

---

**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`](https://github.com/microsoft/AI-For-Beginners/blob/main/.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`](https://github.com/microsoft/AI-For-Beginners/blob/main/scorecard.yml) and [`codeql.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/codeql.yml) to catch syntax errors and security issues

The parallel folder structure means [`lessons/01-intro-to-ai/README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/lessons/01-intro-to-ai/README.md) becomes [`translations/es/lessons/01-intro-to-ai/README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/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:

```bash
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`](https://github.com/microsoft/AI-For-Beginners/blob/main/.co-op-translator.json) in your new language folder:

```bash
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:

```yaml

# .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`](https://github.com/microsoft/AI-For-Beginners/blob/main/.github/workflows/scorecard.yml)** – CI pipeline including translation checks
- **[`.github/workflows/codeql.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/.github/workflows/codeql.yml)** – Security analysis for generated translation branches
- **[`CONTRIBUTING.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md)** – Contributor guidelines for translation workflows
- **[`README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/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`](https://github.com/microsoft/AI-For-Beginners/blob/main/.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`](https://github.com/microsoft/AI-For-Beginners/blob/main/.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`](https://github.com/microsoft/AI-For-Beginners/blob/main/.co-op-translator.json) control file inclusion. Refer to the co-op-translator documentation linked in [`CONTRIBUTING.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md) for advanced configuration options like path filtering and content-type exclusions.