docs: Mkdocs i18n support (#5072)

Signed-off-by: Yifei DIng <yifeiding@protonmail.com>
This commit is contained in:
Yifei Ding 2022-02-14 08:29:41 -08:00 committed by GitHub
parent f0241d7dec
commit 61329049a6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 60 additions and 22 deletions

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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