Add i18n support

.github/workflows/rbe.yml

@@ -1,12 +1,19 @@
 name: CI
 on: [push, pull_request]
 
+env:
+  # Update the language picker in index.hbs to link new languages.
+  LANGUAGES:
+
 jobs:
   test:
     name: Run tests
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@master
+    - uses: actions/checkout@v4
+      with:
+        # We need the full history below.
+        fetch-depth: 0
 
     - name: Update rustup
       run: rustup self update
@@ -23,6 +30,10 @@ jobs:
         curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.15/mdbook-v0.4.15-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.0
+
     - name: Report versions
       run: |
         rustup --version
@@ -41,6 +52,28 @@ jobs:
           https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/linkcheck.sh
         sh linkcheck.sh --all rust-by-example
 
+    - name: Build all translations
+      run: |
+        for po_lang in ${{ env.LANGUAGES }}; do
+          POT_CREATION_DATE=$(grep --max-count 1 '^"POT-Creation-Date:' po/$po_lang.po | sed -E 's/".*: (.*)\\n"/\1/')
+          if [[ $POT_CREATION_DATE == "" ]]; then
+              POT_CREATION_DATE=now
+          fi
+
+          echo "::group::Building $po_lang translation as of $POT_CREATION_DATE"
+          rm -r src/
+          git restore --source "$(git rev-list -n 1 --before "$POT_CREATION_DATE" @)" src/
+
+          # Set language and adjust site URL. Clear the redirects
+          # since they are in sync with the source files, not the
+          # translation.
+          MDBOOK_BOOK__LANGUAGE=$po_lang \
+          MDBOOK_OUTPUT__HTML__SITE_URL=/rust-by-example/$po_lang/ \
+          MDBOOK_OUTPUT__HTML__REDIRECT='{}' \
+          mdbook build -d book/$po_lang
+          echo "::endgroup::"
+        done
+
     - name: Upload Artifact
       uses: actions/upload-artifact@v3
       with:

.gitignore

@@ -1,4 +1,6 @@
 book
 
+po/messages.pot
+
 # Auto-generated files from macOS
-.DS_Store
+.DS_Store

README.md

@@ -27,12 +27,37 @@ mdbook serve
 To be able to run the examples, you must be connected to the internet; you can
 read all content offline, however!
 
+The following warnings can be ignored safely.
+
+```
+[WARN] (mdbook::preprocess::cmd): The command wasn't found, is the "gettext" preprocessor installed?
+[WARN] (mdbook::preprocess::cmd):   Command: mdbook-gettext
+```
+
+### Using translated version
+
+If there is a translated resource in `po/` directory, it can be specified through `MDBOOK_BOOK__LANGUAGE` like below:
+
+```bash
+git clone https://github.com/rust-lang/rust-by-example
+cd rust-by-example
+cargo install mdbook
+MDBOOK_BOOK__LANGUAGE=ja mdbook build
+MDBOOK_BOOK__LANGUAGE=ja mdbook serve
+```
+
 ## Contributing
 
 Please see the [CONTRIBUTING.md] file for more details.
 
 [CONTRIBUTING.md]: https://github.com/rust-lang/rust-by-example/blob/master/CONTRIBUTING.md
 
+## Translating
+
+Please see the [TRANSLATING.md] file for more details.
+
+[TRANSLATING.md]: https://github.com/rust-lang/rust-by-example/blob/master/TRANSLATING.md
+
 ## Translations to other languages
 
 * [Chinese](https://github.com/rust-lang-cn/rust-by-example-cn)

TRANSLATING.md

@@ -0,0 +1,85 @@
+# Rust by Example 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/rust-by-example/blob/master/CONTRIBUTING.md
+
+## Translation workflow
+
+### Preparation
+
+RBE 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/rbe.yml` and `theme/index.hbs` like below:
+
+* `rbe.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>
+```

book.toml

@@ -13,6 +13,15 @@ enable = true
 
 [output.html]
 git-repository-url = "https://github.com/rust-lang/rust-by-example"
+additional-css = [
+  "theme/css/language-picker.css",
+]
 
 [rust]
 edition = "2021"
+
+[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;
+}