Topics

One day, the president gave me the order, "Let's make our website multilingual. Apparently there's a Google Cloud Translation API that can automatically translate during the build process!"

Our website is a static site (SSG) built with Astro. We decided to research the Google Cloud Translation API and implement it.

Prerequisites: Activating an API key and creating a service account

Enabling the Cloud Translation API

Google Cloud ConsoleFrom "APIs and Services," select "Cloud Translation API."Enable

Creating a service account and key

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

This JSON key contains your private key, so be extremely careful not to disclose it.

Grant access rights to the service account.

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

How to generate multilingual pages

The first method I tried was to "copy the Astro file, call the translation API on the spot, and automatically generate multilingual Astro files."

Although the page was generated, we encountered several issues, such as broken code fences, incompatibility with imported components, and problems when tags were written within attributes, so we changed our approach.

Ultimately, I opted for a simple post-build process that performs translation on the static HTML generated after the build.

Language settings are linked to Astro's i18n configuration file.

To manage the multilingual structure of the site, I used the original Astro i18n configuration file (LOCALES_SETTING) was used as the "configuration file" for the translation script.

To add a language, simply add 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 the language switcher

The language selection dropdown is also generated from the i18n configuration file mentioned earlier. Since the label becomes the name of the selected item, we don't want to translate it. Therefore, we've added code to override it with the label's value. (It seems `translate="no"` doesn't work with the Cloud Translation API.)

By the way, I was told to "put national flags in the dropdown," so I tried to do that, but it seems that using national flags for language switching is an anti-pattern. For example, if a German-speaking user is an Austrian user, they might be confused by the German flag, so countries and languages ​​don't necessarily match. Now that you mention it, that's true. It could be a sensitive issue in some cases.

Caching to minimize API usage

At this point, the system for generating multiple languages ​​is almost complete, but the problem is the cost.

As I tried various things and built it many times, the API usage fee quickly exceeded 10,000 yen.

Therefore, during the build process, the combination of Japanese and translation processed by the API is used as a cache.translate-cache.jsonThe data will be saved in a file, and the next build will use this JSON. The specification has been changed so that only the missing data is called via the API, and the results are appended to the JSON.

It will be saved like this.

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

This significantly reduces costs! Depending on the update frequency, running costs will be only a few hundred yen per month.

Operational Notes

When adding an article in the CMS and building it with a deploy hook, the server can only refer to the old cache file on Git. Therefore, we decided to strictly enforce the operational rule of building locally when adding content and pushing the updated cache file to Git.

Controlling strange translations

As expected from machine translation, there are some strange translations here and there.
There was noticeable variation in the spelling of proper nouns, such as the company name "Liberogic" being inconsistently written as "Liberogic" or "Liberogic," and the spelling of corporate entities (Inc., Ltd., etc.) not being consistent.

The Cloud Translation API has a glossary feature, but it only assists machine translation and doesn't offer complete, granular control. Furthermore, it requires not only uploading a CSV file but also running commands to recreate resources each time, making it difficult for operations staff unfamiliar with the web.

Reliable control through spreadsheet integration

Therefore, we compiled the languages ​​and typos in a spreadsheet, retrieved this spreadsheet in CSV format during the build, and performed a text replacement process so that the notation could be overwritten and corrected.

This means that administrators can control translations to some extent simply by updating a spreadsheet, without having to touch any code.

summary

After some trial and error, I was able to create a more practical system using the Google Cloud Translation API for automatic translation than I expected. For cost-effective and simple multilingual support, I think it's perfectly adequate!

(The president says he wants to add Arabic language support to RTL, but that's going to be a major project.)