rzerres/element-call-book
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Internationalization support via mdbook-i18n-helper

Browse Source 
* include links to the github sources
* prepare hint on howto create other language versions
This commit is contained in:
Ralf Zerres
2024-10-17 11:40:15 +02:00
parent 1d3c838aa0
commit 9b18c8c6d0
3 changed files with 83 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
README.md
View File

@@ -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
==================

2
src/ch00-00-introduction.md
View File

@@ -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/

64
src/lib.rs
View File

@@ -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
//! ==================