From 9b18c8c6d0e713a67452fa8ab4d4f1b7716295d5 Mon Sep 17 00:00:00 2001
From: Ralf Zerres <ralf.zerres@mail.de>
Date: Thu, 17 Oct 2024 11:40:15 +0200
Subject: [PATCH] Internationalization support via mdbook-i18n-helper

* include links to the github sources
* prepare hint on howto create other language versions
---
 README.md                   | 68 +++++++++++++++++++++++--------------
 src/ch00-00-introduction.md |  2 +-
 src/lib.rs                  | 64 +++++++++++++++++++++-------------
 3 files changed, 83 insertions(+), 51 deletions(-)

diff --git a/README.md b/README.md
index e31ab29..488e6e1 100644
--- a/README.md
+++ b/README.md
@@ -2,10 +2,10 @@
 
 ![Welcome to the element-call book.][element_call_book]
 
-This repository contains the text source for `The Element-Call` book.
+This repository contains the text source for "The Element-Call" book.
 We will further reference to it as the `Element-Call Book`.
 
-[element_call_book]: https://gitea.networkx.de/rzerres/element-call-book/src/branch/main/src/img/element-call-1.png
+[element_call_book]: https://gitea.networkx.de/rzerres/element-call-book/src/branch/main/src/img/element-call-webui.png
 <!--
 	WIP: once it is ready to be shipped
 	[The book is available in dead-tree form from No Starch Press][nostarch].
@@ -46,22 +46,35 @@ some process flows.
 
 [crates.io]: https://crates.io/crates/cargo-readme
 
-##### Multilingual version of mdBook
-The `Element-Call` book aims to make translations as flawless as
-possible. We are using v0.4.12 that will do the job. There is a
-patch available that adds the needed salt to organize a book as a
-multilingual structure: All sources stored in a single hirachical
-code tree. This work isn't finished yet, but good enough to make
-use of this branch for our productive needs. Thank you [Nutomic
-and Ruin0x11][mdbook localization].
-
-You can force the installation of a given version number
-with:
+If you need a given version of `mdbook`, you may force it's
+installation the following call:
 
 ```rust
-console $ cargo install mdbook --vers 0.4.12 mdbook-linkchecker mdbook-mermaid
+console $ cargo install mdbook --vers 0.4.40 mdbook-linkchecker mdbook-mermaid
 ```
 
+##### Multilingual version of mdBook
+
+The `Element-Call` book aims to make translations as flawless as
+possible. With [`mdbook-i18n-helpers`][mdbook_i18n_helpers] you gain
+`Gettext Translation Support` with three extensions.
+
+```console
+$ cargo install mdbook-i18n-helpers
+```
+
+It will install three binaries:
+
+* mdbook-xgettext: This program extracts the source text. It is an mdbook renderer.
+* mdbook-gettext: This program translates the book into a target language.
+  It is an mdbook preprocessor.
+* mdbook-i18n-normalize: This program normalizs a PO file. Use it after breaking changes.
+
+Please have a look to the online documentation on howto actually use the Gettext subsystem.
+
+[mdbook_i18n_helpers]: https://github.com/google/mdbook-i18n-helpers?tab=readme-ov-file
+[mdbook_i18n_helpers_usage]: https://github.com/google/mdbook-i18n-helpers/blob/main/i18n-helpers/USAGE.md
+
 ##### Cargo handled README
 
 We do make uses of the crate [cargo-readme]. It resolves rust `doc
@@ -93,27 +106,27 @@ To build the book with the default language (here: 'en'), change
 into the root directory of the element-call submodule and type:
 
 ```console
-$ mdbook build --dest-dir book/en
+$ mdbook build --dest-dir book_en
 ```
 
 The rendered HTML output will be placed underneath the
-`book/en` subdirectory. To check it out, open it in your web
+`book_en` subdirectory. To check it out, open it in your web
 browser.
 
 _Firefox:_
 ```console
-$ firefox book/en/html/index.html                       # Linux
-$ open -a "Firefox" book/en/html/index.html             # OS X
-$ Start-Process "firefox.exe" .\book\en\html\index.html # Windows (PowerShell)
-$ start firefox.exe .\book\en\html\index.html           # Windows (Cmd)
+$ firefox book_en/html/index.html                       # Linux
+$ open -a "Firefox" book_en/html/index.html             # OS X
+$ Start-Process "firefox.exe" .\book_en\html\index.html # Windows (PowerShell)
+$ start firefox.exe .\book_en\html\index.html           # Windows (Cmd)
 ```
 
 _Chrome:_
 ```console
-$ google-chrome book/en/html/index.html                 # Linux
-$ open -a "Google Chrome" book/en/html/index.html       # OS X
-$ Start-Process "chrome.exe" .\book\en\html\index.html  # Windows (PowerShell)
-$ start chrome.exe .\book\en\html\index.html            # Windows (Cmd)
+$ google-chrome book_en/html/index.html                 # Linux
+$ open -a "Google Chrome" book_en/html/index.html       # OS X
+$ Start-Process "chrome.exe" .\book_en\html\index.html  # Windows (PowerShell)
+$ start chrome.exe .\book_en\html\index.html            # Windows (Cmd)
 ```
 
 Executing `mdbook serve` will have **mdbook** act has a web service
@@ -125,8 +138,10 @@ To run the tests:
 $ mdbook test
 ```
 
+<!--
 ##### Building a language variant of the book
 
+WIP: adapt to mdbook-i18n-helpers
 Translated version of the book will be placed inside the code tree
 in the subdirectory `src/<language id`.
 
@@ -134,11 +149,12 @@ E.g. if you like to render the german version (language id: 'de'), change
 into Element-Call books root directory and type:
 
 ```console
-$ MDBOOK_BOOK__src=src/de mdbook build --dest-dir book/de --open
+$ MDBOOK_BOOK__src=src_de mdbook build --dest-dir book_de --open
 ```
 
 The rendered HTML output will be placed underneath the
-`book/de` subdirectory. Since we appended the `--open` parameter, your default browser should be fired up and ... tada!
+`book_de` subdirectory. Since we appended the `--open` parameter, your default browser should be fired up and ... tada!
+!-->
 
 #### 🛠️ Development
 ==================
diff --git a/src/ch00-00-introduction.md b/src/ch00-00-introduction.md
index d806aad..7fedb0b 100644
--- a/src/ch00-00-introduction.md
+++ b/src/ch00-00-introduction.md
@@ -65,7 +65,7 @@ The intention of `Element-Call` book is to help interested developers and admini
 
 The source files of the book are maintained as a git submodule found at [`Element-Call book`][element_call_book].
 
-[element_call_book]: https://gitea.networkx.de/rzerres/element-call-book/book-en
+[element_call_book]: https://gitea.networkx.de/rzerres/element-call-book/book_en
 
 <!--
 [element-call_book_en_stable]: https://element.io/element-call/stable/book/
diff --git a/src/lib.rs b/src/lib.rs
index f4c1e8f..86d63eb 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -47,22 +47,35 @@
 //!
 //! [crates.io]: https://crates.io/crates/cargo-readme
 //!
-//! #### Multilingual version of mdBook
-//! The `Element-Call` book aims to make translations as flawless as
-//! possible. We are using v0.4.12 that will do the job. There is a
-//! patch available that adds the needed salt to organize a book as a
-//! multilingual structure: All sources stored in a single hirachical
-//! code tree. This work isn't finished yet, but good enough to make
-//! use of this branch for our productive needs. Thank you [Nutomic
-//! and Ruin0x11][mdbook localization].
-//!
-//! You can force the installation of a given version number
-//! with:
+//! If you need a given version of `mdbook`, you may force it's
+//! installation the following call:
 //!
 //! ```rust
-//! console $ cargo install mdbook --vers 0.4.12 mdbook-linkchecker mdbook-mermaid
+//! console $ cargo install mdbook --vers 0.4.40 mdbook-linkchecker mdbook-mermaid
 //! ```
 //!
+//! #### Multilingual version of mdBook
+//!
+//! The `Element-Call` book aims to make translations as flawless as
+//! possible. With [`mdbook-i18n-helpers`][mdbook_i18n_helpers] you gain
+//! `Gettext Translation Support` with three extensions.
+//!
+//! ```console
+//! $ cargo install mdbook-i18n-helpers
+//! ```
+//!
+//! It will install three binaries:
+//!
+//! * mdbook-xgettext: This program extracts the source text. It is an mdbook renderer.
+//! * mdbook-gettext: This program translates the book into a target language.
+//!   It is an mdbook preprocessor.
+//! * mdbook-i18n-normalize: This program normalizs a PO file. Use it after breaking changes.
+//!
+//! Please have a look to the online documentation on howto actually use the Gettext subsystem.
+//!
+//! [mdbook_i18n_helpers]: https://github.com/google/mdbook-i18n-helpers?tab=readme-ov-file
+//! [mdbook_i18n_helpers_usage]: https://github.com/google/mdbook-i18n-helpers/blob/main/i18n-helpers/USAGE.md
+//!
 //! #### Cargo handled README
 //!
 //! We do make uses of the crate [cargo-readme]. It resolves rust `doc
@@ -94,27 +107,27 @@
 //! into the root directory of the element-call submodule and type:
 //!
 //! ```console
-//! $ mdbook build --dest-dir book/en
+//! $ mdbook build --dest-dir book_en
 //! ```
 //!
 //! The rendered HTML output will be placed underneath the
-//! `book/en` subdirectory. To check it out, open it in your web
+//! `book_en` subdirectory. To check it out, open it in your web
 //! browser.
 //!
 //! _Firefox:_
 //! ```console
-//! $ firefox book/en/html/index.html                       # Linux
-//! $ open -a "Firefox" book/en/html/index.html             # OS X
-//! $ Start-Process "firefox.exe" .\book\en\html\index.html # Windows (PowerShell)
-//! $ start firefox.exe .\book\en\html\index.html           # Windows (Cmd)
+//! $ firefox book_en/html/index.html                       # Linux
+//! $ open -a "Firefox" book_en/html/index.html             # OS X
+//! $ Start-Process "firefox.exe" .\book_en\html\index.html # Windows (PowerShell)
+//! $ start firefox.exe .\book_en\html\index.html           # Windows (Cmd)
 //! ```
 //!
 //! _Chrome:_
 //! ```console
-//! $ google-chrome book/en/html/index.html                 # Linux
-//! $ open -a "Google Chrome" book/en/html/index.html       # OS X
-//! $ Start-Process "chrome.exe" .\book\en\html\index.html  # Windows (PowerShell)
-//! $ start chrome.exe .\book\en\html\index.html            # Windows (Cmd)
+//! $ google-chrome book_en/html/index.html                 # Linux
+//! $ open -a "Google Chrome" book_en/html/index.html       # OS X
+//! $ Start-Process "chrome.exe" .\book_en\html\index.html  # Windows (PowerShell)
+//! $ start chrome.exe .\book_en\html\index.html            # Windows (Cmd)
 //! ```
 //!
 //! Executing `mdbook serve` will have **mdbook** act has a web service
@@ -126,8 +139,10 @@
 //! $ mdbook test
 //! ```
 //!
+//! <!--
 //! #### Building a language variant of the book
 //!
+//! WIP: adapt to mdbook-i18n-helpers
 //! Translated version of the book will be placed inside the code tree
 //! in the subdirectory `src/<language id`.
 //!
@@ -135,11 +150,12 @@
 //! into Element-Call books root directory and type:
 //!
 //! ```console
-//! $ MDBOOK_BOOK__src=src/de mdbook build --dest-dir book/de --open
+//! $ MDBOOK_BOOK__src=src_de mdbook build --dest-dir book_de --open
 //! ```
 //!
 //! The rendered HTML output will be placed underneath the
-//! `book/de` subdirectory. Since we appended the `--open` parameter, your default browser should be fired up and ... tada!
+//! `book_de` subdirectory. Since we appended the `--open` parameter, your default browser should be fired up and ... tada!
+//! !-->
 //!
 //! ### 🛠️ Development
 //! ==================