From 61329049a65fa2526e7b7039cd84bdbc7f9700c5 Mon Sep 17 00:00:00 2001 From: Yifei Ding Date: Mon, 14 Feb 2022 08:29:41 -0800 Subject: [PATCH] docs: Mkdocs i18n support (#5072) Signed-off-by: Yifei DIng --- .github/workflows/klipper3d-deploy.yaml | 4 ++++ docs/CONTRIBUTING.md | 28 +++++++++++------------ docs/_klipper3d/fetch-translations.sh | 30 +++++++++++++++++++++++++ docs/_klipper3d/mkdocs-requirements.txt | 1 + docs/_klipper3d/mkdocs.yml | 14 ++++++------ docs/_klipper3d/translations.yml | 5 +++++ 6 files changed, 60 insertions(+), 22 deletions(-) create mode 100755 docs/_klipper3d/fetch-translations.sh create mode 100644 docs/_klipper3d/translations.yml diff --git a/.github/workflows/klipper3d-deploy.yaml b/.github/workflows/klipper3d-deploy.yaml index 812931c7..0124317b 100644 --- a/.github/workflows/klipper3d-deploy.yaml +++ b/.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 diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index e36fc897..53addbff 100644 --- a/docs/CONTRIBUTING.md +++ b/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 - - : - - locales//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\` 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. diff --git a/docs/_klipper3d/fetch-translations.sh b/docs/_klipper3d/fetch-translations.sh new file mode 100755 index 00000000..79352f60 --- /dev/null +++ b/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 + +#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) diff --git a/docs/_klipper3d/mkdocs-requirements.txt b/docs/_klipper3d/mkdocs-requirements.txt index a7fcf1e9..425d583d 100644 --- a/docs/_klipper3d/mkdocs-requirements.txt +++ b/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 diff --git a/docs/_klipper3d/mkdocs.yml b/docs/_klipper3d/mkdocs.yml index b2ebfcd1..a47ddbc8 100644 --- a/docs/_klipper3d/mkdocs.yml +++ b/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: diff --git a/docs/_klipper3d/translations.yml b/docs/_klipper3d/translations.yml new file mode 100644 index 00000000..d70e3a78 --- /dev/null +++ b/docs/_klipper3d/translations.yml @@ -0,0 +1,5 @@ +plugins: + i18n: + default_language: en + languages: + en: English