How to Add a New Language to the Web-Dev-For-Beginners Translation Pipeline

Question

Easily add a new language to the Web-Dev-For-Beginners translation pipeline by following simple steps. Update tables and push changes to integrate your translation.

Accepted Answer

To add a new language to the Web-Dev-For-Beginners translation pipeline, create a directory under translations/<language-code>/, seed it with a placeholder README, update the language tables in both README.md and translations/README.md, and push your changes to trigger the co-op-translator GitHub Action.

The microsoft/Web-Dev-For-Beginners repository uses an automated translation pipeline powered by the co-op-translator GitHub Action to maintain curriculum translations across dozens of languages. If you want to add a new language to the translation pipeline, you need to understand the directory structure, metadata requirements, and the specific HTML comments that mark the language table in the README files.

Understanding the Translation Pipeline Architecture

How the Co-op-Translator Action Works

The translation workflow is defined in .github/workflows/ and runs on every push to the repository. According to the source code analysis, the pipeline follows this sequence:

Source files in the repository root (e.g., README.md, lesson READMEs, and project READMEs) are scanned for changes.
The co-op-translator service processes the markdown and writes translated output to translations/<language-code>/ (see the "Translation System" section of AGENTS.md).
Each translated file receives a metadata header that records the original hash, translation date, and language code.

Directory Structure and Metadata Headers

Translated content lives in language-specific folders under the translations/ directory. Each markdown file in these folders must include a metadata header at the top:

<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "a1b2c3d4e5f6...",
  "translation_date": "2026-02-27T12:34:56Z",
  "source_file": "../README.md",
  "language_code": "es"
}
-->

The root README.md and the language index at translations/README.md contain a language table delimited by the comments  and . This table is used by the Docsify site to list available languages.

Prerequisites for Adding a New Language

Before you begin, verify that your target language is supported by the co-op-translator service. Consult the official supported languages list at https://github.com/Azure/co-op-translator/blob/main/getting_started/supported-languages.md. If your language code (e.g., es for Spanish, pt-BR for Brazilian Portuguese) is not listed, you must request support from the co-op-translator project before proceeding.

Step-by-Step Guide to Add a New Language to the Translation Pipeline

Follow these steps to integrate a new language into the automated pipeline:

Fork and clone the repository

# Fork on GitHub first, then clone your fork

git clone https://github.com/<your-username>/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners

Create the language directory

mkdir -p translations/<language-code>
# Example for Spanish:

mkdir -p translations/es

Seed the directory with a placeholder
```
cp README.md translations/<language-code>/README.md
```
This gives the GitHub Action an initial file to process and overwrite with the translated version.
Update the language tables

Edit both README.md (root) and translations/README.md. Locate the block between:
```

```
and
```

```
Add a new entry linking to your language folder, for example:
```
[Spanish](../es/README.md)
```

Commit and push your changes

git add .
git commit -m "[Translation] Add <language-code> language support"
git push origin main

This triggers the co-op-translator GitHub Action.

Verify the integration

After the CI run completes, browse to https://github.com/microsoft/Web-Dev-For-Beginners/tree/main/translations/<language-code> to confirm the files were generated with the proper metadata headers.

Updating the Language Table in README Files

The language table is critical for the Docsify documentation site to display available languages. When you add a new language to the translation pipeline, you must update both locations:

Root README.md: Provides the language switcher on the repository's main page
translations/README.md: Powers the language index for the Docsify site

In both files, look for the HTML comment markers  and . Insert your new language link between these markers, maintaining the existing table format.

Verifying Your Translation Pipeline Integration

After pushing your changes, monitor the GitHub Actions tab in your repository. The co-op-translator workflow should execute automatically, processing your placeholder files and generating translated versions in translations/<language-code>/.

Check that the generated files include the CO_OP_TRANSLATOR_METADATA header with the correct language_code and source_file entries. If the Action fails, verify that your language code appears in the co-op-translator supported languages list and that your directory structure matches the expected pattern.

Summary

The Web-Dev-For-Beginners translation pipeline uses the co-op-translator GitHub Action to automatically generate localized content in translations/<language-code>/ directories.
To add a new language, verify support at the co-op-translator repository, create the language folder, seed it with a placeholder README, and update the language tables in both README.md and translations/README.md.
The language table is delimited by  comments and powers the Docsify site language selector.
The co-op-translator Action overwrites files in language folders on every push, so manual translations must preserve the metadata header or reside in separate files.

Frequently Asked Questions

What languages are supported by the co-op-translator pipeline?

The co-op-translator service supports a specific set of languages defined in the Azure/co-op-translator repository. Before adding a new language to the Web-Dev-For-Beginners translation pipeline, consult the supported languages list at https://github.com/Azure/co-op-translator/blob/main/getting_started/supported-languages.md. If your desired language code is not listed, you must request support from the co-op-translator maintainers before proceeding.

Will the GitHub Action overwrite my manual translations?

Yes, the co-op-translator GitHub Action regenerates all files inside translations/<language-code>/ on every push, overwriting existing content. To preserve manual improvements, either maintain the required CO_OP_TRANSLATOR_METADATA header at the top of your edited files (which allows the Action to recognize and preserve specific sections) or store manual translations in separate files outside the standard pipeline directories.

How do I update the language table correctly?

You must edit both the root README.md and translations/README.md files. Locate the HTML comment markers  and  in each file. Insert your new language link between these markers using the format [Language Name](../<code>/README.md), maintaining the existing table structure. This updates both the repository homepage and the Docsify documentation site language selector.

Where can I verify the translation was generated successfully?

After pushing your changes, navigate to https://github.com/microsoft/Web-Dev-For-Beginners/tree/main/translations/<language-code> (replacing <language-code> with your specific code) to view the generated files. Verify that each markdown file contains the CO_OP_TRANSLATOR_METADATA header with the correct language_code and source_file fields. You can also check the GitHub Actions tab in your repository to confirm the co-op-translator workflow completed without errors.