Replace mdBook with Typst

[burrbull]

This is my answer to multi-language book.

We can keep translations in same file if use Typst instead. See typ/intro/index.typ for example.

This is a draft yet, but it is already looks and works very similar to mdBook version as it reuses original CSS and scripts.

How to compile:

English:

typst compile typ/book.typ --input lang=en --input target=html book --features bundle,html -f bundle
typst compile typ/book.typ --input lang=en --input target=pdf book/book_en.pdf

German:

typst compile typ/book.typ --input lang=de --input target=html book --features bundle,html -f bundle
typst compile typ/book.typ --input lang=de --input target=pdf book/book_de.pdf

Temporary published on:
https://burrbull.github.io/book/
Translations:
German: https://burrbull.github.io/book/de @braunharald
Chinese: https://burrbull.github.io/book/zh @XxChang
Japanese: https://burrbull.github.io/book/ja @tomoyuki-nakabayashi

See rendered PDF:
https://burrbull.github.io/book/book_en.pdf

Syntax:

Function tr takes 1 argument:

• Dictionary with translations.

Depending on compile option goal missing translation will be:

1. --input goal=publish : replaced with initial text (not available in other alternatives)
2. --input goal=translation : replaced with marker "not translated"

#tr((
en: [
  You can find this information in the data sheet or the reference manual
  of your device.
],
de: [
  Diese Informationen finden Sie im Datenblatt oder im Referenzhandbuch
  Ihres/Ihrer Microcontrollers/Microcontrollerplatine.
],
ja: [
  これらの情報は、デバイスのデータシートかリファレンスマニュアルに掲載されています。
],
zh: [
  你可以在你的设备的数据手册和参考手册上找到这些信息。
]))

[hwhsu1231]

Hello @burrbull,

Thank you for tagging me in this draft PR.

First of all, if you are asking for my opinion on this PR, I'm not entirely in favor of this change. Since you tagged me, I assume you've likely seen the rust-embedded-book-l10n project I announced in #401. Therefore, if rust-embedded/book migrates from mdBook to another documentation generator, this l10n project will no longer be able to function (unless the new tool also supports gettext-based internationalization).

Additionally, I noticed you mentioned the German translation in #415. If you are interested in translating The Embedded Rust Book, you are more than welcome to join the rust-embedded-book-l10n project! If German is not available yet, feel free to open an issue to request adding a new language. Once the requested language is added, you can start translating right away!

[burrbull]

CI caching does not work. What I did wrong?

All works as expected except one thing with sidebar in localized book.
Fixed.

P.S. It would be nice to add some html formatter in CI.

[burrbull]

Added German translation from #415. @braunharald please review.
cc @eldruin @therealprof

rust_embedded_book_en.pdf
rust_embedded_book_de.pdf

[braunharald]

I think I still have a bit of trouble understanding this. Should I just compare the two PDF files and let you know whether I think the implementation is good or bad? Or is there a branch on GitHub for the “typ” directory and its subdirectories so that I can put together a patch if necessary? If so, I'd appreciate the link. /Harald Am 04.08.26 um 17:43 schrieb Zgarbul Andrey:

*burrbull* left a comment (rust-embedded/book#416) <#416 (comment)> Added German translation from #415 <#415>. @braunharald <https://github.com/braunharald> please review. cc @eldruin <https://github.com/eldruin> @therealprof <https://github.com/therealprof> rust_embedded_book_en.pdf <https://github.com/user-attachments/files/30710500/rust_embedded_book_en.pdf> rust_embedded_book_de.pdf <https://github.com/user-attachments/files/30710506/rust_embedded_book_de.pdf> — Reply to this email directly, view it on GitHub <#416?email_source=notifications&email_token=ASFDTGBIKIYUYNF3EY6QDIT5IIABVA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMJYGEZTINBVGYZKM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5181344562>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ASFDTGGCGXITFVP74GNMCAT5IIABVAVCNFSNUABFKJSXA33TNF2G64TZHMYTINBSGE2TSMJXHNEXG43VMU5TKMBTHAYTCOJRG422C5QC>. Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/ASFDTGDC4MPREDLHQ557VEL5IIABVA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMJYGEZTINBVGYZKM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJKTGN5XXIZLSL5UW64Y> and Android <https://github.com/notifications/mobile/android/ASFDTGCH4ZKH43RRPXW3WW35IIABVA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMJYGEZTINBVGYZKM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLTGN5XXIZLSL5QW4ZDSN5UWI>. Download it today! You are receiving this because you were mentioned.Message ID: ***@***.***>

-- Mit freundlichem Gruß Harald Braun In der Aue 6 36282 Hauneck-Rotensee Tel.: +49 6621 7966123 ***@***.***

[burrbull]

I think I still have a bit of trouble understanding this.

There is example in first message how you could to compile the book locally.
But first you need to install typst with

cargo install typst-cli

In book and book/de directories will be generated html and pdf files.

The original text and translation were added manually.
So I'd want you to look over book and say what is wrong or missing. For example intro/install/index.md is missing in archive you've uploaded in #415.
It is easy to see in PDF. Feel free to make PR in https://github.com/burrbull/book/tree/typst
It is also interesting to know how hard to do it for another people.

P.S. My recommendations to use vs code:

1. Install typst extension.
2. Go to settings.json and change language in --input=lang.
3. Go to book-pdf.typ and press button to watch pdf preview in real time.

[braunharald]

Hello everyone, I've reviewed the German translation of the book. Attached is the patch for the remaining changes. /Harald Am 05.08.26 um 18:38 schrieb Zgarbul Andrey:

*burrbull* left a comment (rust-embedded/book#416) <#416 (comment)> I think I still have a bit of trouble understanding this. There is example in first message how you could to compile the book locally. But first you need to install |typst| with |cargo install typst-cli | In |book| and |book/de| directories will be generated |html| and |pdf| files. The original text and translation were added manually. So I'd want you to look over book and say what is wrong or missing. For example |intro/install/index.md| is missing in archive you've uploaded in #415 <#415>. It is easy to see in PDF. Feel free to make PR in https://github.com/burrbull/book/tree/typst It is also interesting to know how hard to do it for another people. — Reply to this email directly, view it on GitHub <#416?email_source=notifications&email_token=ASFDTGC4HQW46IOLHFTYDID5INPJJA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMJZGQ2TOMRYGAZKM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5194572802>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ASFDTGFMQI3W3BAE67DMZJD5INPJJAVCNFSNUABFKJSXA33TNF2G64TZHMYTINBSGE2TSMJXHNEXG43VMU5TKMBTHAYTCOJRG422C5QC>. Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/ASFDTGCECCLDAKDRDZSE3UT5INPJJA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMJZGQ2TOMRYGAZKM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJKTGN5XXIZLSL5UW64Y> and Android <https://github.com/notifications/mobile/android/ASFDTGA3N5WCYDTTGOYYA5L5INPJJA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMJZGQ2TOMRYGAZKM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLTGN5XXIZLSL5QW4ZDSN5UWI>. Download it today! You are receiving this because you were mentioned.Message ID: ***@***.***>

-- Mit freundlichem Gruß Harald Braun In der Aue 6 36282 Hauneck-Rotensee Tel.: +49 6621 7966123 ***@***.***

[burrbull]

typ/mdbook contents are now a library. So it can be published on Typst Universe for reusing in other similar projects.

[hwhsu1231]

Hello @burrbull,

About what you mentioned at the beginning:

We can keep translations in same file if use Typst instead. See typ/intro/index.typ for example.

First off, I honestly think this practice is a bad idea. In fact, Doxygen's current internationalization feature uses the exact approach proposed in this PR—specifically, using the \~[LanguageId] command to maintain translations for multiple languages within a single .c/.cpp/.dox file. For example:

/*! \~english This is English
    \~dutch Dit is Nederlands
    \~german Dies ist Deutsch.
    \~ output for all languages.
 */

However, after all these years, we rarely see any major C/C++ project actually leveraging this i18n feature to build multilingual Doxygen docs. This maintenance model is simply too difficult to sustain long-term—unless the project team happens to have a large number of native speakers for each specific language who are willing to continuously maintain the translations.

Honestly, even having translators from each language community create their own rust-embedded-book-xx repository to maintain translated copies of .typ files would be far more sustainable. That way, they would rarely run into PR merge conflicts that force them to re-push updates.

[braunharald]

Regarding the disadvantage described:

“Does not support multiple statements in the same branch (compared to the if-else syntax)”

Am I understanding this correctly?

Is the following not possible?

Start branch a

#(
en: [
You can find this information in the data sheet or the reference manual
of your device.
],
de: [
Diese Informationen finden Sie im Datenblatt oder im Referenzhandbuch
Ihres/Ihrer Microcontrollers/Microcontrollerplatine.
],
ja: [
これらの情報は、デバイスのデータシートかリファレンスマニュアルに掲載されています。
],
zh: [
你可以在你的设备的数据手册和参考手册上找到这些信息。
],
).at(lang, default: todo)

#(
en: [
WINDOWS: prerequisite C++ Build Tools for Visual Studio 2019 is installed. #ln_vs
],
de: [
WINDOWS: Voraussetzung ist, dass die C++-Build-Tools für Visual Studio 2019
installiert sind. #ln_vs
],
zh: [
WINDOWS: 需要预先安装 C++ Build Tools for Visual Studio 2019。#ln_vs
],
).at(lang, default: todo)

.
.
.

---

End of branch a

[burrbull]

Is the following not possible?

This is possible.
I meant other case where several languages should have same translation. With if - else you can join them in one branch if lang in ("en", "de") [Same text].
In dict you should duplicate them.

[braunharald]

Thank you for your explanation.

I think the alternative syntax is
a) Easy to understand
b) Shorter and therefore faster to write
c) The drawback of having to provide the same content for each language in translations that are identical in some or all languages is acceptable, since this is likely to occur only in a few cases.

I would prefer the alternative syntax.

[burrbull]

@braunharald Added yet one in first message, I think a final syntax. Your thoughts?

[burrbull]

@XxChang @tomoyuki-nakabayashi Are you interested in updating your translations?
Look for red "not translated" text in these versions of book:
https://burrbull.github.io/book/book_zh_tr.pdf
https://burrbull.github.io/book/book_ja_tr.pdf