Preliminary support multilingual

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.

You can test this using command 'cmake -P build.cmake'. If you want to
use 'mdbook serve', you can test it by adding the '-DSERVE=ON' flag.
This will build all the languages listed in the build script and copy
them into the directory generated by mdbook serve.

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

Author: Mes0903

.github/workflows/deploy.yml

@@ -24,7 +24,7 @@ jobs:
       - name: build book
         run: |
           cd guide
-          mdbook build
+          cmake -P build.cmake
           ls book
       - name: setup pages
         uses: actions/configure-pages@v4

guide/.gitignore

@@ -1 +1,2 @@
 book
+build/*

guide/book.toml

@@ -1,6 +1,10 @@
 [book]
 authors = ["Karn Kaul"]
 language = "en"
-multilingual = false
 src = "src"
 title = "Learn Vulkan"
+
+[output.html]
+theme = "theme"
+additional-js = ["theme/lang-toggle.js"]
+additional-css = ["theme/lang-toggle.css"]

guide/build.cmake

@@ -0,0 +1,70 @@
+# Build the target languages
+function(BuildBook LANGUAGE SOURCE_DIR TARGET_DIR)
+  set(LANGUAGE "${LANGUAGE}")
+
+  if(NOT EXISTS "${SOURCE_DIR}/src/SUMMARY.md")
+    message(WARNING "Skipping '${LANGUAGE}' – SUMMARY.md not found at ${SOURCE_DIR}")
+    return()
+  endif()
+  
+  if(NOT EXISTS "${SOURCE_DIR}/book.toml")
+    message(WARNING "Skipping '${LANGUAGE}' – book.toml not found at ${SOURCE_DIR}")
+    return()
+  endif()
+
+  message(STATUS "Building book for language: ${LANGUAGE}")
+  execute_process(
+    COMMAND mdbook build -d ${TARGET_DIR}
+    WORKING_DIRECTORY ${SOURCE_DIR}
+  )
+endfunction()
+
+# Check if the translations theme folder exists
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/translations/theme")
+  message(STATUS "Translations theme folder found.")
+else()
+  message(WARNING "Translations theme folder not found. Copy it from the guide folder.")
+  file(COPY "${CMAKE_CURRENT_SOURCE_DIR}/theme" DESTINATION "${CMAKE_CURRENT_SOURCE_DIR}/translations")
+endif()
+
+# For 'mdbook serve' usage
+if(NOT DEFINED SERVE)
+  set(SERVE OFF)
+endif()
+
+if(SERVE)
+  # Dont need to build Enslish version, it would be built when running 'mdbook serve'
+  BuildBook("zh-TW" "${CMAKE_CURRENT_SOURCE_DIR}/translations/zh-TW" "${CMAKE_CURRENT_SOURCE_DIR}/.tmp-output/zh-TW") # would copy these translation to the book folder later
+
+  message(STATUS "Running 'mdbook serve'")
+  if(WIN32)
+    execute_process(
+      COMMAND powershell -Command "Start-Process mdbook -ArgumentList 'serve','-d','${CMAKE_CURRENT_SOURCE_DIR}/book'"
+      WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+    )
+  else()
+    execute_process(
+      COMMAND bash -c "mdbook serve -d \"${CMAKE_CURRENT_SOURCE_DIR}/book\" &"
+      WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+    )  
+  endif()
+
+  # Move the zh-TW output folder into book/
+  message(STATUS "Moving the translation folder to final location...")
+  execute_process(COMMAND ${CMAKE_COMMAND} -E sleep 2)
+
+  # Move the translation folder to the book folder
+  file(MAKE_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/book")
+  file(RENAME
+    "${CMAKE_CURRENT_SOURCE_DIR}/.tmp-output/zh-TW"
+    "${CMAKE_CURRENT_SOURCE_DIR}/book/zh-TW"
+  )
+
+  # Remove the temporary output folder
+  message(STATUS "Removed temporary folder: .tmp-output")
+  file(REMOVE_RECURSE "${CMAKE_CURRENT_SOURCE_DIR}/.tmp-output")
+else()
+  # Only Build the target languages for `mdbook build` usage
+  BuildBook("en" "${CMAKE_CURRENT_SOURCE_DIR}" "${CMAKE_CURRENT_SOURCE_DIR}/book")
+  BuildBook("zh-TW" "${CMAKE_CURRENT_SOURCE_DIR}/translations/zh-TW" "${CMAKE_CURRENT_SOURCE_DIR}/book/zh-TW")
+endif()