LearnOpenGL-CN: the Simplified Chinese translation of learnopengl.com and how to build it locally

What LearnOpenGL-CN is, and the reader it is written for

LearnOpenGL-CN is the Simplified Chinese translation of the learnopengl.com tutorial series by JoeyDeVries. The repository describes itself as a Chinese localization project and states that it is currently being proofread and translated. It is aimed at Chinese-speaking programmers who want to learn OpenGL from a structured course rather than from API reference pages, and who would rather read the lessons in their own language while keeping the original code and terminology intact.

The project is not a library, a binding or a wrapper. There is nothing to import into a graphics program. What it ships is a documentation tree under docs/, a MkDocs configuration in mkdocs.yml, a glossary.md, a styleguide.md, and an old/ directory that appears to hold earlier material. The published site is hosted on GitHub Pages at learnopengl-cn.github.io, and the README also points to an older Read the Docs host that it says is updated irregularly.

The honest framing matters here. The README's status list says most of the original code has changed because the tutorials now use different libraries, that the configuration chapters have already been updated, and that work on the rest is in progress. It also says the translation has not yet settled on a unified set of translated terms. A reader who wants a finished textbook should know that before starting.

How the translation is organized: Markdown files, MkDocs, and a glossary

The unit of work is a Markdown file. The README gives a naming convention built from a two-digit chapter number, the chapter name, a two-digit section number and the section name, with an optional third level for subsections. Two examples it provides are 01 Getting started/01 OpenGL.md and 05 Advanced Lighting/03 Shadows/02 Point Shadows.md. Keeping the numbers in the path is what lets MkDocs order the navigation without a separate index file for every chapter.

Each translated file opens with a small table carrying three rows: the original article link, the author (JoeyDeVries in the README's template), and the translator, with a proofreader row that starts as 暂无, meaning none yet. That header is the mechanism the project uses to track provenance and to avoid two volunteers translating the same page.

The build itself is MkDocs, a static site generator that reads mkdocs.yml and turns the Markdown tree into HTML in a site/ directory. The README pins two dependencies, mkdocs==1.4.2 and python-markdown-math==0.8, and the presence of python-markdown-math suggests the lessons include LaTeX-style formulas in places. The repository also carries a tools/ directory and a yeti/ directory, and a .github/ directory that holds the deploy workflow whose status badge sits at the top of the README.

One design choice worth noting: the default branch is new-theme, not main or master. Pull requests and clones that assume the default branch name will land on the theme rework rather than on whatever the older layout was, and the old/ directory plus the Read the Docs link suggest that older layout still exists somewhere.

Building the site locally with mkdocs serve

The README gives a short build path. It asks for Python 3.7 or newer, then two pinned packages. Run this once to create the environment:

pip install mkdocs==1.4.2 python-markdown-math==0.8

After that, a full build writes the static site into the site folder:

mkdocs build

For reading while you work, the README recommends the development server:

mkdocs serve

It states that the deployed page is reachable at 127.0.0.1:8000. Open that address in a browser and you should see the Chinese tutorial site rendered from the Markdown under docs/, with the navigation order taken from the file names. If a page is missing from the sidebar, the usual cause is a file that does not follow the two-digit numbering convention the README describes, because MkDocs has no other ordering hint for it.

If you want to contribute rather than just read, the README asks you to read styleguide.md first, then contact the maintainers to be added to the LearnOpenGL-CN organization before pushing. It also accepts a fork-and-pull-request route, with pull requests targeted at the new-theme branch. The README gives a QQ group number, 383745868, as the contact channel.

Where the translation is incomplete, and what that means for a learner

The README is unusually direct about the state of the text. It lists four open items: most of the original code has changed because of new libraries, so proofreading has to restart, with the configuration sections already done; everything after section 5-2 is not laid out in the new format, contains many errors, and lacks unified terminology; a full pass over the revised articles is wanted from volunteers; and the PBL chapter and the In Practice chapter still contain tutorials that have not been translated at all.

For a reader, that translates into a practical rule. Early configuration material is the most reliable part, because the README says it has been updated. Advanced lighting, model loading, and the later chapters are the parts most likely to show inconsistent terminology or leftover formatting, and the PBL and In Practice sections may simply be absent in Chinese. If a page looks wrong, the README's guidance is to check the English original first, and only report a translation error if the original does not have the same problem.

There is a second limitation that has nothing to do with translation quality. The site is a static documentation build. It has no versioned API surface, no release artifacts, and no changelog in the repository listing. The only way to know what changed is to read the commit history on the new-theme branch. Anyone expecting semver-style upgrades from this project is looking at the wrong kind of repository.

LearnOpenGL-CN against the English original and other OpenGL references

The obvious alternative is learnopengl.com itself, the English source this project translates. The difference is not coverage but authorship and freshness. The English site is the place where corrections land first, and the README tells readers with content questions to raise them there, in the original site's comment section, rather than in the Chinese repository. The Chinese repository, by contrast, is a downstream copy that can lag, and the README's own status list is the evidence for that lag.

A second alternative is the older Read the Docs host that the README links. It is the same translation published through a different pipeline, and the README describes it as updated irregularly, so it is a fallback rather than a parallel edition. Choosing between the two hosts is really choosing between a GitHub Pages build driven by the deploy workflow and a Read the Docs build that the maintainers do not keep in step.

If your goal is a printed or offline copy, note what the repository does not provide. There is no PDF in the top-level entries, and the README does not document an export step. The build output is HTML in site/, which you can host or read locally, but generating a PDF from it is your own problem, not a documented feature.

Maintenance, licensing and the cost of keeping a translation alive

The last push to the repository was on 2026-03-20, and the repository is not archived. The README describes ongoing work by a named contributor, Krasjet, on re-proofreading and reformatting, and it asks for volunteers for the remaining chapters. That is a maintenance model based on volunteers rather than a release cadence, and the repository listing shows no releases at all, so there is no version number to pin and no upgrade notes to read.

The upgrade cost for a reader is therefore not a dependency bump. It is re-reading pages that may have changed under you, and checking the glossary when a term looks unfamiliar. For a contributor, the cost is higher: you must follow styleguide.md, keep the file naming convention exact, and coordinate through the organization or the QQ group so two people do not translate the same section.

The licence is the part to check yourself. The repository's licence field is not identified in the repository metadata, which means the terms under which the translation text can be reused, mirrored or republished are not stated where the project exposes them. The upstream English tutorials are the work of JoeyDeVries, and the README's per-file header records both author and translator. Before republishing any part of the Chinese text, look for a LICENSE file in the repository and, if there is none, ask the maintainers directly. That is a factual gap to resolve, not a legal opinion.

Editorial conclusion

Adopt LearnOpenGL-CN if you want the learnopengl.com material in Simplified Chinese and are willing to read around parts the README marks as still being proofread. Do not adopt it as a substitute for the English original if you need a settled, fully reformatted text, because the README states that everything after section 5-2 is not yet in the new format and that the PBL and In Practice chapters still contain untranslated tutorials. Before relying on a chapter, open the corresponding file under docs/ and compare its structure against the English page, then build the site locally with mkdocs serve and read the page at 127.0.0.1:8000 rather than trusting a cached copy.

Frequently asked questions

Official sources

1. Issues
2. LearnOpenGL-CN/LearnOpenGL-CN on GitHub
3. Project website
4. README