zk-jargon-decoder icon indicating copy to clipboard operation
zk-jargon-decoder copied to clipboard

Add multi-language support using mdbook-i18n-helpers

Open Mameta29 opened this issue 1 year ago • 3 comments

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:

  1. Install mdbook-i18n-helpers: cargo install mdbook-i18n-helpers
  2. Generate POT file: MDBOOK_OUTPUT='{"xgettext": {}}' mdbook build -d po
  3. Create a PO file for a new language (e.g., Japanese): msginit -i po/messages.pot -l ja -o po/ja.po
  4. Add some translations to po/ja.po
  5. Build the Japanese version: MDBOOK_BOOK__LANGUAGE=ja mdbook build -d book/ja

Mameta29 avatar Aug 12 '24 03:08 Mameta29

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 .pot file 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 .po files 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?

nmohnblatt avatar Sep 03 '24 11:09 nmohnblatt

@Mameta29 thanks for making a pull request, are you happy to address the points raised by @nmohnblatt ?

darigovresearch avatar Sep 29 '24 10:09 darigovresearch

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

  1. Removing the .pot file and adding it to .gitignore: I will remove the po/messages.pot file and add po/messages.pot to the .gitignore file.

  2. 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.

  3. Build process for the full book with all translations: The current build process is:

    MDBOOK_BOOK__LANGUAGE=xx mdbook build -d book/xx
    

    This needs to be run for each language. I will create a script to build all languages at once.

  4. 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.

Mameta29 avatar Sep 30 '24 01:09 Mameta29

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!

nmohnblatt avatar Oct 06 '24 18:10 nmohnblatt

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.

Mameta29 avatar Oct 09 '24 09:10 Mameta29