Astro-SSG-Website mit Google Translation API mehrsprachig gemacht

Eines Tages kam vom Geschäftsführer die Anweisung: "Lass uns unsere Website mehrsprachig machen. Es gibt wohl die Google Cloud Translation API, die während des Builds automatisch übersetzen kann!"

Unsere Website ist als statische Seite (SSG) mit Astro aufgebaut. Während wir die Google Cloud Translation API recherchierten, entschieden wir uns, sie direkt umzusetzen.

Vorbereitung: API-Schlüssel aktivieren und Dienstkonto erstellen

Cloud Translation API aktivieren

Aktivieren Sie in der Google Cloud Console die Cloud Translation API unter "APIs und Dienste".

Dienstkonto und Schlüssel erstellen

Um die API zu nutzen, erstellen wir ein Dienstkonto und laden den JSON-Schlüssel herunter.

Bei diesem JSON-Schlüssel ist Vorsicht geboten, da er einen privaten Schlüssel enthält, der unter keinen Umständen veröffentlicht werden darf.

Zugriffsrechte für das Dienstkonto vergeben

Wechseln Sie zu IAM und fügen Sie unter Principals die E-Mail-Adresse des Dienstkontos hinzu. Als Rolle wählen Sie „Cloud Translation API User“.

Wie mehrsprachige Seiten generiert werden

Zunächst probierten wir den Ansatz aus, die Astro-Datei zu kopieren, die Übersetzungs-API direkt aufzurufen und so automatisch mehrsprachige Astro-Dateien zu erzeugen.

Die Seiten ließen sich zwar generieren, doch Codeblöcke wurden beschädigt, importierte Komponenten konnten nicht verarbeitet werden und Tags innerhalb von Attributen führten zu Fehlern. Da sich diese Probleme nicht zufriedenstellend lösen ließen, haben wir den Ansatz geändert.

Letztlich haben wir uns für einen einfachen Postbuild-Prozess entschieden, der die Übersetzung auf das nach dem Build erzeugte statische HTML anwendet.

Spracheinstellungen werden mit der i18n-Konfigurationsdatei von Astro verknüpft

Zur Verwaltung der mehrsprachigen Seitenstruktur haben wir die bereits vorhandene i18n-Konfigurationsdatei von Astro (LOCALES_SETTING) als Konfigurationsdatei für das Übersetzungsskript verwendet.

Um eine Sprache hinzuzufügen, genügt es, sie hier zu ergänzen.

export const LOCALES_SETTING: LocaleSetting = {
  ja: {
    label: '日本語',
    lang: 'ja',
    oglocale: 'ja_JP',
    path: 'ja',
  },
  en: {
    label: 'English',
    lang: 'en',
    oglocale: 'en_US',
    path: 'en',
  },
  de: {
    label: 'Deutsch',
    lang: 'de',
    oglocale: 'de_DE',
    path: 'de',
  },
  es: {
    label: 'Español',
    lang: 'es',
    oglocale: 'es_ES',
    path: 'es',
  },
  cn: {
    label: '简体中文',
    lang: 'zh-CN',
    oglocale: 'zh_CN',
    path: 'zh-cn',
  },
  tw: {
    label: '繁體中文',
    lang: 'zh-TW',
    oglocale: 'zh_TW',
    path: 'zh-tw',
  },
};

Implementierung des Sprachwechsels

Das Sprachauswahl-Dropdown wird ebenfalls aus der zuvor erstellten i18n-Konfigurationsdatei generiert. Da das label den Namen der jeweiligen Auswahloption enthält, soll es nicht übersetzt werden. Deshalb habe ich eine Verarbeitung ergänzt, die die Werte durch den label-Wert überschreibt. (translate="no" wirkt bei der Cloud Translation API leider nicht.)

Übrigens: Als ich den Vorschlag bekam, Flaggen in das Dropdown aufzunehmen, habe ich das versucht. Bei Sprachwechslern sind Flaggen jedoch ein Anti-Pattern. Sprache und Land stimmen nicht immer überein. Ein deutschsprachiger Nutzer in Österreich könnte zum Beispiel durch die deutsche Flagge verwirrt werden. Im Nachhinein leuchtet das ein. Je nach Situation kann das auch zu einem heiklen Thema werden.

Durch Caching wird die API-Nutzung auf das Nötigste reduziert.

Damit ist die Mechanik zur Generierung mehrsprachiger Inhalte weitgehend fertig. Das eigentliche Problem sind die Kosten.

Bei zahlreichen Build-Durchläufen beim Ausprobieren und Optimieren war die API-Nutzungsgebühr plötzlich über 10.000 Yen gestiegen.

Deshalb werden die über die API verarbeiteten Kombinationen aus japanischem Text und Übersetzung beim Build als Cache in einer Datei namens translate-cache.json gespeichert. Beim nächsten Build werden die Übersetzungen aus dieser JSON-Datei angewendet. Nur fehlende Einträge werden noch über die API abgefragt, und die Ergebnisse werden anschließend in die JSON-Datei ergänzt.

So werden die Daten gespeichert.

{
  "en:UIデザイン": "UI Design",
  "en:私たちについて": "About Us",
  "en:サービス": "Service",
  ...
}

Dadurch sinken die Kosten erheblich! Je nach Aktualisierungshäufigkeit bleiben die laufenden Kosten im Bereich von einigen hundert Yen pro Monat.

Hinweise zum Betrieb

Wenn Artikel im CMS hinzugefügt und über einen Deploy-Hook gebaut werden, kann der Server nur die alten Cache-Dateien referenzieren, die in Git liegen. Deshalb haben wir uns entschieden, konsequent die Betriebsregel durchzusetzen: Bei neuen Inhalten wird lokal gebaut und die aktualisierten Cache-Dateien werden anschließend in Git gepusht.

Fehlerhafte Übersetzungen kontrollieren

Typisch maschinelle Übersetzung. Stellenweise tauchen seltsame Übersetzungen auf.
Der Firmenname „Liberogic“ wurde mal zu „Liberlogic“ oder „Libelogic“, und auch die Schreibweise der Rechtsformen (Inc., Ltd. usw.) war nicht einheitlich. Bei Eigennamen fielen die inkonsistenten Schreibweisen deutlich auf.

Cloud Translation API bietet zwar eine Glossarfunktion, diese unterstützt die maschinelle Übersetzung jedoch nur und erlaubt keine vollständige, feingranulare Kontrolle. Zudem reicht das Hochladen einer CSV-Datei nicht aus: Bei jeder Änderung müssen Befehle ausgeführt und Ressourcen neu erstellt werden, was für Betreuer ohne Webkenntnisse schwer umsetzbar ist.

Verlässliche Kontrolle über eine Tabellenkalkulations-Integration

Daher haben wir Sprachen und korrekte Schreibweisen in einer Tabelle zusammengeführt. Beim Build wird diese Tabelle als CSV abgerufen und per Textersetzung in die korrekte Schreibweise überschrieben.

Dadurch können Betreuer die Übersetzungen größtenteils steuern, indem sie einfach die Tabelle aktualisieren, ohne Code anfassen zu müssen.

Fazit

Die automatische Übersetzung mit der Google Cloud Translation API ist nach einigen Versuchen praxistauglicher geworden, als wir erwartet hatten. Für eine kostengünstige, unkomplizierte und einfache Mehrsprachigkeit halte ich sie für völlig ausreichend!

(Der Chef möchte auch RTL-Arabisch unterstützen, das wird ein großer Umbau.)