Add multi-language support using mdbook-i18n-helpers
This PR adds multi-language support to the project using mdbook-i18n-helpers. This lays the groundwork for creating translations of the documentation, starting with Japanese.
Changes implemented:
- Installed mdbook-i18n-helpers
- Updated book.toml to include gettext preprocessor
- Created initial PO template file
- Updated README with instructions for translators
To test:
- Install mdbook-i18n-helpers:
cargo install mdbook-i18n-helpers - Generate POT file:
MDBOOK_OUTPUT='{"xgettext": {}}' mdbook build -d po - Create a PO file for a new language (e.g., Japanese):
msginit -i po/messages.pot -l ja -o po/ja.po - Add some translations to po/ja.po
- Build the Japanese version:
MDBOOK_BOOK__LANGUAGE=ja mdbook build -d book/ja
Thank you for your contribution, amazing work! Looking forward to welcoming new languages to the ZK Jargon Decoder.
Before we merge this PR, can you please address the following fixes and questions:
- [fix] remove the
.potfile from the tracked files and add it to.gitignore(see the usage manual for mdbook-i18n-helpers, second paragraph of the "Creating and Updating Translations" section). - [fix] include a translation tip to tell translators to not edit
.pofiles by hand and use a PO Editor instead (see TRANSLATE.md in the comprehensive-rust repo) - [question] what is the build process to build the full book with all translations?
- [question] in the Comprehensive Rust book, there is a little globe icon at the top-right of each page to switch between languages. Is this something we can include in our support of multiple languages?
@Mameta29 thanks for making a pull request, are you happy to address the points raised by @nmohnblatt ?
@nmohnblatt @darigovresearch Thank you for your feedback and suggestions. I apologize for the delay in responding; I've been quite busy recently. I appreciate your patience. I will address your questions and requested modifications as follows:
-
Removing the
.potfile and adding it to.gitignore: I will remove thepo/messages.potfile and addpo/messages.potto the.gitignorefile. -
Adding a translation tip about using a PO editor: I will add a note in the "Translation Tips" section of the README.md file regarding the use of PO editors.
-
Build process for the full book with all translations: The current build process is:
MDBOOK_BOOK__LANGUAGE=xx mdbook build -d book/xxThis needs to be run for each language. I will create a script to build all languages at once.
-
Possibility of implementing a language switch icon: While mdbook-i18n-helpers doesn't provide this functionality directly, I will implement a custom JavaScript solution that:
- Generates a JSON file with available languages during each language version build.
- Creates a language switch dropdown using this JSON file.
- Redirects to the corresponding language version URL when a user selects a language.
Implementing these changes may take a few days, but I will keep you updated on the progress regularly. Thank you again for your valuable input. If you have any further questions or concerns, please let me know.
Wonderful, thank you for the update!
We can also put point 4 (language switch icon) into a separate open issue and merge this PR. This will hopefully allow you (and others!) to get started on translation in the meantime.
Let me know what you prefer!
Thank you for the suggestion, @nmohnblatt. I think that's an excellent way to proceed. Let's create a separate issue for implementing the language switch icon and move forward with merging this PR.