Use mdbook-i18n-helpers to support translations

This PR expands the publishing step to also publish a (very partial) Danish translation of the book. The infrastructure uses the GNU Gettext tools, as well as a mdbook plugin: sudo apt install gettext cargo install mdbook-i18n-helpers The translation lives in po/da.po, which was created with MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot"}}' mdbook build -d po msginit -l da -i po/messages.pot -o po/da.po After creating the da.po file, the translation can be served locally with: MDBOOK_BOOK__LANGUAGE=da mdbook serve The publication flow on GitHub has been expanded to publish translations into subdirectories named after the two-letter ISO_639-1 language codes. The English source text stays the same. Links to the new translations are added manually in the index.hbs theme file[1]. I imported the one from mdbook and added a very simple language picker in the top right corner. [1]: https://raw.githubusercontent.com/rust-lang/mdBook/master/src/theme/index.hbs
rust-embedded · mgeisler · May 16, 2023 · May 16, 2023 · 5e26a4d2cb00da06d788b044d8d60254aa06bcfc
commit 5e26a4d2cb00da06d788b044d8d60254aa06bcfc
@@ -5,6 +5,11 @@ on:
     branches: [ staging, trying, master ]
   pull_request:
 
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
 jobs:
   build:
     runs-on: ubuntu-20.04
@@ -21,25 +26,9 @@ jobs:
       - name: Put pip binary directory into path
         run: echo "~/.local/bin" >> $GITHUB_PATH
 
-      - name: Cache Cargo installed binaries
-        uses: actions/cache@v1
-        id: cache-cargo
-        with:
-          path: ~/cargo-bin
-          key: cache-cargo
-      - name: Install mdbook
-        if: steps.cache-cargo.outputs.cache-hit != 'true'
-        uses: actions-rs/install@v0.1
+      - uses: moonrepo/setup-rust@v0
         with:
-          crate: mdbook
-          version: latest
-      - name: Copy mdbook to cache directory
-        if: steps.cache-cargo.outputs.cache-hit != 'true'
-        run: |
-          mkdir ~/cargo-bin
-          cp ~/.cargo/bin/mdbook ~/cargo-bin
-      - name: Put new cargo binary directory into path
-        run: echo "~/cargo-bin" >> $GITHUB_PATH
+          bins: mdbook, mdbook-i18n-helpers
 
       - name: Build book
         run: mdbook build
@@ -48,10 +37,28 @@ jobs:
       - name: Check links
         run: linkchecker book
 
-      - name: Deploy book
-        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
-        uses: peaceiris/actions-gh-pages@v3
+      - name: Build translations
+        # Expand the list of langauges in the for loop as needed.
+        # Update the language picker in theme/index.hbs when a
+        # language is complete enough to be found by users.
+        run: |
+          for po_lang in da; do
+              echo "::group::Building $po_lang translation"
+              MDBOOK_BOOK__LANGUAGE=$po_lang \
+              MDBOOK_OUTPUT__HTML__SITE_URL=/book/$po_lang/ \
+              mdbook build -d book/$po_lang
+              echo "::endgroup::"
+          done
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: book
-          force_orphan: true
+          path: book
+
+      - name: Deploy to GitHub Pages
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        id: deployment
+        uses: actions/deploy-pages@v1
@@ -1 +1,2 @@
 book
+po/messages.pot
@@ -4,5 +4,11 @@ multilingual = false
 src = "src"
 title = "The Embedded Rust Book"
 
+[build]
+extra-watch-dirs = ["po"]
+
+[preprocessor.gettext]
+after = ["links"]
+
 [output.html]
 git-repository-url = "https://github.com/rust-embedded/book"