Translating an Astro SSG Site into Multiple Languages with the Google Translate API

One day, our president said, "Let's make our website multilingual. I heard there's a Google Cloud Translation API that can translate automatically at build time!"

Our website is a static site (SSG) built with Astro. While researching the Google Cloud Translation API, we decided to try implementing it.

Preparation: Enabling the API Key and Creating a Service Account

Enabling the Cloud Translation API

In the Google Cloud Console, enable the "Cloud Translation API" under "APIs & Services".

Creating a Service Account and Key

To use the API, create a service account and download a JSON key.

This JSON key contains a private key, so be careful never to make it public.

Grant access rights to the service account

Go to IAM and add the service account's email address as a principal, with the role set to "Cloud Translation API User."

How to Generate Multilingual Pages

My first approach was to copy the Astro files, call the translation API on the spot, and automatically generate multilingual Astro files.

Although the pages were generated, the code fences broke, imported components could not be handled, and tags written inside attributes caused problems. These issues led me to change direction.

In the end, I settled on a simple postbuild process that translates the static HTML generated after the build.

Language settings linked to Astro's i18n configuration file

To manage the site's multilingual structure, I used Astro's existing i18n configuration file (LOCALES_SETTING) as the translation script's "settings file."

To add a language, just append it here.

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

Implementing Language Switching

The language selection dropdown is also generated from the i18n configuration file I mentioned earlier. Since the label is the name of each option, I don't want it translated. So I added logic to override it with the label value. (It turns out translate="no" doesn't work with the Cloud Translation API.)

By the way, when someone suggested "Let's put flags in the dropdown," I tried it, but it seems that using flags for language switching is an anti-pattern. For example, if a German speaker is a user in Austria, they might be confused by seeing the German flag. In other words, countries and languages don't always match. Now that I think about it, that makes sense. Depending on the case, it could even become a sensitive issue.

Cache results to keep API usage to a minimum

With this, the multilingual generation mechanism is nearly complete. The problem, however, is cost.

While repeatedly building through trial and error, my API usage fees quickly exceeded 10,000 yen.

To address this, during the build I now save the Japanese text processed by the API and its translation pairs to a file called translate-cache.json. The next build applies translations from this JSON. The specification was changed so that the API is only called for items not already present, and the results are appended to the JSON.

It is saved in the following format.

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

This significantly reduces costs! Depending on update frequency, running costs come to a few hundred yen per month.

Operational Notes

When articles are added in the CMS and built via a deploy hook, the server can only reference the outdated cache files stored in Git. For this reason, we established a firm operational rule: when content is added, a local build is performed, and the updated cache files are pushed to Git.

Controlling strange translations

It was still machine translation, and some of the output was off.
Inconsistencies in proper nouns were especially noticeable: our company name "Liberogic" sometimes appeared as "Liberlogic" or "Libelogic," and corporate suffixes (Inc., Ltd., etc.) were not applied consistently.

Cloud Translation API has a glossary feature, but it only assists machine translation and cannot provide fully granular control. In addition, rather than simply uploading a CSV, you must run a command and recreate resources every time, which is difficult for operations staff who are not familiar with the web.

Reliable control through spreadsheet integration

We therefore compiled languages and correct terminology in a spreadsheet, retrieved this spreadsheet in CSV format at build time, and ran a text replacement process to overwrite the output with the correct wording.

As a result, operations staff can now control translations to a certain degree simply by updating the spreadsheet, without touching any code.

Summary

After much trial and error, we built an automatic translation system using the Google Cloud Translation API that is more practical than we expected. I think it is more than sufficient as a low-cost, simple way to make a site multilingual!

(The president also wants to support right-to-left Arabic, but that would be a major undertaking...)