Localization of mdBook Documentation

[hwhsu1231]

Hello, mdBook Community,

I’m glad to announce that the 🎉 mdbook-docs-l10n 🎉 project is published now:

• 🚀 Preview: mdbook-docs-l10n
• 🌐 Crowdin: mdbook-docs-l10n
• 🐙 GitHub: mdbook-docs-l10n

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

[hwhsu1231]

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

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

Those po/${VERSION} branches are created to facilitate usage by the upstream project. However, since mdbook@^0.5 and the currently latest mdbook-i18n-helpers@0.3.6 are incompatible. See the following issues for details:

• The v0.5.0-alpha.1 version of mdBook is incompatible with mdbook-i18n-helpers #2835
• mdbook-i18n-helpers@0.3.6 will be imcompatible with mdbook@0.5.0 google/mdbook-i18n-helpers#278

Therefore, here we will demonstrate how to build the translated documentation for version 0.4:

LANGUAGE=zh_TW
VERSION=0.4
TAG=v0.4.52

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

# Clone the .po files from the 'po/${VERSION}' branch
git clone --branch=po/${VERSION} --depth=1 \
    https://github.com/localizethedocs/mdbook-docs-l10n.git \
    guide/locale

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

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