feat: add multilingual mode support (#241)

BREAKING CHANGE:  Layout file renamed ´layouts/partials/page-footer.html → layouts/partials/menu-nextprev.html`. If you use overrides, you might need to change the filenames as well.

exampleSite/config/_default/config.yaml

@@ -2,11 +2,14 @@
 baseURL: https://geekdocs.de/
 title: Geekdocs
 theme: hugo-geekdoc
+
 pygmentsUseClasses: true
 pygmentsCodeFences: true
 timeout: 180000
 pluralizeListTitles: false
 
+defaultContentLanguage: en
+
 disablePathToLower: true
 enableGitInfo: true
 
@@ -34,19 +37,3 @@ outputs:
     - HTML
   term:
     - HTML
-
-params:
-  geekdocToC: 3
-  geekdocTagsToMenu: true
-
-  geekdocRepo: https://github.com/thegeeklab/hugo-geekdoc
-  geekdocEditPath: edit/main/exampleSite/content
-
-  geekdocSearch: true
-  geekdocSearchShowParent: true
-
-  geekdocLegalNotice: https://thegeeklab.de/legal-notice/#contact-information
-  geekdocPrivacyPolicy: https://thegeeklab.de/legal-notice/#privacy-policy
-
-  geekdocImageLazyLoading: true
-  geekdocDarkModeDim: true

exampleSite/config/_default/languages.yaml

@@ -0,0 +1,5 @@
+---
+en:
+  languageName: "English"
+  contentDir: "content/en"
+  weight: 10

exampleSite/config/_default/params.yaml

@@ -0,0 +1,15 @@
+---
+geekdocToC: 3
+geekdocTagsToMenu: true
+
+geekdocRepo: https://github.com/thegeeklab/hugo-geekdoc
+geekdocEditPath: edit/main/exampleSite/content
+
+geekdocSearch: true
+geekdocSearchShowParent: true
+
+geekdocLegalNotice: https://thegeeklab.de/legal-notice/#contact-information
+geekdocPrivacyPolicy: https://thegeeklab.de/legal-notice/#privacy-policy
+
+geekdocImageLazyLoading: true
+geekdocDarkModeDim: true

exampleSite/content/en/features/multilingual/_index.md

@@ -0,0 +1,78 @@
+---
+title: Multilingual
+resources:
+  - name: translation-available
+    src: images/translation-available.png
+    title: ""
+---
+
+{{< toc >}}
+
+Hugo supports the creation of websites with multiple languages. In this post we will explain how to get configure Multilingual Mode with this theme.
+
+## Configuration
+
+### Languages
+
+You need to set a default language and configure at least two different languages used by your site to your configuration file at `config.toml`:
+
+```Toml
+defaultContentLanguage = "en"
+
+[languages.en]
+languageName = "English"
+contentDir = "content/en"
+weight = 10
+
+[languages.de]
+languageName = "German"
+contentDir = "content/de"
+weight = 20
+```
+
+### Translation Strings
+
+To customize translation strings used by the theme you can create a file `i18n/<languagecode>.toml` for every language you want to use e.g. `i18n/en.toml`. You can lookup all used strings in the [default](https://github.com/thegeeklab/hugo-geekdoc/blob/main/i18n/en.yaml) translation file.
+
+### Menus
+
+For the [Bundle Menu](/usage/menus/#bundle-menu) as well as for the [Extra Header Menu](/usage/menus/#extra-header-menu) you can translate the name within the data file of the menu:
+
+```YAML
+---
+more:
+  # If `name` is a text, this text will be used as name for each language.
+  - name: News
+    ref: "/#"
+    icon: "gdoc_notification"
+  # To translate the name you can add a sub-item per language. Important: If you miss a language key
+  # that is configured in the languages list of your `config.toml` the name will be empty for this language!
+  - name:
+      en: Releases
+      de: Veröffentlichung
+    ref: "https://github.com/thegeeklab/hugo-geekdoc/releases"
+    external: true
+    icon: "gdoc_download"
+```
+
+## Add Content
+
+To translate your content you need to create a directory `content/<languagecode>/` for each language you want to use e.g. `content/en/`. This language directories will hold the translated pages for the particular language.
+
+## Switch Content
+
+If you have configured at least two different languages, the language switcher will be enabled in the UI automatically. The switcher is as part of the header menu and displayed on all pages.
+
+{{< columns >}}
+
+[![Beach Color Palette](images/translation-available.png)](images/translation-available.png)
+
+On pages for which a translation is available it will be displayed in the selection list and links to the translated page.
+
+<--->
+
+[![Beach Color Palette](images/translation-not-available.png)](images/translation-not-available.png)
+
+Pages without a translation will be displayed in the selection list as well but are marked with an asterisk and link to the start page of the respective language.
+
+{{< /columns >}}

exampleSite/content/en/shortcodes/columns.md

@@ -6,17 +6,17 @@ The Columns shortcode can be used to organize content side-by-side (horizontally
 
 ```html
 {{</* columns */>}} <!-- begin columns block -->
-# Left Content
+## Left Content
 Dolor sit, sumo unique argument um no ...
 
 <---> <!-- magic separator, between columns -->
 
-# Mid Content
+## Mid Content
 Dolor sit, sumo unique argument um no ...
 
 <---> <!-- magic separator, between columns -->
 
-# Right Content
+## Right Content
 Dolor sit, sumo unique argument um no ...
 {{</* /columns */>}}
 ```

exampleSite/content/en/shortcodes/includes.md

@@ -49,14 +49,14 @@ This method can be used to include source code files and keep them automatically
 
 <!-- prettier-ignore -->
 ```tpl
-{{</* include file="config.yaml" language="yaml" options="linenos=table,hl_lines=5-6,linenostart=100" */>}}
+{{</* include file="config/_default/config.yaml" language="yaml" options="linenos=table,hl_lines=5-6,linenostart=100" */>}}
 ```
 
 Result:
 
 <!-- prettier-ignore-start -->
 <!-- spellchecker-disable -->
-{{< include file="config.yaml" language="yaml" options="linenos=table,hl_lines=5-6,linenostart=100" >}}
+{{< include file="config/_default/config.yaml" language="yaml" options="linenos=table,hl_lines=5-6,linenostart=100" >}}
 <!-- spellchecker-enable -->
 <!-- prettier-ignore-end -->
 

exampleSite/content/en/usage/configuration.md

@@ -61,11 +61,11 @@ enableRobotsTXT = true
   # You can also specify this parameter per page in front matter.
   geekdocBreadcrumb = false
 
-  # (Optional, default none) Set source repository location. Used for 'Edit this page' links.
+  # (Optional, default none) Set source repository location. Used for 'Edit page' links.
   # You can also specify this parameter per page in front matter.
   geekdocRepo = "https://github.com/thegeeklab/hugo"
 
-  # (Optional, default none) Enable 'Edit this page' links. Requires 'GeekdocRepo' param
+  # (Optional, default none) Enable 'Edit page' links. Requires 'GeekdocRepo' param
   # and path must point to 'content' directory of repo.
   # You can also specify this parameter per page in front matter.
   geekdocEditPath = "edit/main/exampleSite/content"
@@ -174,11 +174,11 @@ params:
   # You can also specify this parameter per page in front matter.
   geekdocBreadcrumb: false
 
-  # (Optional, default none) Set source repository location. Used for 'Edit this page' links.
+  # (Optional, default none) Set source repository location. Used for 'Edit page' links.
   # You can also specify this parameter per page in front matter.
   geekdocRepo: "https://github.com/thegeeklab/hugo-geekdoc"
 
-  # (Optional, default none) Enable "Edit this page" links. Requires 'GeekdocRepo' param
+  # (Optional, default none) Enable "Edit page" links. Requires 'GeekdocRepo' param
   # and path must point to 'content' directory of repo.
   # You can also specify this parameter per page in front matter.
   geekdocEditPath: edit/main/exampleSite/content
@@ -262,11 +262,11 @@ geekdocBreadcrumb = false
 # Set source repository location.
 geekdocRepo = "https://github.com/thegeeklab/hugo-geekdoc"
 
-# Enable "Edit this page" links. Requires 'GeekdocRepo' param and path must point
+# Enable "Edit page" links. Requires 'GeekdocRepo' param and path must point
 # to 'content' directory of repo.
 geekdocEditPath = "edit/main/exampleSite/content"
 
-# Used for 'Edit this page' link, set to '.File.Path' by default.
+# Used for 'Edit page' link, set to '.File.Path' by default.
 # Can be overwritten by a path relative to 'geekdocEditPath'
 geekdocFilePath =
 
@@ -322,11 +322,11 @@ geekdocBreadcrumb: false
 # Set source repository location.
 geekdocRepo: "https://github.com/thegeeklab/hugo-geekdoc"
 
-# Enable "Edit this page" links. Requires 'GeekdocRepo' param and path must point
+# Enable "Edit page" links. Requires 'GeekdocRepo' param and path must point
 # to 'content' directory of repo.
 geekdocEditPath: "edit/main/exampleSite/content"
 
-# Used for 'Edit this page' link, set to '.File.Path' by default.
+# Used for 'Edit page' link, set to '.File.Path' by default.
 # Can be overwritten by a path relative to 'geekdocEditPath'
 geekdocFilePath:
 

exampleSite/content/en/usage/menus.md

@@ -33,7 +33,7 @@ content/
 
 ## Bundle menu
 
-This type of navigation needs to be enabled first by setting `geekdocMenuBundle` to `true` in your [site configuration](/usage/configuration/#site-configuration). After you have activated the bundle menu, you start with an empty navigation. This is intentional because bundle menus have to be defined manually in a data file. While this increases the effort it also offers maximum flexibility in the design. The data file needs to be written in YAML and placed at `data/menu/main.yml`.
+This type of navigation needs to be enabled first by setting `geekdocMenuBundle` to `true` in your [site configuration](/usage/configuration/#site-configuration). After you have activated the bundle menu, you start with an empty navigation. This is intentional because bundle menus have to be defined manually in a data file. While this increases the effort it also offers maximum flexibility in the design. The data file needs to be written in YAML and placed at `data/menu/main.yaml`.
 
 **Example:**
 
@@ -73,7 +73,7 @@ As an advantage you can add [icons](/features/icon-sets/) to your menu entries e
 The more menu is special type of the bundle menu and can be combined with the default file-tree menu.
 {{< /hint >}}
 
-As this is a special type of the bundle menu it is basically working in the same way. To enable it just add a data file to `data/menu/more.yml`. The more menu will also work with the file-tree menu and therefor **don't need to be enabled** by the `geekdocMenuBundle` parameter.
+As this is a special type of the bundle menu it is basically working in the same way. To enable it just add a data file to `data/menu/more.yaml`. The more menu will also work with the file-tree menu and therefor **don't need to be enabled** by the `geekdocMenuBundle` parameter.
 
 **Example:**
 
@@ -97,7 +97,7 @@ more:
 
 ## Extra Header Menu
 
-If you want to customize the header menu, this can be achieved by using a data file written in YAML and placed at `data/menu/extra.yml`.
+If you want to customize the header menu, this can be achieved by using a data file written in YAML and placed at `data/menu/extra.yaml`.
 
 **Example:**
 

exampleSite/data/menu/more.yaml

@@ -7,7 +7,7 @@ more:
     ref: "https://github.com/thegeeklab/hugo-geekdoc/releases"
     external: true
     icon: "gdoc_download"
-  - name: "View Source"
+  - name: View Source
     ref: "https://github.com/thegeeklab/hugo-geekdoc"
     external: true
     icon: "gdoc_github"