Ein mehrsprachiges Hilfecenter ohne leere Seiten

Ein Kookee-Projekt konnte sein Hilfecenter auf Englisch und Deutsch haben, und das gehostete Portal zeigte trotzdem jede Seite auf Englisch. Die deutschen Artikel waren da, und die API hätte sie geliefert. Das Portal hat sie nur nie abgefragt.

Die Sprachauswahl im Header des Portals machte es noch schlimmer. Es war die Auswahl für Kookees eigene Oberfläche, mit den sechs Sprachen, in denen es Kookees Buttons gibt. Wer Deutsch wählte, bekam deutsche Menüs und jeden Artikel weiter auf Englisch. Ein Projekt auf Italienisch bekam eine Auswahl ohne Italienisch.

Darauf gestoßen bin ich, als ich das Ankündigungsbanner des Portals in @kookee/react verlegt habe, und ich habe es im selben Release behoben, in Kookee 1.29.0.

Jede Sprache bekommt ihre eigene Adresse

Wer die deutsche Seite an eine Kollegin schickt, braucht dafür eine deutsche Adresse. Ich habe die Sprache in den Pfad gesetzt, nur die Standardsprache kommt ohne aus. Im Demo-Portal von Lumen, das Englisch und Deutsch hat, sieht das so aus:

lumen.kookee.dev/help/getting-started/invite-your-team       Englisch, die Standardsprache
lumen.kookee.dev/de/help/erste-schritte/dein-team-einladen   Deutsch
lumen.kookee.dev/en/help/getting-started/invite-your-team    → /help/getting-started/invite-your-team
lumen.kookee.dev/fr/help/getting-started/invite-your-team    → /help/getting-started/invite-your-team
lumen.kookee.dev/de/help/getting-started/invite-your-team    → /de/help/erste-schritte/dein-team-einladen

Die Standardsprache hat kein Segment, weil jeder bisherige Portal-Link die Standardsprache meinte: Links in E-Mails, in alten Beiträgen, in den MCP-Antworten von Kookee und in Webhook-Payloads. Sie funktionieren weiter, meinen weiter dasselbe, und Kookee baut sie nach wie vor so.

Die Weiterleitungen sorgen dafür, dass jede Seite nur eine Adresse hat. /en/ in einem Projekt mit Englisch als Standardsprache führt zur Adresse ohne Segment. Ebenso eine Sprache, die das Projekt nicht hat oder später entfernt hat: Ein /fr/-Link, der geteilt wurde, bevor Französisch wegfiel, landet auf der englischen Seite statt auf einem 404. Und ein englischer Slug unter /de/, also die Adresse, die entsteht, wenn du /de vor einen englischen Link tippst, führt zum eigenen Slug des deutschen Artikels.

Fehlt eine Übersetzung, springt die Standardsprache ein

Das Hilfecenter von Lumen hat 12 Artikel auf Englisch. Drei davon, die aus Getting started, gibt es auch auf Deutsch. Ein deutscher Leser öffnet lumen.kookee.dev/de/help.

Das Portal könnte die anderen neun ausblenden. Dann sieht das deutsche Hilfecenter fertig aus: drei Artikel, alle auf Deutsch. Wer den Artikel zur Abrechnung braucht, erfährt nicht, dass es ihn gibt, und schreibt dem Support eine Frage, die auf Englisch längst beantwortet war.

Es könnte sie mit einem Hinweis „noch nicht übersetzt“ zeigen. Das habe ich erwogen und verworfen: Dass der Artikel auf Englisch ist, sieht der Leser selbst.

Oder es zeigt den englischen Artikel unter der deutschen Adresse, ohne Hinweis, so wie es Kookees API und das Website-Widget schon taten. Genau das macht das Portal jetzt. Die Kategorienkarten auf /de/help zeigen Erste Schritte, die deutsche Fassung von Getting started, neben Dashboards, Billing und Guides, die es nur auf Englisch gibt:

Öffnet man von dort einen Artikel, den es nur auf Englisch gibt, behält er seine /de/-Adresse: Die Sprachauswahl zeigt weiter Deutsch, und der nächste Link, dem der Leser folgt, bleibt unter /de/.

Der Artikel selbst trägt lang="en", damit ein Screenreader ihn mit englischer Stimme vorliest, statt englische Wörter nach deutschen Regeln auszusprechen. Bei Arabisch und Hebräisch setzt er außerdem die Schreibrichtung von rechts nach links.

Dieselbe Regel gilt im ganzen Portal. Die Listen von Blog, Changelog und Seiten zeigen die Sprache des Lesers, wo es eine Übersetzung gibt, und sonst die Standardsprache. Hilfekategorien werden über die Sprachen hinweg einander zugeordnet, sodass sich ein unübersetzter Artikel innerhalb der deutschen Fassung seiner Kategorie öffnet. Die Suche sucht zuerst in der Sprache der Seite, dann in der Standardsprache.

Warum kookee.dev unübersetzte Beiträge stattdessen ausblendet

Mein eigener Blog macht es umgekehrt. kookee.dev/de/blog listet nur Beiträge, die es auf Deutsch gibt, und ein deutscher Link auf einen Beitrag, den es nur auf Englisch gibt, leitet auf die englische Seite weiter.

Der Unterschied sind die Suchmaschinen. kookee.dev wird indexiert, und ein englischer Artikel unter einer deutschen Adresse ist eine zweite URL mit demselben Text. Ich gebe Google lieber eine Adresse pro Text. Portale senden X-Robots-Tag: noindex, Suchmaschinen lassen Portalseiten also aus, und für die Leser ist der Fallback die bessere Wahl.

Die Sprachauswahl zeigt nur deine Sprachen

Die Auswahl listet jetzt die Sprachen des Projekts, jede unter ihrem eigenen Namen: Deutsch, Italiano, 日本語. Wer eine wählt, landet auf derselben Seite in dieser Sprache: bei der Übersetzung des Artikels, wenn es eine gibt, sonst beim selben Artikel unter dem neuen Segment.

Ein Projekt mit nur einer Sprache zeigt gar keine Auswahl. Die Sprachen eines Projekts legst du unter Einstellungen → Projekt in Unterstützte Sprachen fest, und sobald es zwei sind, erscheint die Auswahl im Header, im mobilen Menü und im Footer.

Die Sprachauswahl für Kookees eigene Oberfläche habe ich aus den Portalen ganz entfernt. Ein Portal gehört dem Projekt, und wer dort sechs Sprachen sieht, erwartet die Artikel in sechs Sprachen. Buttons und Menüs folgen weiter der letzten Wahl des Lesers oder seinem Browser, sonst Englisch. Wählt er eine Inhaltssprache, die auch Kookees Oberfläche hat (Englisch, Russisch, Spanisch, Französisch, Portugiesisch oder Deutsch), wechseln auch die Buttons. Bei Italienisch bleiben sie, wie sie waren.

Eine Weiterleitung nach Browsersprache gibt es nicht. Wer seinen Browser auf Deutsch eingestellt hat und lumen.kookee.dev/help öffnet, bekommt Englisch, mit der Sprachauswahl im Header.

Was sich sonst im Portal geändert hat

• Das Website-Widget im Portal zeigt Hilfe und Antworten in der Sprache der Seite. Bisher folgte es der Sprache der Oberfläche und konnte so deutsche Hilfe neben einer englischen Seite zeigen.

• Das Ankündigungsbanner zeigt Ankündigungen in der Sprache der Seite.

• Die Startseite des Portals zählt einen Artikel und seine Übersetzungen nur einmal. Vorher zählte sie jede Sprache einzeln.

• Diese Seite melden auf einer übersetzten Seite meldet jetzt den Artikel. Bisher ging die Meldung an das Projekt.

Unverändert: Blog-Tags und hreflang

Die Zahl bei einem Tag im Portal-Blog zählt weiterhin alle Sprachen zusammen. Portale bekommen keine hreflang-Links und keine Sitemaps, weil Suchmaschinen sie nicht indexieren.

Das öffentliche Portal nutzen beschreibt die Adressen, die Sprachauswahl und die Weiterleitungen des Portals, und Mehrsprachige Inhalte und Fallback auf die Standardsprache denselben Fallback über das SDK, für ein Hilfecenter auf deiner eigenen Website.

Weiterlesen

• Dein Support-Widget sollte die Sprache der Seite lesen, nicht die des Browsers — wie das Website-Widget auf deiner eigenen Website eine Sprache wählt und warum es der Seite mehr traut als dem Browser.

• So baust du ein Hilfecenter für dein SaaS — Struktur, Kategorien und Suche, bevor du irgendetwas davon übersetzt.

• Das Widget in der Sprache deiner Besucher zeigen — die Sprachoptionen des Widgets, von data-locale bis setLocale().