Astro SSG-Website mit Google Translate API mehrsprachig gemacht

Eines Tages bekam ich vom CEO die Anweisung: „Lass uns unsere Website mehrsprachig machen. Es soll da eine Google Cloud Translation API geben, mit der wir beim Build automatisch übersetzen können!"

Unsere Website ist eine statische Website (SSG), die mit Astro aufgebaut wurde. Wir haben uns entschieden, sie zu implementieren, während wir die Google Cloud Translation API untersuchen.

Vorbereitung: API-Schlüssel aktivieren und Service-Konto erstellen

Cloud Translation API aktivieren

Aktivieren Sie die Cloud Translation API über „APIs und Services" in der Google Cloud Console.

Erstellen Sie ein Dienstkonto und einen Schlüssel

Um die API zu nutzen, erstellen Sie ein Service-Konto und laden Sie den JSON-Schlüssel herunter.

Dieser JSON-Schlüssel enthält einen geheimen Schlüssel und darf auf keinen Fall öffentlich gemacht werden.

Zugriffsberechtigung für Dienstkonto erteilen

Navigieren Sie zu IAM, fügen Sie die E-Mail-Adresse des Dienstkontos als Principal hinzu und weisen Sie die Rolle „Cloud Translation API User" zu.

Mehrsprachige Seiten generieren – So funktioniert's

Zuerst versuchten wir den Ansatz: „Astro-Dateien kopieren, dann direkt eine Übersetzungs-API aufrufen und mehrsprachige Astro-Dateien automatisch generieren."

Die Seite konnte zwar generiert werden, aber es gab verschiedene Probleme: Code-Fence-Bereiche wurden beschädigt, importierte Komponenten konnten nicht verarbeitet werden, und Tags innerhalb von Attributen funktionierten nicht richtig. Da diese Probleme nicht zu lösen waren, haben wir unseren Ansatz geändert.

Am Ende haben wir uns für einen einfachen postbuild-Prozess entschieden – nämlich die Durchführung der Übersetzungsverarbeitung auf der nach dem Build generierten statischen HTML.

Die Spracheinstellung ist mit der i18n-Konfigurationsdatei von Astro verknüpft

Um die mehrsprachige Struktur der Website zu verwalten, verwendeten wir die ursprüngliche Astro-i18n-Konfigurationsdatei (LOCALES_SETTING) als „Konfigurationsdatei" für das Übersetzungsskript.

Wenn Sie eine Sprache hinzufügen möchten, fügen Sie sie einfach hier hinzu.

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 der Sprachumschaltung

Das Sprachauswahlmenü wird ebenfalls aus der i18n-Konfigurationsdatei von eben generiert. Das Label entspricht dem Namen des Auswahlpunkts, daher möchten wir es nicht übersetzen. Deshalb habe ich eine Verarbeitung hinzugefügt, die den Label-Wert überschreibt. (Es stellt sich heraus, dass translate="no" bei Cloud Translation API nicht funktioniert.)

Übrigens habe ich versucht, Landesflaggen in das Dropdown-Menü einzufügen, wie mir geraten wurde, aber es scheint, dass Flaggen bei der Sprachweiterleitung ein Antimuster darstellen. Wenn beispielsweise ein deutschsprachiger Nutzer ein Benutzer aus Österreich ist, könnte die deutsche Flagge verwirrend wirken – Länder und Sprachen stimmen nicht immer überein. Wenn ich es mir recht überlege, ist das tatsächlich nachvollziehbar. In manchen Fällen könnte dies auch ein sensibles Thema darstellen.

Caching zur Minimierung der API-Nutzung

Bis hierher ist der Mechanismus für mehrsprachige Generierung praktisch vollständig. Das Problem ist jedoch die Kosten.

Nach vielen Trial-and-Error-Builds während der Entwicklung überstieg die API-Nutzungsgebühr schnell 10.000 Yen.

Daraufhin habe ich während des Builds die von der API verarbeiteten japanischen Texte und deren Übersetzungen als Cache in einer Datei namens translate-cache.json gespeichert und diese JSON beim nächsten Build angewendet. Die Spezifikation wurde geändert, um nur API-Aufrufe für fehlende Einträge zu tätigen und die Ergebnisse der JSON hinzuzufügen.

So wird es gespeichert.

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

Dies reduzierte die Kosten erheblich! Je nach Aktualisierungshäufigkeit liegen die laufenden Kosten bei nur wenigen hundert Yen pro Monat.

Betriebliche Überlegungen

Wenn Artikel im CMS hinzugefügt werden und ein Deploy-Hook einen Build auslöst, kann der Server nur auf die alte Cache-Datei in Git verweisen. Um dieses Problem zu vermeiden, habe ich eine strikte Betriebsregel eingeführt: Bei jedem neuen Inhalt lokal bauen, die aktualisierte Cache-Datei zu Git pushen.

Kontrolle fehlerhafter Übersetzungen

Eben maschinelle Übersetzung. Hier und da entstehen merkwürdige Übersetzungen.
Der Unternehmensname „Liberogic" verwandelt sich in „Liberlogic" oder „Libelogic", und die Rechtsformbezeichnungen (Inc., Ltd. usw.) sind inkonsistent – bei den Eigennamen fielen die Schreibvariationen besonders auf.

Cloud Translation API verfügt zwar über eine Glossarfunktion, doch diese dient nur der Unterstützung maschineller Übersetzungen und ermöglicht keine umfassende Kontrolle im Detail. Darüber hinaus ist es nicht ausreichend, nur eine CSV-Datei hochzuladen – bei jeder Aktualisierung müssen Befehle ausgeführt und Ressourcen neu erstellt werden, was für Betriebsleiter ohne Webtechnologie-Kenntnisse schwierig ist.

Sichere Steuerung durch Tabellenkalkulationsintegration

Deshalb haben wir die Sprachen und die Korrektheit in einer Tabelle zusammengefasst, diese Tabelle zum Zeitpunkt des Builds im CSV-Format abgerufen und einen Textersetzungsprozess durchgeführt, um die Einträge mit der korrekten Schreibweise zu überschreiben.

Dadurch können Betriebsleiter Übersetzungen bis zu einem gewissen Grad kontrollieren, indem sie einfach Tabellenkalkulationen aktualisieren, ohne den Code anfassen zu müssen.

Fazit

Wir haben die automatische Übersetzung mit der Google Cloud Translation API ausprobiert und sind überraschend zu einer praktischen Lösung gelangt. Für eine kostengünstige und unkomplizierte Mehrsprachigkeit halten wir das für vollkommen ausreichend!

(Der CEO möchte auch RTL-Arabisch unterstützen, aber das wird ein großes Projekt...)