Add translation support

.github/workflows/main.yml

@@ -1,6 +1,10 @@
 name: CI
 on: [push, pull_request]
 
+env:
+  # Update the language picker in index.hbs to link new languages.
+  LANGUAGES:
+
 jobs:
   test:
     name: Run tests
@@ -17,7 +21,7 @@ jobs:
     - name: Install mdbook
       run: |
         mkdir bin
-        curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.21/mdbook-v0.4.21-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
+        curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.37/mdbook-v0.4.37-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
         echo "$(pwd)/bin" >> ${GITHUB_PATH}
     - name: Report versions
       run: |
@@ -64,8 +68,10 @@ jobs:
     - name: Install mdbook
       run: |
         mkdir bin
-        curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.21/mdbook-v0.4.21-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
+        curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.37/mdbook-v0.4.37-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
         echo "$(pwd)/bin" >> ${GITHUB_PATH}
+    - name: Install mdbook-i18n-helpers
+      run: cargo install mdbook-i18n-helpers --locked --version 0.3.3
     - name: Install mdbook-trpl-note
       run: cargo install --path packages/mdbook-trpl-note
     - name: Install mdbook-trpl-listing
@@ -97,3 +103,17 @@ jobs:
           https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/linkcheck.sh
         # Cannot use --all here because of the generated redirect pages aren't available.
         sh linkcheck.sh book
+    - name: Build all translations
+      run: |
+        for po_lang in ${{ env.LANGUAGES }}; do
+          echo "::group::Building $po_lang translation"
+          MDBOOK_BOOK__LANGUAGE=$po_lang \
+          mdbook build -d book/$po_lang
+          echo "::endgroup::"
+        done
+    - name: Check all translations for broken links
+      run: |
+        for po_lang in ${{ env.LANGUAGES }}; do
+          MDBOOK_BOOK__LANGUAGE=$po_lang \
+          sh linkcheck.sh --all rust-by-example
+        done

.gitignore

@@ -4,4 +4,5 @@ book/
 .DS_Store
 target
 tmp
+po/messages.pot
 

README.md

@@ -66,6 +66,21 @@ To run the tests:
 $ mdbook test
 ```
 
+The following warnings can be ignored safely if you don't build a translated version.
+
+```
+[WARN] (mdbook::preprocess::cmd): The command wasn't found, is the "gettext" preprocessor installed?
+[WARN] (mdbook::preprocess::cmd):   Command: mdbook-gettext
+```
+
+### Building translated version
+
+If there is a translated resource in `po/` directory, it can be specified through `MDBOOK_BOOK__LANGUAGE` like below:
+
+```bash
+MDBOOK_BOOK__LANGUAGE=ja mdbook build
+```
+
 ## Contributing
 
 We'd love your help! Please see [CONTRIBUTING.md][contrib] to learn about the
@@ -85,6 +100,12 @@ isn't strictly fixing an error, it might sit until the next time that we're
 working on a large revision: expect on the order of months or years. Thank you
 for your patience!
 
+## Translating
+
+Please see the [TRANSLATING.md] file for more details.
+
+[TRANSLATING.md]: https://github.com/rust-lang/book/blob/main/TRANSLATING.md
+
 ### Translations
 
 We'd love help translating the book! See the [Translations] label to join in

TRANSLATING.md

@@ -0,0 +1,98 @@
+# Translation guidelines
+
+Please see the [CONTRIBUTING.md] file for general contribution guidelines.
+This file describes about the translation workflow.
+
+[CONTRIBUTING.md]: https://github.com/rust-lang/book/blob/main/CONTRIBUTING.md
+
+## Translation workflow
+
+### Preparation
+
+The book uses [mdbook-i18n-helpers](https://github.com/google/mdbook-i18n-helpers) as a translation framework.
+The following tools are required.
+
+* GNU gettext utilities ( `msgmerge` and `msgcat` )
+* mdbook-i18n-helpers ( `cargo install mdbook-i18n-helpers` )
+
+### Creating and Updating Translations
+
+Please see the [mdbook-i18n-helpers USAGE](https://github.com/google/mdbook-i18n-helpers/blob/main/i18n-helpers/USAGE.md) file for the detailed usage of mdbook-i18n-helpers.
+The summarized command list is below:
+
+#### Generating a message template
+
+The generated message templete `po/messages.pot` is required to create or update translations.
+
+```bash
+MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot"}}' \
+  mdbook build -d po
+```
+
+#### Creating a new translation resource
+
+`xx` is [ISO 639](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code.
+
+```bash
+msginit -i po/messages.pot -l xx -o po/xx.po
+```
+
+#### Updating the exising translation resource
+
+```bash
+msgmerge --update po/xx.po po/messages.pot
+```
+
+### Editing translation resources
+
+After generating a translation resource `po/xx.po`, you can write translation messages in `msgstr` entry of `po/xx.po`.
+To build a translated book, the following command can be used.
+
+```bash
+MDBOOK_BOOK__LANGUAGE=xx mdbook build
+MDBOOK_BOOK__LANGUAGE=xx mdbook serve
+```
+
+### Add a language entry
+
+Please add a language entry in `.github/workflows/main.yml`, `theme/index.hbs`, and `src/bootstrap/src/core/build_steps/doc.rs` in [rust-lang/rust](https://github.com/rust-lang/rust) like below:
+
+* `main.yml`
+
+```yml
+env:
+  # Update the language picker in index.hbs to link new languages.
+  LANGUAGES: xx yy zz
+```
+
+* `index.hbs`
+
+```html
+<ul id="language-list" class="theme-popup" aria-label="Languages" role="menu">
+  <li role="none"><button role="menuitem" class="theme">
+      <a id="en">English</a>
+  </button></li>
+  <li role="none"><button role="menuitem" class="theme">
+      <a id="xx">XX language</a>
+  </button></li>
+  <li role="none"><button role="menuitem" class="theme">
+      <a id="yy">YY language</a>
+  </button></li>
+  <li role="none"><button role="menuitem" class="theme">
+      <a id="zz">ZZ language</a>
+  </button></li>
+</ul>
+```
+
+* `src/bootstrap/src/core/build_steps/doc.rs` in [rust-lang/rust](https://github.com/rust-lang/rust)
+
+```rust
+// build book
+builder.ensure(RustbookSrc {
+    target,
+    name: "book".to_owned(),
+    src: absolute_path.clone(),
+    parent: Some(self),
+    languages: vec!["xx", "yy", "zz"],
+});
+```

book.toml

@@ -6,7 +6,7 @@ title = "The Rust Programming Language"
 authors = ["Steve Klabnik", "Carol Nichols", "Contributions from the Rust Community"]
 
 [output.html]
-additional-css = ["ferris.css", "theme/2018-edition.css", "theme/semantic-notes.css", "theme/listing.css"]
+additional-css = ["ferris.css", "theme/css/2018-edition.css", "theme/css/semantic-notes.css", "theme/css/listing.css", "theme/css/language-picker.css"]
 additional-js = ["ferris.js"]
 git-repository-url = "https://github.com/rust-lang/book"
 
@@ -15,3 +15,9 @@ git-repository-url = "https://github.com/rust-lang/book"
 
 [preprocessor.trpl-listing]
 output-mode = "default"
+
+[build]
+extra-watch-dirs = ["po"]
+
+[preprocessor.gettext]
+after = ["links"]

theme/css/language-picker.css

@@ -0,0 +1,13 @@
+#language-list {
+  left: auto;
+  right: 10px;
+}
+
+[dir="rtl"] #language-list {
+  left: 10px;
+  right: auto;
+}
+
+#language-list a {
+  color: inherit;
+}