# How to Add or Update an English Translation for a Course in cs-self-learning

> Learn to add or update an English translation for a course in the cs-self-learning repository. Follow the file-pair convention using .en.md files to contribute.

- Repository: [Yinmin Zhong/cs-self-learning](https://github.com/PKUFlyingPig/cs-self-learning)
- Tags: how-to-guide
- Published: 2026-03-02

---

**To add or update an English translation in the cs-self-learning repository, create or edit a parallel [`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md) file in the same directory as the Chinese source, following the file-pair convention recognized by Material for MkDocs.**

The cs-self-learning repository organizes computer science course resources using a bilingual file structure powered by Material for MkDocs. Contributing an English translation requires understanding the parallel file naming convention and the i18n configuration defined in [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml). This guide explains the exact steps to locate, create, and commit translation files that integrate automatically with the site's continuous deployment pipeline.

## Understanding the Bilingual File Structure

The repository stores each course as a **file pair** under the `docs/` directory:

- **Chinese version**: `docs/<category>/<course>.md`
- **English version**: `docs/<category>/<course>.en.md`

When MkDocs builds the site with the `en` locale, the **Material for MkDocs** plugin automatically detects the [`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md) suffix and renders that file instead of the Chinese source. If no English file exists, the build falls back to the Chinese content. This behavior is controlled by the `i18n` plugin configuration in [[`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml)](https://github.com/PKUFlyingPig/cs-self-learning/blob/master/mkdocs.yml), which also contains the `nav_translations` block mapping Chinese navigation labels to English equivalents (e.g., "软件工程" → "Software Engineering").

## Step-by-Step Guide to Adding or Updating Translations

### 1. Locate the Course Directory

Browse the repository structure under `docs/` to find the target course. For example, the UC Berkeley CS169 software engineering course resides at `docs/软件工程/CS169.md` [\[source\]](https://github.com/PKUFlyingPig/cs-self-learning/blob/master/docs/软件工程/CS169.md).

### 2. Create or Modify the English Translation File

Check for an existing [`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md) file in the same directory:

- **If adding a new translation**: Copy the Chinese file and rename it with the [`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md) suffix.
  ```bash
  cd docs/软件工程
  cp CS169.md CS169.en.md
  ```

- **If updating an existing translation**: Open `docs/软件工程/CS169.en.md` [\[source\]](https://github.com/PKUFlyingPig/cs-self-learning/blob/master/docs/软件工程/CS169.en.md) directly in your editor.

### 3. Translate Content While Preserving Structure

Edit the Markdown file to translate headings and body text into English. **Preserve the original Markdown structure**—including heading levels, list formatting, and tables—so the navigation generated by MkDocs remains consistent across languages. Only the visible text content requires translation; frontmatter and anchor links should maintain their functional relationships.

Example structure to maintain:

```markdown

# UCB CS169: Software Engineering

## Descriptions

- Offered by: UC Berkeley
- Prerequisites: None
- Programming Languages: Ruby/JavaScript
- Difficulty: 🌟🌟🌟🌟
- Class Hour: 100 hours

This is Berkeley's software engineering course...

```

### 4. Commit and Push Changes

Stage your translation file and commit with a descriptive message. The GitHub Actions workflow defined in [`.github/workflows/ci.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.github/workflows/ci.yml) triggers automatically on each push to rebuild the site.

```bash
git add docs/软件工程/CS169.en.md
git commit -m "Add English translation for CS169 (Software Engineering)"
git push origin main

```

### 5. Verify the English Site

After the CI pipeline completes, visit the English version of the site at `https://csdiy.wiki/en/`. Navigate to the corresponding section (e.g., "Software Engineering") to confirm your translation renders correctly and the navigation labels display in English as mapped in [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml).

## Key Configuration and Automation

The translation system relies on three critical components:

- **[`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml)**: Contains the `i18n` plugin configuration that enables the file-pair detection mechanism and the `nav_translations` dictionary for menu localization.
- **File-pair convention**: The Material theme looks for `<filename>.en.md` when serving the English locale, creating a seamless override system that requires no manual routing changes.
- **CI/CD integration**: The workflow in [`.github/workflows/ci.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.github/workflows/ci.yml) executes MkDocs on every push, ensuring translations go live without manual server access or build commands.

## Summary

- The cs-self-learning repository uses a **parallel file structure** where English translations live as [`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md) siblings to Chinese `.md` files.
- **Material for MkDocs** automatically selects the appropriate language file based on the build locale configured in [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml).
- To contribute a translation, **copy the Chinese source**, rename it with the [`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md) extension, translate the visible text while preserving Markdown structure, and commit to trigger the CI pipeline.
- The **navigation translation** is handled centrally in [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml) via `nav_translations`, so individual course files only need content translation, not menu label updates.

## Frequently Asked Questions

### Do I need to update mkdocs.yml when adding a new course translation?

No. The `i18n` plugin in Material for MkDocs automatically discovers [`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md) files using the file-pair convention. You only need to edit [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml) if you are adding an entirely new course category that requires navigation translation mapping, not for translating existing course content.

### What happens if I only translate part of a course file?

The Material theme will render the [`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md) file as-is, displaying partial English content. If sections remain untranslated, they will appear in English only if you translated them; otherwise, that specific file will show a mix of translated and untranslated content. The system does not fall back to Chinese for individual sections within a file—only for entire missing files.

### How long does it take for my translation to appear on the live site?

Translations typically appear within minutes of pushing to the main branch. The GitHub Actions workflow defined in [`.github/workflows/ci.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.github/workflows/ci.yml) executes immediately on push, building the static site and deploying it to the hosting environment automatically.

### Can I use HTML tags or special Markdown extensions in translations?

Yes, but preserve the existing Markdown structure and any special syntax used in the Chinese source (such as admonitions or emoji ratings). The English file must remain valid Markdown that MkDocs can parse identically to its Chinese counterpart to ensure consistent rendering and navigation anchor generation.