Hugo - Anleitung Teil 1 - i18n multilinguale Site erstellen

Teil 1 von 3 Anleitungen fĂĽr das Erstellen einer Hugo multilingualen Website. Es gibt immer mehrere Wege um etwas zu realisieren. In diesen Anleitungen beschreibe ich meinen Weg.
Die Themen im Teil 1 sind - hugo.toml allgemein, Page Bundle Struktur der Webseiten und Front Matter Einträge in den Markdown Dateien.
Um es vorweg zu nehmen, mit Teil 1 werden Sie noch keine komplett multilinguale Website erstellen können.
- Hugo - Anleitung Teil 2 - i18n multilinguale Site erstellen
Der zweite Teil geht in die Tiefe der Theme-Entwicklung und zeigt die Programmierung der multilingualen Website. Mit den folgenden Themen: Einträge im html und head Tag der baseof.html und Menüstruktur in der hugo.toml, inklusiv der Navigation Partials nav.html und sidepanel.html.
- Hugo - Anleitung Teil 3 - i18n multilinguale Site erstellen
Mit den folgenden Themen: Die T (Translate) Funktion von Hugo, das Umschalten der Sprache auf der Website inkl. Sourcecode und SCSS, Hugo Probleme mit multilingualen Tags, Tag Wolke als ThemenĂĽbersicht, Tag Beitragsliste inkl. Sourcecode und SCSS, interne Verlinkung.
Internationalisierung wird gerne mit dem Numeronym i18n abgekĂĽrzt - im englischen Wort Internationalization befinden sich 18 Buchstaben zwischen dem ersten Buchstaben I und dem letzten Buchstaben n.
Beitrag aktualisiert am 05.06.2023
Ich habe diesen Beitrag etwas überarbeitet und an die Hugo-Änderungen der Version 0.112 angepasst.
i18n Einträge in der hugo.toml
Die default Konfigurationsdatei von Hugo wird ab der Version 0.110.0 von config.toml in
Die allgemeinen Konfigurationsmöglichkeiten von Hugo sind sehr umfangreich. Bei den i18n Einträgen für diese Website habe ich mich auf das Notwendige beschränkt. Im Teil 2 von dieser Blogreihe kommen noch weitere Parameter hinzu.
- In der - Hugo Dokumentation - Configure Hugo
- werden alle Konfigurationsparameter der
erklärt.hugo.toml
- Die - Hugo Dokumentation - Multilingual Mode - erklärt wie verschiedene Sprachen in Hugo verarbeitet werden.
- Die Blogreihe von Régis Philibert - Hugo Multilingual Part 1: Content translation - hat mir den Einstieg in die Hugo Mehrsprachigkeit erleichtert. Deshalb empfehle ich es hier gerne.
Eine Menge Dokumentation. Ich hoffe, dass ich mit meiner Blogreihe den Einstieg etwas leichter machen kann. Die relevanten Parameter, fĂĽr diesen Teil 1 der Blogreihe, sind in der /hugo.toml
folgende:
..
defaultContentLanguage = "de"
[languages]
[languages.de]
languageName = "Deutsch"
weight = 1
title = "Hugo, Webdev, SEO, Tools"
[languages.de.params]
description = "Blog ĂĽber Hugo, Webdev, SEO, Tools"
mydomain = "tekki-tipps.de 🇩🇪"
..
[languages.en]
languageName = "English"
weight = 2
title = "Hugo, Webdev, SEO, Tools"
[languages.en.params]
description = "Blog about Hugo, Webdev, SEO, Tools"
mydomain = "tekki-tipps.de/en/ 🇬🇧"
..
Die Einträge in der hugo.toml
wurden von mir nachträglich an die Hugo-Version 0.112 angepasst. Siehe dazu auch - Multilingual - Änderungen in Hugo ab Version 0.112
.
Hugo config Parameter defaultContentLanguage
Mit dem Parameter defaultContentLanguage
wird Hugo die Hauptsprache mitgeteilt. Inhalte ohne Sprachkennzeichen werden in dieser Sprache angezeigt. Standardmäßig wird en
als default Sprache in Hugo verarbeitet. Da dies bei mir anders ist, habe ich de
eingestellt. Bei nicht ĂĽbersetzten Webseiten wird die Version mit der Hauptsprache benutzt.
Hugo config Parameter languages
Unterhalb von [languages]
wird in die Sprachversionen verzweigt. In meinem Fall in [languages.de]
und [languages.en]
.
Unterhalb der jeweiligen Sprachversion folgen die Parameter
languageName
Der languageName kann in einem Sprachumschalter als Text angezeigt werden. Mehr Infos im Teil 2.weight
Die Sortierung der Sprachen erfolgt ĂĽber diesen Parameter. Der Hauptsprache sollte die niedrigste Zahl zugewiesen werden.description
Die Benutzung von description erkläre ich in derbaseof.html
im Teil 2.mydomain
Dieser von mir erstellte Parameter wird fĂĽr den Domainnamen benutzt. FĂĽr die englische Version um/en
erweitert. Im Teil 2 werde ich dies imbaseof.html
-Abschnitt erklären.
Was ich hier jetzt aber festhalten möchte ist, auch im [languages]
Teil der Konfiguration können eigene Parameter definiert werden. Am Anfang war mir dies nicht klar. Deshalb hatte ich den title
-Parameter fĂĽr den Domainnamen missbraucht. Dadurch wurde der Sourcecode aber nicht ĂĽbersichtlicher.
Struktur Entscheidung
Hugo bietet mehrere Möglichkeiten die Webseiten einer multilingualen Site zu organisieren und zu strukturieren. Ich habe mich gegen die Methode By Directory
und fĂĽr By Filename
entschieden. Mit - Page Bundles
- fasse ich alles fĂĽr eine Webseite, d.h. Dokumente und Ressourcen (img, pdf, ..), in einem Verzeichnis zusammen. Die Struktur meiner multilingualen Page Bundles sieht wie folgt aus:
content/
├── blog/
├── name-of-page-bundle1/
├── img/
└── image-name1.jpg
└── image-name2.jpg
├── index.en.md
└── index.md
├── name-of-page-bundle2/
├── name-of-page-bundle3/
├── _index.en.md
└── _index.md
├── about-me/
├── img/
└── image-name1.jpg
├── index.en.md
└── index.md
..
themes/
├── tekki/
├── layouts/
├── index.en.html
└── index.html
FĂĽr jede Webseite wird ein Page Bundle im Content Verzeichnis angelegt. Jedes Page Bundle besteht aus dem Verzeichnisnamen des Page Bundles, einer Markdown Datei index.md
fĂĽr die Hauptsprache, index.en.md
fĂĽr die Ăśbersetzung ins englische und einem Unterverzeichnis img
für die Bilddateien. Meine Blogbeiträge habe ich in dem Verzeichnis content/blog/
gespeichert. Mit der Zeit, bei immer mehr Blogbeiträgen, wird es dadurch für mich übersichtlicher.
Die Page Bundles der allgemeinen Webseiten - Ăśber mich, Datenschutz, Impressum und die Kontaktseite speichere ich direkt im content
Verzeichnis.
Der Page Bundle Verzeichnisname kann auch nachträglich verändert werden. Dies hat keinen Einfluss auf die URL-Struktur. Der Verzeichnisname wird nur für die eigene Organisation der Page Bundles genutzt.
Die Startseiten habe ich in meinem Theme unter themes/tekki/layouts/index*.html
gespeichert.
Markdown Dateinamen im Page Bundle
Der Dateiname von Markdown Dateien wird von Hugo nicht in die Webseite eingebaut. Es ist also egal wie die Datei benannt wird. Ich habe mich fĂĽr index.md
und index.en.md
entschieden.
Was und wofĂĽr sind _index.md Dateien?
Kurz und bündig - damit können Sie Ihre Listenvorlagen mit Titelseiten und Inhalten versehen. In der - Hugo Dokumentation - Index Pages: _index.md - wird dies genauer beschrieben.
Ich habe in meinem Theme unter themes/layouts/blog/list.html
ein eigenes Template und benötige den Standard von Hugo nicht. Trotzdem müssen die _index*.md
Dateien vorhanden sein, damit Hugo den Generierungsprozess fĂĽr mein content/blog
Verzeichnis durchfĂĽhrt.
Der Inhalt von content/blog/_index.md
:
---
title: Blog
description: "Blog Artikel"
sitemap_exclude: true
---
Der Inhalt von content/blog/_index.en.md
:
---
title: Blog
description: "Blog Post"
sitemap_exclude: true
---
Ungewollte Auswirkung auf die sitemap.xml
Wie oben beschrieben wird diese Generierungsanweisung eigentlich nirgendwo angezeigt. Eigentlich - aber bis in die sitemap.xml
schafft es dieser Eintrag ohne sitemap_exclude: true
dennoch:
<url>
<loc>https://tekki-tipps.de/blog/</loc>
<lastmod>2023-01-30T20:22:03+01:00</lastmod>
<xhtml:link
rel="alternate"
hreflang="en"
href="https://tekki-tipps.de/en/blog/"
/>
<xhtml:link
rel="alternate"
hreflang="de"
href="https://tekki-tipps.de/blog/"
/>
</url>
Da das ĂĽberhaupt keinen Sinn macht, habe ich einen eigenen Front Matter Parameter sitemap_exclude: true
in die md
-Dateien eingefĂĽgt. Im Template themes/tekki/layouts/_default/sitemap.xml
frage ich diesen Parameter ab und wenn true
, wird der Eintrag nicht erstellt.
Das war aber nicht alles. Was mir damals bei der Entwicklung aufgefallen ist - die Webseite tekki-tipps.de/blog/
kann aufgerufen werden. Und das macht auch keinen Sinn und sieht durch die fehlenden CSS Klassen nicht gut aus.
Die Lösung ist ein Redirect 301
in der static/.htaccess
:
RewriteEngine On
Redirect 301 /blog https://tekki-tipps.de
Redirect 301 /en/blog https://tekki-tipps.de/en/
Die Startseite dieser Site - index.html und index.en.html
Das Ganze muss ja irgendwo anfangen. Die Startseiten meiner Site index.html
und index.en.html
habe ich in dem Verzeichnis themes/tekki/layouts/
erstellt. In dem Verzeichnis sind auch meine 404.html
und die robots.txt
.
Der einzige Unterschied zwischen index.html
und index.en.html
ist der ĂĽbersetzte Text der HTML-Tags h1
und p
. Aus diesem Grund zeige ich hier nur die index.en.html
an:
{{- define "main" -}}
<div class="content-header">
<div class="container">
<h1>A blog about Hugo, Webdev, SEO, Tools ..</h1>
<p>Tips and tricks around the static website generator Hugo.</p>
</div>
</div>
{{- partial "blogTeaser.html" . -}}
{{- end -}}
Im Partial blogTeaser.html
werden dann die Teaser der Blogbeiträge angezeigt.
Front Matter Parameter fĂĽr i18n
Die relevanten Front Matter Parameter fĂĽr diesen Blogbeitrag sehen in der index.md
wie folgt aus:
---
..
slug: "hugo-i18n-howto-teil-1"
translationKey: "i18n-howto-1"
description: "i18n - Teil 1 von 3 Anleitungen fĂĽr das Erstellen einer multilingualen Website mit Hugo dem Static Site Generator."
..
---
In der index.en.md
:
---
..
slug: "hugo-i18n-howto-part-1"
translationKey: "i18n-howto-1"
description: "i18n - Part 1 of 3 instructions for creating a multilingual website with Hugo the Static Site Generator."
..
---
Der Hugo Front Matter Parameter slug
kĂĽrzt die URL vom Blogbeitrag und muss in der jeweiligen Sprache angepasst werden. Dies ist nicht der entscheidende Parameter fĂĽr die Ăśbersetzung, aber trotzdem sehr hilfreich.
Der Parameter translationKey
ist entscheidend und muss in allen index*.md
Dateien des Page Bundles gleich lauten. Dadurch erkennt Hugo das dies eine mehrsprachige Webseite ist und generiert entsprechend alle Strukturen. Sogar bis in die sitemap.xml
- magisch, ich mag Hugo.
description
ist ein sehr wichtiger Front Matter Parameter. Suchmaschinen benutzen den Text bei der Anzeige unterhalb von Links. Aber dazu mehr im Teil 2.
Fazit
Wenn man einige Grundregeln beachtet, ist die Erstellung einer mehrsprachigen Website mit Hugo gar nicht so schwer. Ich hoffe, dass diese Serie den Weg fĂĽr Hugo i18n-Einsteiger etwas einfacher macht. Es lohnt sich. Ein englischer Blogbeitrag von mir wurde gerade auf Samoa aufgerufen. Matomo sei Dank fĂĽr diese Info und der Blogger freut sich.
Linkliste zu diesem Beitrag
Das könnte Sie auch interessieren
- Hugo - Anleitung Teil 2 - i18n multilinguale Site erstellen
Der zweite Teil geht in die Tiefe der Theme-Entwicklung und zeigt die Programmierung der multilingualen Website. Mit den folgenden Themen: Einträge im html und head Tag der baseof.html und Menüstruktur in der hugo.toml, inklusiv der Navigation Partials nav.html und sidepanel.html.
- Hugo - Anleitung Teil 3 - i18n multilinguale Site erstellen
Mit den folgenden Themen: Die T (Translate) Funktion von Hugo, das Umschalten der Sprache auf der Website inkl. Sourcecode und SCSS, Hugo Probleme mit multilingualen Tags, Tag Wolke als ThemenĂĽbersicht, Tag Beitragsliste inkl. Sourcecode und SCSS, interne Verlinkung.
- Hugo - Page Bundle Shortcodes fĂĽr Bilder
In der Markdown Datei Bilder per Shortcodes aus dem Page Bundle einbinden.
- Hugo - i18n Multilingual - lastmod Datum länderspezifisch anpassen
i18n - Die länderspezifische Schreibweise des lastmod Datums entsprechend der Sprache anpassen.
Kommentare werden bei deutscher Spracheinstellung nicht in der englischen Variante der Webseite angezeigt und umgekehrt.