book-cn: the Chinese translation of The Rust Programming Language

Why the translation was restarted

The rust-lang-cn/book-cn repository is the Chinese translation of The Rust Programming Language, and the note at the top of the README explains why it exists in the form it does.

Because the Chinese versions already available online had fallen behind the English content, the translation was restarted so that it could follow the original book, and the project is described as a key translation project of the Rust Chinese translation group.

The state of it is stated plainly: the document is 100% translated into Chinese, with a last update time of 2022-02-06.

That date is the single most important fact for a reader, and it cuts both ways. The translation is complete, which means every chapter is readable rather than half-translated with gaps. It is also a snapshot of the English book as of early 2022, which means the parts of Rust that moved since then are described as they were then.

The credit policy is also explicit. The translation includes the translation group's own earlier work as well as existing open source translation versions from the internet, such as the KaiserY/trpl-zh-cn version, with the stated aim of avoiding unnecessary duplicated work and gratitude to the original translators.

The repository holds the book source, and the English paperback can be bought from No Starch Press. There is a note on the Chinese publication: the Chinese book title is the Rust authoritative guide, available from online and physical bookshops, and the published version is translated independently of this repository's translation.

The primary language is Rust, the licence is dual Apache 2.0 and MIT, the default branch is master, and the last push to the repository was on 2026-04-16. There are no GitHub releases, since the artefact is a website rather than a package.

Reading it online, and the bilingual switch

The online version can be read on the organisation's own site, and the feature it highlights is that the same page supports switching between Chinese and English.

That is the thing that makes this repository more than a set of translated Markdown files. A reader with some English can move between the two texts without losing their place, which is what makes a lagging translation tolerable rather than disqualifying.

The English version is read on the Rust website, and there the reader can choose between the stable, beta, and nightly branch versions. The README notes that these branch versions may lag the latest content of the English repository, which is the same staleness caveat expressed for the upstream side.

The interesting part is that the bilingual switching is implemented in this repository rather than inherited. The top level entries include a language.js file, a ferris.css and a ferris.js for the mascot styling, and a theme/ directory for the mdBook theme. The language file is the hook that the theme uses to swap the text, which is why a custom theme and a custom script are both needed, and why the repository is more than a fork with translated strings.

The README also links a Translations label in the English upstream repository, and explains how to join: create an issue and start using a new language. There is a caveat, and it is an important one for anyone expecting to contribute a translation today. Before anything is merged, the project is waiting on mdBook support for multiple languages, and once that lands it can begin at any time.

That is a specific upstream dependency blocking a specific workflow, and it is worth knowing if you are considering maintaining a translation in this style, because it means the bilingual approach here cannot be reproduced elsewhere until mdBook grows the capability.

Building the book, and the mdBook version that matters

The dependency section is short and specific about the one thing that will break your build if you get it wrong.

Building the book requires mdBook, and the recommendation is to use the same version that rust-lang/rust specifies in that file, which is the Cargo.toml of the rustbook tool. The install command is:

$ cargo install mdbook --locked --vers [version-num]

Pinning the version is not a formality here, because the book uses a custom theme and custom scripts, and mdBook changes between releases. A newer mdBook than the upstream book was built against will often fail on the theme rather than on the content.

The build itself is one command:

$ mdbook build

The output lands in the book subdirectory, and you open it in a browser. The README gives the command for each browser and platform, which is the kind of detail that is only written by someone who has done it on all four:

$ firefox book/index.html                       # Linux
$ open -a "Firefox" book/index.html             # OS X
$ Start-Process "firefox.exe" .\book\index.html # Windows (PowerShell)
$ start firefox.exe .\book\index.html           # Windows (Cmd)

And the tests are run with:

$ mdbook test

The repository also has a Cargo.toml, and the interesting thing about it is that it is not for the book itself. The package is named rust-book at version 0.0.1 with the description The Rust Book, but the binaries it declares are tools: concat_chapters, convert_quotes, lfp, link2print, release_listings, remove_hidden_lines, remove_links, and remove_markup. The book is Markdown built by mdBook, and the Rust crate exists to build the artefacts around it.

The eight tools, and what each one is for

The binary names in the Cargo manifest describe the pipeline that turns the source tree into the published book, and reading them together tells you what the project actually had to build.

concat_chapters merges the per-chapter source into a single document, which is what the print edition needs. convert_quotes handles the typographic differences between the two languages. lfp is the line-for-line comparison tool, the one that makes it possible to track a translation against a moving upstream. link2print prepares the print version, and release_listings generates the code listings that appear in the book.

Then there are the three removers, remove_hidden_lines, remove_links, and remove_markup. These exist because the book is a polyglot source tree, and the English and Chinese versions do not use the same inline constructs. A line hidden in one language has no counterpart in the other, a link has to be rewritten for the target, and markup differs. The tools strip these constructs per language so that each build produces clean output rather than a shared file with the other language's debris in it.

The dependencies support that reading. walkdir and regex are the tools for walking the tree and rewriting text, docopt is the command line parser that gives each of these binaries its argument handling, serde is for structured data, lazy_static is the usual workaround for statics in Rust, and flate2 and tar are for producing the compressed release tarball.

The tools directory holds the source for all of this, and the src/ directory holds the book itself. The english/ directory holds the upstream text, the listings/ directory holds the code listings, the theme/ directory the mdBook theme, the dot/ directory the diagram sources, and the tools/ directory the Rust programs.

Spell checking, and the dual licence that lets translations merge

Two details in the repository are worth calling out because they say something about how a translation project is run in practice.

The first is the spell checker. To scan the source files for spelling errors you can use the spellcheck.sh script in the ci directory. It needs a dictionary of valid words provided by ci/dictionary.txt, and if the script produces a false positive, for example with a word like BTreeMap that the script considers invalid, you add the word to ci/dictionary.txt while keeping the sorted order for consistency.

That is a detail that sounds trivial and is not. A Chinese translation of a programming book contains thousands of identifiers, type names, and API names, and a spell checker that does not know them flags every one. The dictionary file is a curated list of exactly those words, and the requirement to keep it sorted is what makes it reviewable in a diff.

The second is the licence. The book, both the Chinese version and the English The Rust Programming Language, is offered under either of two licences, Apache 2.0 or MIT, at your choice. Unless you say otherwise, any contribution you submit is dual licensed in that way, with no additional terms or conditions, as the Apache 2.0 agreement provides.

The dual licence is what makes merging possible. The project explicitly credits work from other open source translations, and a permissive dual licence is what allows that to happen without the original translator having to approve each merge. The repository carries both LICENSE-APACHE and LICENSE-MIT files, and a README that points to the upstream English repository and the KaiserY translation as the sources being merged.

Editorial conclusion

Adopt book-cn if you read better in Chinese and want the official book content, since the translation is complete and the build is a single mdBook command. Do not expect it to track the English book week to week, because the translation was last updated on 2022-02-06 and the English side moves continuously. Verify first which mdBook version the upstream Rust repository specifies, since a mismatched version is the usual cause of a build that fails on the book's custom theme.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. rust-lang-cn/book-cn on GitHub