Astro SSG-site meertalig gemaakt met de Google Translate API

Op een dag kwam de president met de opdracht: "Laten we onze site meertalig maken. Er is blijkbaar een Google Cloud Translation API waarmee we tijdens het bouwen automatisch kunnen vertalen!"

Onze website is gebouwd als statische site (SSG) met Astro. We onderzochten de Google Cloud Translation API en besloten deze te implementeren.

Voorbereiding: API-sleutel activeren en een serviceaccount aanmaken

De Cloud Translation API activeren

Activeer de "Cloud Translation API" via "APIs en services" in de Google Cloud Console.

Een serviceaccount en sleutel aanmaken

Om de API te gebruiken, maken we een serviceaccount aan en downloaden we een JSON-sleutel.

Let op: deze JSON-sleutel bevat een geheime sleutel en mag nooit openbaar worden gemaakt.

Toegang verlenen aan het serviceaccount

Ga naar IAM en voeg het e-mailadres van het serviceaccount toe als principal, met de rol "Cloud Translation API User".

Hoe we meertalige pagina's genereren

De eerste aanpak was: het Astro-bestand kopiëren, de vertaal-API direct aanroepen en automatisch meertalige Astro-bestanden genereren.

De pagina's konden worden gegenereerd, maar het codeblok raakte beschadigd, geïmporteerde componenten werden niet goed verwerkt en tags binnen attributen gaven problemen. Omdat dit op meerdere punten misliep, zijn we van aanpak veranderd.

Uiteindelijk hebben we gekozen voor een eenvoudige postbuild-stap: de vertaling wordt uitgevoerd op de gegenereerde statische HTML na de build.

Taalinstellingen gekoppeld aan het i18n-configuratiebestand van Astro

Om de meertalige structuur van de site te beheren, gebruiken we het bestaande i18n-configuratiebestand van Astro (LOCALES_SETTING) als 'configuratiebestand' voor het vertaalscript.

Wilt u een taal toevoegen? Dan hoeft u alleen maar hier een regel toe te voegen.

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',
  },
};

Implementatie van taalwisseling

Het taalkiezermenu wordt ook gegenereerd op basis van het eerdere i18n-configuratiebestand. Het label is de naam van de taal zelf, dus die wil ik niet vertalen. Daarom heb ik een verwerking toegevoegd die de waarde van het label als overschrijving gebruikt. (translate="no" werkt blijkbaar niet bij de Cloud Translation API.)

Overigens, toen ik werd gevraagd om vlaggen in het menu te plaatsen, probeerde ik dat, maar bleek het gebruik van vlaggen voor taalwisseling een antipatroon te zijn. Zo kan een Duissprekende gebruiker uit Oostenrijk verward raken door de Duitse vlag, omdat land en taal niet altijd samenvallen. Als je er zo over nadenkt, is dat inderdaad logisch. In sommige gevallen kan het zelfs een gevoelig onderwerp worden.

Cachen om het gebruik van de API tot een minimum te beperken

Tot hier is het mechanisme voor het genereren van meertalige content vrijwel klaar. Het probleem is echter de kosten.

Door herhaaldelijk te bouwen tijdens het experimenteren, liep de API-kosten ineens op tot meer dan 10.000 yen.

Daarom is de specificatie gewijzigd: tijdens het bouwen worden de combinaties van Japanse tekst en vertaling die via de API zijn verwerkt, als cache opgeslagen in een bestand genaamd translate-cache.json. Bij de volgende build wordt deze JSON gebruikt. Alleen voor ontbrekende items wordt de API aangeroepen, waarna het resultaat aan de JSON wordt toegevoegd.

Zo wordt het opgeslagen.

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

Hierdoor zijn de kosten sterk gedaald! Afhankelijk van hoe vaak de content wordt bijgewerkt, blijven de doorlopende kosten beperkt tot enkele honderden yen per maand.

Aandachtspunten voor het beheer

Wanneer artikelen worden toegevoegd in het CMS en er via een deploy hook wordt gebouwd, kan de server alleen de oude cachebestanden gebruiken die in Git staan. Daarom hebben we besloten een strikte werkwijze in te voeren: na het toevoegen van content wordt lokaal gebouwd en worden de bijgewerkte cachebestanden naar Git gepusht.

Foutieve vertalingen beheersen

Het blijft machinevertaling. Hier en daar verschijnen er foutieve vertalingen.
Onze bedrijfsnaam "Liberogic" verschoof naar "Liberlogic" of "Libelogic", en de schrijfwijze van rechtsvormen (Inc., Ltd., enz.) was niet consistent. Er waren dus duidelijke inconsistenties in eigennamen.

Cloud Translation API heeft een glossaryfunctie, maar die ondersteunt de machinevertaling alleen en biedt geen volledige, fijnmazige controle. Bovendien moet je niet alleen een CSV uploaden, maar ook telkens een commando uitvoeren om resources opnieuw aan te maken. Voor beheerders zonder webkennis is dat lastig.

Betrouwbare controle via een spreadsheetkoppeling

We hebben daarom talen en correcte schrijfwijzen in een spreadsheet samengebracht. Tijdens de build wordt deze spreadsheet als CSV opgehaald en worden teksten vervangen, zodat de juiste schrijfwijze kan worden afgedwongen.

Beheerders kunnen de vertalingen zo grotendeels sturen door alleen de spreadsheet bij te werken, zonder code aan te raken.

Conclusie

De automatische vertaling met Google Cloud Translation API is na vallen en opstaan praktischer uitgepakt dan verwacht. Voor een kostenefficiënte, eenvoudige meertalige oplossing vind ik het ruim voldoende!

(De CEO wil ook RTL-Arabisch ondersteunen, maar dat wordt een flinke klus.)