docs: Mkdocs i18n support (#5072)

Signed-off-by: Yifei DIng <yifeiding@protonmail.com>

.github/workflows/klipper3d-deploy.yaml

@@ -7,6 +7,8 @@ on:
       - docs/**
       - mkdocs.yml
       - .github/workflows/klipper3d-deploy.yaml
+  schedule:
+    - cron: "0 0 * * *"
 jobs:
   deploy:
     runs-on: ubuntu-latest
@@ -24,6 +26,8 @@ jobs:
             ${{ runner.os }}-pip-
       - name: Install dependencies
         run: pip install -r docs/_klipper3d/mkdocs-requirements.txt
+      - name: Fetch translations
+        run: docs/_klipper3d/fetch-translations.sh
       - name: Build and deploy klipper3d
         run: |
           mkdocs gh-deploy --config-file docs/_klipper3d/mkdocs.yml --remote-branch gh-pages --force --verbose

docs/CONTRIBUTING.md

@@ -301,15 +301,13 @@ contributions) and contain a current email address.
 [Klipper-translations Project](https://github.com/Klipper3d/klipper-translations)
 is a project dedicated to translating Klipper to different languages.
 [Weblate](https://hosted.weblate.org/projects/klipper/) hosts all the
-Gettext strings for translating and reviewing. Locales can merge into
-the Klipper project once they satisfy the following requirements:
+Gettext strings for translating and reviewing. Locales can be displayed on
+[klipper3d.org](https://www.klipper3d.org) once they satisfy the following requirements:
 
 - [ ] 75% Total coverage
-- [ ] All titles (H1) are covered
+- [ ] All titles (H1) are translated
 - [ ] An updated navigation hierarchy PR in klipper-translations.
 
-The navigation hierarchy is in `docs\_klipper3d\mkdocs.yml`.
-
 To reduce the frustration of translating domain-specific terms and
 gain awareness of the ongoing translations, you can submit a PR
 modifying the
@@ -321,15 +319,15 @@ If a translation already exists in the Klipper repository and no
 longer meets the checklist above, it will be marked out-of-date after
 a month without updates.
 
-Please follow the following format for `mkdocs.yml` navigation
-hierarchy:
+Once the requirements are met, you need to:
 
-```yml
-nav:
-  - existing hierachy
-  - <language>:
-    - locales/<language code>/md file
-```
+1. update klipper-tranlations repository
+[active_translations](https://github.com/Klipper3d/klipper-translations/blob/translations/active_translations)
+2. Optional: add a manual-index.md file in klipper-translations repository's
+`docs\locals\<lang>` folder to replace the language specific index.md (generated
+index.md does not render correctly).
 
-Note: Currently, there isn't a method for correctly translating
-pictures in the documentation.
+Known Issues:
+1. Currently, there isn't a method for correctly translating pictures in
+the documentation
+2. It is impossible to translate titles in mkdocs.yml.

docs/_klipper3d/fetch-translations.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Modify the file structure before running mkdocs
+# This is a make shift script before the current structure of
+# Klipper-translations can be directly utilized by mkdocs
+# Usage: pre-mkdocs.sh <lang_directory_name> <target_lang_name>
+
+#git clone --depth 1 https://github.com/Klipper3d/klipper-translations
+
+while IFS="," read dirname langname langdesc note; do
+  # move and rename markdown files
+  local_dir="klipper-translations/docs/locales/$dirname"
+  echo "Moving $dirname to $langname"
+  for file in "$local_dir"/*.md; do
+    mdfilename="${file/$local_dir\//}"
+    mv "$file" "./docs/${mdfilename//.md/.${langname}.md}"
+  done
+
+  # manually replace index.md if a manual-index.md exist
+  manual_index="./docs/manual-index.$langname.md"
+
+  if [[ -f "$manual_index" ]];then
+    mv "$manual_index" "./docs/index.${langname}.md"
+    echo "replaced index.${langname}.md with $manual_index"
+  else
+      echo "Manually translated index file for $dirname not found!"
+  fi
+
+  # add to translations.yml
+  echo "      ${langname}: ${langdesc}" >> ./docs/_klipper3d/translations.yml
+done <  <(egrep -v '^ *(#|$)' ./klipper-translations/active_translations | tail -n +2)

docs/_klipper3d/mkdocs-requirements.txt

@@ -6,3 +6,4 @@ mkdocs-exclude==1.0.2
 mdx-truly-sane-lists==1.2
 mdx-breakless-lists==1.0.1
 py-gfm==1.0.2
+mkdocs-static-i18n=0.30

docs/_klipper3d/mkdocs.yml

@@ -8,6 +8,7 @@ edit_uri: blob/master/docs/
 use_directory_urls: False
 docs_dir: '../'
 site_dir: '../../site/'
+INHERIT: translations.yml
 
 # Markdown document translation settings
 markdown_extensions:
@@ -19,13 +20,12 @@ markdown_extensions:
   - mdx_truly_sane_lists
   - mdx_breakless_lists
 plugins:
-  - search
-  - mkdocs-simple-hooks:
-      hooks:
-        on_page_markdown: "docs._klipper3d.mkdocs_hooks:transform"
-  - exclude:
-      glob:
-        - README.md
+  search: {}
+  mkdocs-simple-hooks:
+    hooks:
+      on_page_markdown: "docs._klipper3d.mkdocs_hooks:transform"
+  exclude:
+    glob: "README.md"
 
 # Website layout configuration (using mkdocs-material theme)
 theme:

docs/_klipper3d/translations.yml

@@ -0,0 +1,5 @@
+plugins:
+  i18n:
+    default_language: en
+    languages:
+      en: English