Customize mdbook for translations, add KO#23
Merged
Conversation
* Preliminary multilingual support mdBook does not natively support multilingual documentation. A common approach is to use a third-party library like mdbook-i18n-helper, which relies on a Gettext-based workflow to enable multilingual support. However, I believe such a complex system is unnecessary for our case. Therefore, this commit follows the approach suggested in the official mdBook documentation: overriding the 'index.hbs' template to add a button that redirects users to the corresponding documentation in another language, thus achieving basic multilingual support. This commit introduces the following three files under the theme directory: - 'index.hbs': Adds a redirect button for switching languages. - 'lang-toggle.css': Defines the styling for the button and the dropdown menu. - 'lang-toggle.js': Implements the main logic behind the button's behavior. As a result, two separate books need to be built. However, since mdBook’s 'book.toml' does not support multiple '[book]'' sections in a single configuration. This commit introduces a CMake script to build different language versions of the book and place them in their respective directories. It can be tested by command 'cmake -P build.cmake'. Due to mdBook's behavior, the 'src' field in 'book.toml' determines the root URL. Therefore, if the theme directory is placed above the src directory, mdBook will copy it relative to the 'src' path during the build, which will cause the theme folder to become unreachable. Since English is the primary language of this documentation, the default behavior supports running 'mdbook' command directly from the guide directory, such as with 'mdbook serve'. However, this will only generate the English version of the documentation, other languages will not be built. To build other language versions using the mdbook command directly, it must manually adjust their respective book.toml files. All translations are placed under 'guide/translations'. To add a new language, it need to follow the same folder structure, update the CMake script, and register the new language in 'theme/index.hbs'. [1]: https://github.com/google/mdbook-i18n-helpers * Stick to 'snake_case' for filenames * Stick to 'snake_case' for file reference
* Add build book job to CI * Test book build breakage * `execute_process()`: treat errors as fatal * Revert deliberate breakage
* ko-translate getting_started * ko-translate initialization.md * ko-translate rendering * ko-translate ImGui * ko-translate shader_objects * ko-translate memory * ko-translate descriptorSets * revise and summary * fix --------- Co-authored-by: Karn Kaul <karnkaul@gmail.com>
Member
Author
|
CC: @CDDing |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.