mirror of https://github.com/Desuuuu/klipper.git
docs: Mkdocs i18n support (#5072)
Signed-off-by: Yifei DIng <yifeiding@protonmail.com>
This commit is contained in:
parent
f0241d7dec
commit
61329049a6
|
@ -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
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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)
|
|
@ -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
|
||||||
|
|
|
@ -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:
|
||||||
|
|
|
@ -0,0 +1,5 @@
|
||||||
|
plugins:
|
||||||
|
i18n:
|
||||||
|
default_language: en
|
||||||
|
languages:
|
||||||
|
en: English
|
Loading…
Reference in New Issue