Astro SSG-website meertalig maken met Google Translate API

Op een dag kregen we van de directeur de opdracht: "We moeten onze website meertalig maken. Er schijnt iets te zijn dat Google Cloud Translation API heet waarmee we automatisch kunnen vertalen tijdens het bouwen!"

Onze website is gebouwd met Astro, een statische site (SSG). We besloten Google Cloud Translation API te onderzoeken en te implementeren.

Voorbereiding: API-sleutel activeren en serviceaccount maken

Cloud Translation API activeren

In de Google Cloud Console activeren we Cloud Translation API via "API's en Services".

Serviceaccount en sleutel maken

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

Deze JSON-sleutel bevat een geheime sleutel en mag onder geen omstandigheden openbaar worden gemaakt.

Toegangsrechten toekennen aan de serviceaccount

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

Hoe genereer je meertalige pagina's?

De eerste aanpak was: "Astro-bestanden kopiëren, ter plaatse de vertaal-API aanroepen en automatisch meertalige Astro-bestanden genereren".

De pagina's werden gegenereerd, maar codefences werden beschadigd, geïmporteerde componenten konden niet worden verwerkt, en tags in attributen werkten niet goed. Dit zorgde voor veel problemen, dus hebben we onze aanpak gewijzigd.

Uiteindelijk hebben we gekozen voor een eenvoudige postbuild-verwerking: "Vertaalverwerking toepassen op gegenereerde statische HTML na het bouwen".

Taalinstelling synchroon met Astro i18n-configuratie

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

Wil je een taal toevoegen? Voeg het eenvoudig toe aan dit bestand.

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 taalswitching

Het dropdown-menu voor taalselectie wordt ook gegenereerd op basis van het i18n-configuratiebestand. We willen het label niet vertalen omdat het de naam van de geselecteerde optie weergeeft. Daarom hebben we een proces toegevoegd dat de labelwaarde overschrijft. (translate="no" werkt blijkbaar niet met Cloud Translation API)

Trouwens, iemand stelde voor om landvlaggen in de dropdown te zetten, dus ik ging dat proberen. Maar het blijkt dat het gebruik van vlaggen voor taalswitching een anti-patroon is. Bijvoorbeeld: als een Duitstalige spreker een gebruiker in Oostenrijk is, kunnen ze in verwarring raken door de Duitse vlag. Land en taal komen niet altijd overeen. Nu je het zegt, klopt dat inderdaad. In sommige gevallen kan dit gevoelig liggen.

Caching implementeren om API-gebruik te minimaliseren

Tot nu toe is het systeem voor meertalige generatie vrijwel voltooid. Maar het probleem is de kosten.

Na veel experimenteren en herhaalde builds was ik al snel voorbij de 10.000 yen aan API-kosten.

Daarom sla ik tijdens het build-proces de combinatie van Japanse inhoud en vertalingen op in een cachbestand genaamd translate-cache.json. Bij de volgende build pas ik de gegevens uit deze JSON toe. Alleen voor nieuwe items maak ik een API-aanroep en voeg ik het resultaat toe aan de JSON.

Het wordt op deze manier opgeslagen.

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

Hierdoor worden de kosten aanzienlijk verlaagd! Afhankelijk van de updatefrequentie bedragen de maandelijkse kosten slechts enkele honderden yen.

Aandachtspunten bij onderhoud

Als we artikelen in de CMS toevoegen en met een deploy hook buildproces activeren, kan de server alleen verwijzen naar het oude cachbestand dat op Git staat. Om deze reden hebben we een operationeel protocol ingesteld: wanneer we inhoud toevoegen, moet het build-proces lokaal worden uitgevoerd, en moet het bijgewerkte cachbestand naar Git worden gepusht.

Onjuiste vertalingen beheren

Inderdaad machinevertaling. Op veel plaatsen komen vreemde vertalingen voor.
Onze eigen bedrijfsnaam "Liberogic" werd inconsistent weergegeven als "Liberlogic" of "Libelogic", en ook juridische aanduidingen (Inc., Ltd. enzovoort) waren niet uniform — er waren veel schrijfvariaties in eigennamen op te merken.

Cloud Translation API heeft een woordenlijstfunctie, maar deze ondersteunt alleen machinevertaling en biedt niet de volledige nauwkeurige controle. Bovendien moet je niet alleen een CSV uploaden, maar ook telkens commando's uitvoeren om resources opnieuw aan te maken — voor operationeel personeel zonder webachtergrond is dit lastig.

Nauwkeurige controle via spreadsheetintegratie

Daarom hebben we de talen en correcties in een spreadsheet verzameld en deze tijdens de build als CSV opgehaald. Vervolgens voerden we tekstvervanging uit om de juiste schrijfwijzen in te voeren.

Hierdoor kunnen operationeel medewerkers eenvoudigweg het spreadsheet bijwerken en tot op zekere hoogte vertalingen beheren zonder code aan te raken.

Samenvatting

De automatische vertaling via Google Cloud Translation API werkte, ondanks veel trial-and-error, uiteindelijk veel praktischer dan verwacht. Voor kosteneffectieve en eenvoudige meertalige ondersteuning is dit zeker voldoende!

(De directeur wil ook RTL Arabisch ondersteunen, maar dat wordt een grote klus...)