Translation
The mkdocs-static-i18n
plugin is setup based on suffix, with index.md
is the default English, and index.fr.md
used for French:
The mkdocs-material-theme language chooser is configured by this plugin allowing the selection of language at runtime.
Reference:
Deepl Translation
Translation uses pandoc to convert to html
for conversion by Deepl.
Specific pandoc extensions are used to match the capabilities of mkdocs:
markdown extension | pandoc extension |
---|---|
tables | pipe_tables |
pymdownx.keys | |
pymdownx.superfences | backtick_code_blocks |
admonition | fenced_divs |
The differences differences in markdown requires pre/post processing of markdown and html files. These steps are automated in the translate python script (check comments for details). Supporting additional mkdocs features requires updating this script.
- Install mkdocs_translate python script:
- To translate provide environmental variable with Deepl authentication key:
- And translate a file:
- To test each stage individually:
mkdocs_translate internal-html manual/docs/contributing/style-guide.md
mkdocs_translate internal-document target/contributing/style-guide.html target/contributing/style-guide.fr.html
mkdocs_translate internal-markdown target/contributing/style-guide.fr.html
cp target/contributing/style-guide.fr.md manual/docs/contributing/style-guide.fr.md
- To test markdown / html round trip: