Zweisprachig mit Hugo: So bin ich vorgegangen

Mehrsprachigkeit klingt in Hugo erst simpel: Sprachen in der Konfiguration anlegen, Inhalte übersetzen, fertig. In der Praxis stecken die Fehler aber in den Details.

Warum Mehrsprachigkeit, wenn Browser heute alles live übersetzen können? Für mich ist die Antwort einfach: Ich denke auf Deutsch, schreibe ich besser auf Deutsch. Eine automatische Live-Übersetzung reicht mir aber nicht, weil ich beim englischen Text die Kontrolle über Ton, Begriffe und Nuancen behalten will.

Kurz hatte ich die Idee, Deutsch zu schreiben, danach ins Englische zu übersetzen und den deutschen Originaltext zu verwerfen. Das hat sich falsch angefühlt. Deshalb habe ich mich für einen klaren Weg entschieden: Der Blog bleibt primär deutsch, und zusätzlich gibt es eine bewusst gepflegte englische Version.

In diesem Post zeige ich, wie ich Meadow Lark auf Deutsch und Englisch erweitert habe, worauf man achten sollte und welche Fehler bei mir konkret aufgetreten sind.

1) Saubere Basis in der Hugo-Konfiguration

Der erste Schritt ist eine klare Sprachkonfiguration in der Datei hugo.yaml.

Wichtig sind vor allem:

• defaultContentLanguage auf ‘de’ setzen
• beide Sprachen unter languages definieren
• pro Sprache Menüeinträge pflegen
• ein einheitliches Datumsformat pro Sprache setzen

Ich habe außerdem den Theme-Eintrag explizit gesetzt. Ohne aktives Theme können Layouts fehlen oder Seiten scheinbar leer rendern.

2) Inhalte als Sprachpaare anlegen

Ich arbeite mit Dateipaaren:

• about.md und about.en.md
• projects.md und projects.en.md
• posts/slug.md und posts/slug.en.md

Das macht die Zuordnung eindeutig und Hugo kann Übersetzungen sauber verknüpfen.

Wichtig: Jede Sprachversion braucht eigenes Front Matter mit sinnvoller Zusammenfassung. Diese sollte manuell geschrieben werden und nicht automatisch entstehen.

3) Sprachumschalter im Template

Der Umschalter steckt in einer wiederverwendbaren Navigation-Komponente. Das Prinzip:

• Wenn eine Übersetzung für die aktuelle Seite existiert, direkt dorthin linken
• Wenn nicht, auf die Startseite der anderen Sprache verlinken

Der zweite Teil ist wichtig, damit Nutzer nicht auf einer Sackgasse landen.

4) Typische Fehler, die schnell passieren

Fehler 1: Theme nicht aktiv

Symptom: Startseite wirkt leer oder Layouts sind unvollständig.

Ursache: Der Theme-Eintrag in hugo.yaml fehlt.

Fix: Theme explizit setzen, damit die Basis-Layouts geladen werden.

Wichtig: theme steht auf oberster Ebene in hugo.yaml, also nicht unter languages, params oder outputs.

baseURL: "https://meadowlark.care"
theme: "hugo-bearblog"

defaultContentLanguage: de
defaultContentLanguageInSubdir: false

Fehler 2: API-Unterschiede zwischen Hugo-Versionen

Symptom: Lokal funktioniert alles, im Cloud-Build knallt es im Template, weil zwei verschiedene Hugo-Versionen im Spiel sind.

Bei mir lief lokal Hugo 0.160, Cloudflare baute aber mit Hugo 0.146. Eine neuere Template-API lief deshalb lokal.

Fix: Versionen pinnen, damit lokal und Cloud dieselbe Hugo-Version nutzen (z. B. 0.160.1), und erst danach deployen. Falls das nicht geht, i18n-/Sprachumschalt-Logik auf kompatiblere Konstrukte umstellen. Danach erneut lokal bauen und remote deployen.

Ich habe dafür zwei Stellen gesetzt: in Cloudflare die Variable HUGO_VERSION=0.160.1 und lokal eine .tool-versions Datei mit hugo 0.160.1. Somit laufen lokale und Online-Builds mit derselben Basis.

Fehler 3: Sprachabhaengige URLs im Footer oder Menue

Symptom: RSS-Links oder Sprachlinks zeigen in eine falsche Sprache oder auf 404.

Fix: Links über Hugo-Output-Formate und RelPermalink aufbauen, statt Pfade hart zu codieren.

Fehler 4: Übersetzungen sind vorhanden, aber nicht verlinkt

Symptom: Die EN-Datei existiert, aber der Umschalter zeigt sie nicht.

Ursache ist inkonsistente Dateibenennung oder fehlende Gegenstücke.

Fix: Sprachpaare konsequent benennen und Front Matter vergleichen.

5) Mein minimales Test-Set vor dem Push

Bevor ich pushe, gehe ich kurz durch:

• hugo Build lokal ohne Fehler
• Sprachumschalter auf Home und Post-Seiten prüfen
• DE/EN Menülinks anklicken
• RSS-Link in beiden Sprachen testen

Gerade der Versionsunterschied zwischen lokalem Hugo und Cloud-Build hat mir gezeigt: Ein grüner lokaler Build reicht nicht.

Fazit

Zweisprachigkeit mit Hugo ist gut machbar, wenn Konfiguration, Dateibenennung und Templates sauber zusammenspielen.

Die größten Stolperfallen sind nicht die Inhalte, sondern die kleinen Infrastrukturdetails: Theme-Aktivierung, stabile Template-APIs und robuste URL-Erzeugung.

Wenn diese drei Punkte sitzen, wird i18n in Hugo entspannt.