From 0ab84b02ed3c3acbfb8dcbff11e1c9d2f361cd3a Mon Sep 17 00:00:00 2001 From: squidfunk Date: Thu, 19 Oct 2017 21:01:57 +0200 Subject: [PATCH] Added documentation for language configuration --- CHANGELOG | 2 + docs/getting-started.md | 126 +++++++++++++---------------- material/partials/language.html | 11 ++- material/partials/language/de.html | 1 - material/partials/language/en.html | 1 - src/partials/language.html | 13 ++- src/partials/language/de.html | 1 - src/partials/language/en.html | 1 - 8 files changed, 78 insertions(+), 78 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index 98d7ec1a1..5dec18cf7 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,5 +1,7 @@ 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 mkdocs-material-1.11.0 (2017-10-19) diff --git a/docs/getting-started.md b/docs/getting-started.md index 8426dfdf7..f29b07255 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -378,66 +378,54 @@ automatically included. #### Translations -Material for MkDocs supports internationalization (i18n). In order to translate -the labels (e.g. *Previous* and *Next* in the footer), you can override the -file `partials/language.html` and provide your own translations inside the -macro `t`: +Material for MkDocs supports internationalization (i18n) and provides +translations for all template variables and labels in English `en` and German +`de`. Specify the language with: -``` jinja -{% macro t(key) %}{{ { - "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 %} +``` yaml +extra: + language: 'en' ``` -Just copy the file from the original theme and make your adjustments. See the -section on [overriding partials][19] and the general guide on -[theme extension][20] in the customization guide. Furthermore, see the -[example configuration][21] for a head start. +If the language is not specified, Material falls back to English. To create a +translation for another language, copy the localization file of an existing +language, name the new file using the [2-letter language code][19] and adjust +all translations: - [19]: customization.md#overriding-partials - [20]: customization.md#extending-the-theme - [21]: https://github.com/squidfunk/mkdocs-material/tree/master/examples/language +``` sh +cp partials/language/en.html partials/language/jp.html +``` + +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 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 -with [lunr-languages][23], both of which are integrated with this theme. Support -for other languages and even multilingual search can be activated by setting -the key `search.languages` to a comma-separated list of supported 2-letter -language codes, e.g.: +with [lunr-languages][21], both of which are integrated with this theme. Support +for other languages and even multilingual search can be activated in your +project's `mkdocs.yml`: -``` jinja -{% macro t(key) %}{{ { - ... - "search.languages": "en, de, ru", - ... -}[key] }}{% endmacro %} +``` yaml +extra: + language: + - 'en' + - 'de' + - 'ru' ``` -This will automatically load the stemmers for the specified languages and -set them up with site search, nothing else to be done. +The first language specified is used as the document language as described in +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`, -French `fr`, Spanish `es`, Italian `it`, Japanese `jp`, Dutch `du`, Danish `da`, -Portguese `pt`, Finnish `fi`, Romanian `ro`, Hungarian `hu`, Russian `ru`, -Norwegian `no`, Swedish `sv` and Turkish `tr`. +French `fr`, German `de`, Spanish `es`, Italian `it`, Japanese `jp`, Dutch `du`, +Danish `da`, Portguese `pt`, Finnish `fi`, Romanian `ro`, Hungarian `hu`, +Russian `ru`, Norwegian `no`, Swedish `sv` and Turkish `tr`. !!! 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 language. -The separator for tokenization can also be customized, which makes it possible -to index parts of words that are separated by `-` or `.` for example: +The separator for tokenization can be customized which makes it possible +to index parts of words that are separated by `-` or `.`. This can be done by +overriding `partials/language.html`: ``` jinja {% macro t(key) %}{{ { ... "search.tokenizer": "[\s\-\.]+", ... -}[key] }}{% endmacro %} +}[key] or lang.t(key) }}{% endmacro %} ``` - [22]: https://lunrjs.com - [23]: https://github.com/MihaiValentin/lunr-languages + [20]: https://lunrjs.com + [21]: https://github.com/MihaiValentin/lunr-languages ### Tabs @@ -475,13 +464,13 @@ extra: ### More advanced customization 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 -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) 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 Material theme including more information regarding installation and usage: -* [Admonition][26] -* [Codehilite][27] -* [Footnotes][28] -* [Metadata][29] -* [Permalinks][30] -* [PyMdown Extensions][31] +* [Admonition][24] +* [Codehilite][25] +* [Footnotes][26] +* [Metadata][27] +* [Permalinks][28] +* [PyMdown Extensions][29] - [25]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions - [26]: extensions/admonition.md - [27]: extensions/codehilite.md - [28]: extensions/footnotes.md - [29]: extensions/metadata.md - [30]: extensions/permalinks.md - [31]: extensions/pymdown.md + [23]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions + [24]: extensions/admonition.md + [25]: extensions/codehilite.md + [26]: extensions/footnotes.md + [27]: extensions/metadata.md + [28]: extensions/permalinks.md + [29]: extensions/pymdown.md ## Full example @@ -535,6 +524,7 @@ theme: 'material' # Options extra: + language: 'en' logo: 'images/logo.svg' palette: primary: 'indigo' diff --git a/material/partials/language.html b/material/partials/language.html index c3cce6f3d..0d2f3c25b 100644 --- a/material/partials/language.html +++ b/material/partials/language.html @@ -1,3 +1,8 @@ -{% set code = config.extra.language | default("en") %} -{% import "partials/language/" + code + ".html" as lang %} -{% macro t(key) %}{{ lang.t(key) }}{% endmacro %} +{% set languages = config.extra.language | default("en") %} +{% if languages is string %} + {% 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 %} diff --git a/material/partials/language/de.html b/material/partials/language/de.html index 25edc301b..e5bbe53df 100644 --- a/material/partials/language/de.html +++ b/material/partials/language/de.html @@ -7,7 +7,6 @@ "footer.next": "Nächste Seite", "meta.comments": "Kommentare", "meta.source": "Quellcode", - "search.languages": "de", "search.placeholder": "Suche", "search.result.placeholder": "Suchbegriff eingeben", "search.result.none": "Keine Suchergebnisse", diff --git a/material/partials/language/en.html b/material/partials/language/en.html index c2461435c..2068c97da 100644 --- a/material/partials/language/en.html +++ b/material/partials/language/en.html @@ -7,7 +7,6 @@ "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", diff --git a/src/partials/language.html b/src/partials/language.html index 994bef5e1..1f70d87ac 100644 --- a/src/partials/language.html +++ b/src/partials/language.html @@ -20,9 +20,16 @@ IN THE SOFTWARE. --> + +{% set languages = config.extra.language | default("en") %} +{% if languages is string %} + {% set languages = languages.split(",") | map("trim") %} +{% endif %} + -{% set code = config.extra.language | default("en") %} -{% import "partials/language/" + code + ".html" as lang %} +{% import "partials/language/" + (languages | first) + ".html" as lang %} -{% macro t(key) %}{{ lang.t(key) }}{% endmacro %} +{% macro t(key) %}{{ { + "search.languages": languages | join(", ") +}[key] or lang.t(key) }}{% endmacro %} diff --git a/src/partials/language/de.html b/src/partials/language/de.html index 23ee1f812..b3adff571 100644 --- a/src/partials/language/de.html +++ b/src/partials/language/de.html @@ -30,7 +30,6 @@ "footer.next": "Nächste Seite", "meta.comments": "Kommentare", "meta.source": "Quellcode", - "search.languages": "de", "search.placeholder": "Suche", "search.result.placeholder": "Suchbegriff eingeben", "search.result.none": "Keine Suchergebnisse", diff --git a/src/partials/language/en.html b/src/partials/language/en.html index 6debad7b6..283760a72 100644 --- a/src/partials/language/en.html +++ b/src/partials/language/en.html @@ -30,7 +30,6 @@ "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",