Localization of Embedded Rust Book

[hwhsu1231]

Hello, Rust Community,

I’m glad to announce that the 🎉 rust-embedded-book-l10n 🎉 project is published now:

• 🚀 Preview: rust-embedded-book-l10n
• 🌐 Crowdin: rust-embedded-book-l10n
• 🐙 GitHub: rust-embedded-book-l10n

The goal of this project is to translate the Embedded Rust Book into multiple languages. Translations are contributed via the Crowdin platform, automatically synchronized with the GitHub repository, and can be previewed on GitHub Pages.

If translators want to translate a language that is not yet supported, they just need to open a new issue to request the new language. Once the requested language is added, they can begin translating.

There are some issues discussing about translating this book into multiple languages:

• I think this repository can support more languages #326
• Is there a procedure required to translate the repository into another language? #350

I believe this rust-embedded-book-l10n project can fulfill such needs.

[hwhsu1231]

Besides, if the upstream project or anyone wants to use the translated .po files prepared by the rust-embedded-book-l10n project, they can clone the .po files from the po/${VERSION} branch by using the following command:

git clone --depth=1 --branch=po/${VERSION} https://github.com/localizethedocs/rust-embedded-book-l10n.git locale

Those po/${VERSION} branches are created to facilitate usage by the upstream project. For instance, the zh_TW documentation for the master version can be generated using the commands below:

VERSION=master
LANGUAGE=zh_TW

# Prepare the repository and environment
git clone --branch=${VERSION} --depth=1 https://github.com/rust-embedded/book.git rust-embedded-book
cd rust-embedded-book
conda create --prefix ./.conda --yes
conda activate ./.conda
conda install conda-forge::rust=1.90 conda-forge::dasel=2 --channel conda-forge --yes
export CARGO_INSTALL_ROOT=$(pwd)/.conda
cargo install mdbook@^0.5 mdbook-i18n-helpers@^0.4

# Clone the .po files to the 'locale' directory
git clone --branch=po/${VERSION} --depth=1 https://github.com/localizethedocs/rust-embedded-book-l10n.git locale

# Build the documentation
export MDBOOK_BOOK__LANGUAGE=${LANGUAGE}
export MDBOOK_PREPROCESSOR='{
  "gettext":{
    "after":["links"],
    "po-dir":"locale"
  }
}'
mdbook build . --dest-dir book/${LANGUAGE}

# Preview the documentation
firefox book/${LANGUAGE}/index.html

[BartMassey]

Thanks much for this work! This is an exciting project.

Do be aware that the Embedded Book will probably have some major changes over the next year. Please don't let this slow the effort down, but you will probably end up doing some rework.

If you'd like to show up at the Rust Embedded Working Group meeting sometime soon to talk about this, we meet Tuesday evenings Berlin time on Matrix.

[hwhsu1231]

Hello, @BartMassey

Do be aware that the Embedded Book will probably have some major changes over the next year. Please don't let this slow the effort down, but you will probably end up doing some rework.

If the major changes you mentioned above are primarily related to the document content, then you don't have to worry about it. This is because the infrastructure (scripts + workflow) designed in @localizethedocs is specifically built to address the issue of outdated document content.

In the rust-embedded-book-l10n repository, the ci-mdbook-update-pot.yml workflow is executed weekly to check the upstream project for any required updates to the document content, which in turn triggers the update of the .pot files. If an update is needed, a Pull Request (PR) is automatically created to merge into the l10n branch. For example:

localizethedocs/rust-embedded-book-l10n#2

Therefore, the core responsibility of the code maintainer, besides ensuring the stable operation of the scripts and workflows, is to regularly check whether there are any pending PRs that need to be merged.