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.

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 hugo.toml umbenannt. Damit wollen die Hugo Entwickler es Code-Editoren und Build-Tools leichter machen, diese als Hugo-Konfigurationsdatei und Projekt zu identifizieren.

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 hugo.toml erklärt.
• 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 der baseof.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 im baseof.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