OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Added documentation for language configuration

Browse Source
This commit is contained in:
squidfunk 2017-10-19 21:01:57 +02:00 committed by Martin Donath
parent 9f513d6411
commit 0ab84b02ed
8 changed files with 78 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG
View File

@ -1,5 +1,7 @@
master master
* Added support for setting language(s) via mkdocs.yml
* Added support for default localization and German translations
* Fixed #374: Search bar misalignment on big screens * Fixed #374: Search bar misalignment on big screens
mkdocs-material-1.11.0 (2017-10-19) mkdocs-material-1.11.0 (2017-10-19)

126
docs/getting-started.md
View File

@ -378,66 +378,54 @@ automatically included.
#### Translations #### Translations
Material for MkDocs supports internationalization (i18n). In order to translate Material for MkDocs supports internationalization (i18n) and provides
the labels (e.g. *Previous* and *Next* in the footer), you can override the translations for all template variables and labels in English `en` and German
file `partials/language.html` and provide your own translations inside the `de`. Specify the language with:
macro `t`:
``` jinja ``` yaml
{% macro t(key) %}{{ { extra:
"language": "en", language: 'en'
"clipboard.copy": "Copy to clipboard",
"clipboard.copied": "Copied to clipboard",
"edit.link.title": "Edit this page",
"footer.previous": "Previous",
"footer.next": "Next",
"meta.comments": "Comments",
"meta.source": "Source",
"search.languages": "",
"search.placeholder": "Search",
"search.result.placeholder": "Type to start searching",
"search.result.none": "No matching documents",
"search.result.one": "1 matching document",
"search.result.other": "# matching documents",
"search.tokenizer": "[\s\-]+",
"source.link.title": "Go to repository",
"toc.title": "Table of contents"
}[key] }}{% endmacro %}
``` ```
Just copy the file from the original theme and make your adjustments. See the If the language is not specified, Material falls back to English. To create a
section on [overriding partials][19] and the general guide on translation for another language, copy the localization file of an existing
[theme extension][20] in the customization guide. Furthermore, see the language, name the new file using the [2-letter language code][19] and adjust
[example configuration][21] for a head start. all translations:
[19]: customization.md#overriding-partials ``` sh
[20]: customization.md#extending-the-theme cp partials/language/en.html partials/language/jp.html
[21]: https://github.com/squidfunk/mkdocs-material/tree/master/examples/language ```
Feel free to contribute your localization to Material for MkDocs by opening a
Pull Request.
[19]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
#### Site search #### Site search
Site search is implemented using [lunr.js][22], which includes stemmers for the Site search is implemented using [lunr.js][20], which includes stemmers for the
English language by default, while stemmers for other languages are included English language by default, while stemmers for other languages are included
with [lunr-languages][23], both of which are integrated with this theme. Support with [lunr-languages][21], both of which are integrated with this theme. Support
for other languages and even multilingual search can be activated by setting for other languages and even multilingual search can be activated in your
the key `search.languages` to a comma-separated list of supported 2-letter project's `mkdocs.yml`:
language codes, e.g.:
``` jinja ``` yaml
{% macro t(key) %}{{ { extra:
... language:
"search.languages": "en, de, ru", - 'en'
... - 'de'
}[key] }}{% endmacro %} - 'ru'
``` ```
This will automatically load the stemmers for the specified languages and The first language specified is used as the document language as described in
set them up with site search, nothing else to be done. the section above. All other languages are used only for stemming. This will
automatically load the stemmers for the specified languages and set them up
with site search.
At the time of writing, the following languages are supported: English `en`, At the time of writing, the following languages are supported: English `en`,
French `fr`, Spanish `es`, Italian `it`, Japanese `jp`, Dutch `du`, Danish `da`, French `fr`, German `de`, Spanish `es`, Italian `it`, Japanese `jp`, Dutch `du`,
Portguese `pt`, Finnish `fi`, Romanian `ro`, Hungarian `hu`, Russian `ru`, Danish `da`, Portguese `pt`, Finnish `fi`, Romanian `ro`, Hungarian `hu`,
Norwegian `no`, Swedish `sv` and Turkish `tr`. Russian `ru`, Norwegian `no`, Swedish `sv` and Turkish `tr`.
!!! warning "Only specify the languages you really need" !!! warning "Only specify the languages you really need"
@ -445,19 +433,20 @@ Norwegian `no`, Swedish `sv` and Turkish `tr`.
JavaScript payload by around 20kb (without gzip) and by another 15-30kb per JavaScript payload by around 20kb (without gzip) and by another 15-30kb per
language. language.
The separator for tokenization can also be customized, which makes it possible The separator for tokenization can be customized which makes it possible
to index parts of words that are separated by `-` or `.` for example: to index parts of words that are separated by `-` or `.`. This can be done by
overriding `partials/language.html`:
``` jinja ``` jinja
{% macro t(key) %}{{ { {% macro t(key) %}{{ {
... ...
"search.tokenizer": "[\s\-\.]+", "search.tokenizer": "[\s\-\.]+",
... ...
}[key] }}{% endmacro %} }[key] or lang.t(key) }}{% endmacro %}
``` ```
[22]: https://lunrjs.com [20]: https://lunrjs.com
[23]: https://github.com/MihaiValentin/lunr-languages [21]: https://github.com/MihaiValentin/lunr-languages
### Tabs ### Tabs
@ -475,13 +464,13 @@ extra:
### More advanced customization ### More advanced customization
If you want to change the general appearance of the Material theme, see If you want to change the general appearance of the Material theme, see
[this article][24] for more information on advanced customization. [this article][22] for more information on advanced customization.
[24]: customization.md [22]: customization.md
## Extensions ## Extensions
MkDocs supports several [Markdown extensions][25]. The following extensions MkDocs supports several [Markdown extensions][23]. The following extensions
are not enabled by default (see the link for which are enabled by default) are not enabled by default (see the link for which are enabled by default)
but highly recommended, so they should be switched on at all times: but highly recommended, so they should be switched on at all times:
@ -497,20 +486,20 @@ markdown_extensions:
For more information, see the following list of extensions supported by the For more information, see the following list of extensions supported by the
Material theme including more information regarding installation and usage: Material theme including more information regarding installation and usage:
* [Admonition][26] * [Admonition][24]
* [Codehilite][27] * [Codehilite][25]
* [Footnotes][28] * [Footnotes][26]
* [Metadata][29] * [Metadata][27]
* [Permalinks][30] * [Permalinks][28]
* [PyMdown Extensions][31] * [PyMdown Extensions][29]
[25]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions [23]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
[26]: extensions/admonition.md [24]: extensions/admonition.md
[27]: extensions/codehilite.md [25]: extensions/codehilite.md
[28]: extensions/footnotes.md [26]: extensions/footnotes.md
[29]: extensions/metadata.md [27]: extensions/metadata.md
[30]: extensions/permalinks.md [28]: extensions/permalinks.md
[31]: extensions/pymdown.md [29]: extensions/pymdown.md
## Full example ## Full example
@ -535,6 +524,7 @@ theme: 'material'
# Options # Options
extra: extra:
language: 'en'
logo: 'images/logo.svg' logo: 'images/logo.svg'
palette: palette:
primary: 'indigo' primary: 'indigo'

11
material/partials/language.html
View File

@ -1,3 +1,8 @@
{% set code = config.extra.language | default("en") %} {% set languages = config.extra.language | default("en") %}
{% import "partials/language/" + code + ".html" as lang %} {% if languages is string %}
{% macro t(key) %}{{ lang.t(key) }}{% endmacro %} {% set languages = languages.split(",") | map("trim") %}
{% endif %}
{% import "partials/language/" + (languages | first) + ".html" as lang %}
{% macro t(key) %}{{ {
"search.languages": languages | join(", ")
}[key] or lang.t(key) }}{% endmacro %}

1
material/partials/language/de.html
View File

@ -7,7 +7,6 @@
"footer.next": "Nächste Seite", "footer.next": "Nächste Seite",
"meta.comments": "Kommentare", "meta.comments": "Kommentare",
"meta.source": "Quellcode", "meta.source": "Quellcode",
"search.languages": "de",
"search.placeholder": "Suche", "search.placeholder": "Suche",
"search.result.placeholder": "Suchbegriff eingeben", "search.result.placeholder": "Suchbegriff eingeben",
"search.result.none": "Keine Suchergebnisse", "search.result.none": "Keine Suchergebnisse",

1
material/partials/language/en.html
View File

@ -7,7 +7,6 @@
"footer.next": "Next", "footer.next": "Next",
"meta.comments": "Comments", "meta.comments": "Comments",
"meta.source": "Source", "meta.source": "Source",
"search.languages": "",
"search.placeholder": "Search", "search.placeholder": "Search",
"search.result.placeholder": "Type to start searching", "search.result.placeholder": "Type to start searching",
"search.result.none": "No matching documents", "search.result.none": "No matching documents",

13
src/partials/language.html
View File

@ -20,9 +20,16 @@
IN THE SOFTWARE. IN THE SOFTWARE.
--> -->
<!-- Normalize language configuration -->
{% set languages = config.extra.language | default("en") %}
{% if languages is string %}
{% set languages = languages.split(",") | map("trim") %}
{% endif %}
<!-- Import translations for given language --> <!-- Import translations for given language -->
{% set code = config.extra.language | default("en") %} {% import "partials/language/" + (languages | first) + ".html" as lang %}
{% import "partials/language/" + code + ".html" as lang %}
<!-- Re-export translations --> <!-- Re-export translations -->
{% macro t(key) %}{{ lang.t(key) }}{% endmacro %} {% macro t(key) %}{{ {
"search.languages": languages | join(", ")
}[key] or lang.t(key) }}{% endmacro %}

1
src/partials/language/de.html
View File

@ -30,7 +30,6 @@
"footer.next": "Nächste Seite", "footer.next": "Nächste Seite",
"meta.comments": "Kommentare", "meta.comments": "Kommentare",
"meta.source": "Quellcode", "meta.source": "Quellcode",
"search.languages": "de",
"search.placeholder": "Suche", "search.placeholder": "Suche",
"search.result.placeholder": "Suchbegriff eingeben", "search.result.placeholder": "Suchbegriff eingeben",
"search.result.none": "Keine Suchergebnisse", "search.result.none": "Keine Suchergebnisse",

1
src/partials/language/en.html
View File

@ -30,7 +30,6 @@
"footer.next": "Next", "footer.next": "Next",
"meta.comments": "Comments", "meta.comments": "Comments",
"meta.source": "Source", "meta.source": "Source",
"search.languages": "",
"search.placeholder": "Search", "search.placeholder": "Search",
"search.result.placeholder": "Type to start searching", "search.result.placeholder": "Type to start searching",
"search.result.none": "No matching documents", "search.result.none": "No matching documents",