Add support for translations

.github/workflows/build.yml

@@ -39,3 +39,87 @@ jobs:
 
       - name: Test Rust code
         run: cargo test
+
+      - name: Test i18n-helpers
+        run: cargo test
+        working-directory: i18n-helpers
+
+  i18n-helpers:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup Rust cache
+        uses: Swatinem/rust-cache@v2
+
+      - name: Install Gettext
+        run: sudo apt install gettext
+
+      - name: Install mdbook
+        run: cargo install mdbook --version 0.4.25
+
+      - name: Install mdbook-svgbob
+        run: cargo install mdbook-svgbob --version 0.2.1
+
+      - name: Install i18n-helpers
+        run: cargo install --path i18n-helpers --locked
+
+      - name: Generate po/messages.pot
+        run: mdbook build -d po
+        env:
+          MDBOOK_OUTPUT: '{"xgettext": {"pot-file": "messages.pot"}}'
+
+      - name: Test messages.pot
+        run: msgfmt --statistics -o /dev/null po/messages.pot
+
+      - name: Expand includes without translation
+        run: mdbook build -d expanded
+        env:
+          MDBOOK_OUTPUT: '{"markdown": {}}'
+
+      - name: Expand includes with no-op translation
+        run: mdbook build -d no-op
+        env:
+          MDBOOK_OUTPUT: '{"markdown": {}}'
+          MDBOOK_PREPROCESSOR__GETTEXT__PO_FILE: po/messages.pot
+
+      - name: Compare no translation to no-op translation
+        run: diff -r expanded no-op
+
+  translations:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        language:
+          - da
+    env:
+      MDBOOK_BOOK__LANGUAGE: ${{ matrix.language }}
+      MDBOOK_PREPROCESSOR__GETTEXT__PO_FILE: po/${{ matrix.language }}.po
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup Rust cache
+        uses: Swatinem/rust-cache@v2
+
+      - name: Install Gettext
+        run: sudo apt install gettext
+
+      - name: Install mdbook
+        run: cargo install mdbook --version 0.4.25
+
+      - name: Install mdbook-svgbob
+        run: cargo install mdbook-svgbob --version 0.2.1
+
+      - name: Install i18n-helpers
+        run: cargo install --path i18n-helpers --locked
+
+      - name: Test ${{ matrix.language }} translation
+        run: msgfmt --statistics -o /dev/null po/${{ matrix.language }}.po
+
+      - name: Build course with ${{ matrix.language }} translation
+        run: mdbook build
+
+      - name: Test code snippets with ${{ matrix.language }} translation
+        run: mdbook test

.gitignore

@@ -1,2 +1,3 @@
 /book/
-/target/
+target/
+po/messages.pot

TRANSLATIONS.md

@@ -0,0 +1,116 @@
+# Translations of Comprehensive Rust 🦀
+
+We would love to have your help with translating the course into other
+languages! We use the [Gettext] system for translations. This means that you
+don't modify the Markdown files directly: instead you modify `.po` files in a
+`po/` directory. The `.po` files are small text-based translation databases.
+
+There is a `.po` file for each language. They are named after the [ISO 639]
+language codes: Danish would go into `po/da.po`, Korean would go into
+`po/ko.po`, etc. The `.po` files contain all the English text plus the
+translations. They are initialized from a `messages.pot` file (a PO template)
+which contains only the English text.
+
+We will show how to update and manipulate the `.po` and `.pot` files using the
+GNU Gettext utilities below.
+
+[Gettext]: https://www.gnu.org/software/gettext/manual/html_node/index.html
+[ISO 639]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
+
+## I18n Helpers
+
+We use two helpers for the translations:
+
+* `mdbook-xgettext`: This program extracts the English text. It is an mdbook
+  renderer.
+* `mdbook-gettext`: This program translates the book into a target language. It
+  is an mdbook preprocessor.
+
+Install both helpers with the following command from the root of the course:
+
+```shell
+$ cargo install --path i18n-helpers
+```
+
+## Creating and Updating Translations
+
+First, you need to know how to update the `.pot` and `.po` files.
+
+As a general rule, you should never touch the auto-generated `po/messages.pot`
+file. You should also not edit the `msgid` entries in a `po/xx.po` file. If you
+find mistakes, you need to update the original English text instead. The fixes
+to the English text will flow into the `.po` files the next time the translators
+update them.
+
+### Generating the PO Template
+
+To extract the original English text and generate a `messages.pot` file, you run
+`mdbook` with a special renderer:
+
+```shell
+$ MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot"}}' \
+  mdbook build -d po
+```
+
+You will find the generated POT file as `po/messages.pot`.
+
+### Initialize a New Translation
+
+To start a new translation, first generate the `po/messages.pot` file. Then use
+`msginit` to create a `xx.po` file for the fictional `xx` language:
+
+```shell
+$ msginit -i po/messages.pot -l xx -o po/xx.po
+```
+
+You can also simply copy `po/messages.pot` to `po/xx.po`. Then update the file
+header (the first entry with `msgid ""`) to the correct language.
+
+### Updating an Existing Translation
+
+As the English text changes, translations gradually become outdated. To update
+the `po/xx.po` file with new messages, first extract the English text into a
+`po/messages.pot` template file. Then run
+
+```shell
+$ msgmerge --update po/xx.po po/messages.pot
+```
+
+Unchanged messages will stay intact, deleted messages are marked as old, and
+updated messages are marked "fuzzy". A fuzzy entry will reuse the previous
+translation: you should then go over it and update it as necessary before you
+remove the fuzzy marker.
+
+## Using Translations
+
+This will show you how to use the translations to generate localized HTML
+output.
+
+## Building a Translation
+
+To use the `po/xx.po` file for your output, run the following command:
+
+```shell
+$ MDBOOK_BOOK__LANGUAGE='xx' \
+  MDBOOK_PREPROCESSOR__GETTEXT__PO_FILE='po/xx.po' \
+  MDBOOK_PREPROCESSOR__GETTEXT__RENDERERS='["html"]' \
+  MDBOOK_PREPROCESSOR__GETTEXT__BEFORE='["svgbob"]' \
+  mdbook build -d book/xx
+```
+
+This will update the book's language to `xx`, it will make the `mdbook-gettext`
+preprocessor become active and tell it to use the `po/xx.po` file, and finally
+it will redirect the output to `book/xx`.
+
+## Serving a Translation
+
+Like normal, you can use `mdbook serve` to view your translation as you work on
+it. You use the same command as with `mdbook build` above, but additionally
+we'll tell `mdbook` to watch the `po/` directory for changes:
+
+```shell
+$ MDBOOK_BOOK__LANGUAGE=xx \
+  MDBOOK_PREPROCESSOR__GETTEXT__PO_FILE=po/xx.po
+  MDBOOK_BUILD__EXTRA_WATCH_DIRS='["po"]'
+  mdbook serve -d book/xx
+```

book.toml

@@ -8,7 +8,14 @@ title = "Comprehensive Rust 🦀"
 [rust]
 edition = "2021"
 
+[preprocessor.links]
+renderers = ["html"]
+
+[preprocessor.index]
+renderers = ["html"]
+
 [preprocessor.svgbob]
+renderers = ["html"]
 class = "bob"
 
 [output.html]