diff --git a/CHANGELOG b/CHANGELOG
index 98d7ec1a1b8b24ba9086c3580b2cfa6c063cb6ce..5dec18cf742cc471a0dc105879fd7fad93bf5518 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 8426dfdf76fd46fa9354a5778486eec9bf929532..f29b0725547b2f3d19cd57b9ed9cf8f7b6028adb 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'
+```
+
+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:
+
+``` sh
+cp partials/language/en.html partials/language/jp.html
```
-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.
+Feel free to contribute your localization to Material for MkDocs by opening a
+Pull Request.
- [19]: customization.md#overriding-partials
- [20]: customization.md#extending-the-theme
- [21]: https://github.com/squidfunk/mkdocs-material/tree/master/examples/language
+ [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]
-
- [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
+* [Admonition][24]
+* [Codehilite][25]
+* [Footnotes][26]
+* [Metadata][27]
+* [Permalinks][28]
+* [PyMdown Extensions][29]
+
+ [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 c3cce6f3deca4735a5b655ea9520140ff878bf88..0d2f3c25be483dc7a9a3afcfbbbde4ae3d7ab561 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 25edc301b62631f99e9b22f640f6bfe628296a03..e5bbe53dfd066fcd00786ccd4da3f005d7de35d0 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 c2461435c0c67e4008056fe4ce541cc82e6e7498..2068c97dace4c94a829fd6a5efcbdf752f9ca0b6 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 994bef5e18225164a8d7922893c9e8643e67df7b..1f70d87acecbfab861f3a9d0e94872b873be68da 100644
--- a/src/partials/language.html
+++ b/src/partials/language.html
@@ -20,9 +20,16 @@
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 -->
-{% set code = config.extra.language | default("en") %}
-{% import "partials/language/" + code + ".html" as lang %}
+{% import "partials/language/" + (languages | first) + ".html" as lang %}
<!-- Re-export translations -->
-{% 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 23ee1f81282b40e8f8d1a531942ea9dc53fc1e4c..b3adff5716bf968d760df422b29a28447f385a76 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 6debad7b63956de2fab60ffd023d49242e32c6bd..283760a721c35f0efe430975381155c90c6a3835 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",