# How to Add a New Language to the Web-Dev-For-Beginners Translation Pipeline > 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. - Repository: [Microsoft/Web-Dev-For-Beginners](https://github.com/microsoft/Web-Dev-For-Beginners) - Tags: how-to-guide - Published: 2026-02-27 --- **To add a new language to the Web-Dev-For-Beginners translation pipeline, create a directory under `translations//`, seed it with a placeholder README, update the language tables in both [`README.md`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/README.md) and [`translations/README.md`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/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: 1. **Source files** in the repository root (e.g., [`README.md`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/README.md), lesson READMEs, and project READMEs) are scanned for changes. 2. The **co-op-translator** service processes the markdown and writes translated output to `translations//` (see the "Translation System" section of [`AGENTS.md`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/AGENTS.md)). 3. 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: ```markdown ``` The root [`README.md`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/README.md) and the language index at [`translations/README.md`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/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: 1. **Fork and clone the repository** ```bash # Fork on GitHub first, then clone your fork git clone https://github.com//Web-Dev-For-Beginners.git cd Web-Dev-For-Beginners ``` 2. **Create the language directory** ```bash mkdir -p translations/ # Example for Spanish: mkdir -p translations/es ``` 3. **Seed the directory with a placeholder** ```bash cp README.md translations//README.md ``` This gives the GitHub Action an initial file to process and overwrite with the translated version. 4. **Update the language tables** Edit both [`README.md`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/README.md) (root) and [`translations/README.md`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/translations/README.md). Locate the block between: ```markdown ``` and ```markdown ``` Add a new entry linking to your language folder, for example: ```markdown [Spanish](../es/README.md) ``` 5. **Commit and push your changes** ```bash git add . git commit -m "[Translation] Add language support" git push origin main ``` This triggers the co-op-translator GitHub Action. 6. **Verify the integration** After the CI run completes, browse to `https://github.com/microsoft/Web-Dev-For-Beginners/tree/main/translations/` 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`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/README.md)**: Provides the language switcher on the repository's main page - **[`translations/README.md`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/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//`. 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//` 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`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/README.md) and [`translations/README.md`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/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//` 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`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/README.md) and [`translations/README.md`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/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](..//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/` (replacing `` 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.