Traducir un sitio Astro SSG a varios idiomas con la API de Google Translate

Un día, nuestro presidente nos dijo: "Oye, ¡deberíamos hacer multilingüe nuestro sitio! Parece que existe una API de Google Cloud Translation que puede traducir automáticamente durante la compilación."

Nuestro sitio web es un sitio estático (SSG) construido con Astro. Decidimos investigar la API de Google Cloud Translation mientras la implementábamos.

Preparación previa: habilitar la clave de API y crear una cuenta de servicio

Habilitar la API de Cloud Translation

En la consola de Google Cloud, habilite "Cloud Translation API" desde "APIs y servicios".

Crear una cuenta de servicio y una clave

Para usar la API, cree una cuenta de servicio y descargue la clave JSON.

Esta clave JSON contiene una clave privada, así que hay que tener mucho cuidado de no publicarla nunca.

Conceder acceso a la cuenta de servicio

Vaya a IAM y añada la dirección de correo electrónico de la cuenta de servicio como entidad principal, con el rol "Cloud Translation API User".

Cómo generar páginas multilingües

El primer enfoque que probamos fue copiar los archivos de Astro y llamar a la API de traducción sobre la marcha para generar automáticamente archivos Astro multilingües.

Aunque se pudieron generar las páginas, surgieron problemas: los bloques de código se rompían, los componentes importados no se podían manejar y no funcionaba bien cuando había etiquetas dentro de atributos, por lo que cambiamos de enfoque.

Al final optamos por un sencillo proceso postbuild que traduce el HTML estático generado después de la compilación.

La configuración de idiomas está vinculada al archivo de configuración i18n de Astro

Para gestionar la estructura multilingüe del sitio, reutilizamos el archivo de configuración i18n de Astro que ya teníamos (LOCALES_SETTING) como "archivo de configuración" del script de traducción.

Para añadir un idioma, basta con agregarlo aquí.

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

Implementación del cambio de idioma

El desplegable de selección de idioma también se genera a partir del archivo de configuración i18n mencionado antes. Como el label es el nombre de la opción seleccionable, no queremos traducirlo. Por eso añadimos un proceso que sobrescribe el valor con el label. (Resulta que translate="no" no funciona con Cloud Translation API).

Por cierto, cuando me dijeron "pongamos banderas en el desplegable", intenté añadirlas, pero resulta que usar banderas para el cambio de idioma es un antipatrón. Por ejemplo, si un hablante de alemán es un usuario de Austria, podría confundirse al ver la bandera de Alemania. Es decir, país e idioma no siempre coinciden. Pensándolo bien, tiene sentido. Según el caso, también podría convertirse en un tema delicado.

Almacenar en caché y minimizar el uso de la API

Hasta aquí, el mecanismo de generación multilingüe está prácticamente completo. Pero el problema es el coste.

Tras compilar muchas veces mediante prueba y error, el uso de la API superó los 10,000 yenes en muy poco tiempo.

Por eso, durante la compilación se guardan como caché las combinaciones de japonés y traducción procesadas por la API en un archivo llamado translate-cache.json. En la siguiente compilación, se aplican desde este JSON. Se cambió la especificación para llamar a la API solo para lo que no existe y añadir el resultado al JSON.

Así es como se guarda.

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

Con esto, el coste se reduce considerablemente. Dependiendo de la frecuencia de actualización, el coste operativo mensual se mantiene en unos pocos cientos de yenes.

Notas operativas

Si se añaden artículos en el CMS y el build se activa mediante un deploy hook, el servidor solo puede consultar los archivos de caché antiguos que están en Git. Por ese motivo, decidimos establecer una regla operativa estricta: al añadir contenido, se realiza el build en local y luego se sube a Git el archivo de caché actualizado.

Controlar las traducciones extrañas

Al fin y al cabo, es traducción automática. Aparecen traducciones extrañas aquí y allá.
El nombre de nuestra empresa, "Liberogic", aparecía como "Liberlogic" o "Libelogic", y las formas de la forma jurídica (Inc., Ltd., etc.) no estaban unificadas. Las inconsistencias en los nombres propios eran muy evidentes.

Cloud Translation API cuenta con una función de glosario, pero solo asiste a la traducción automática y no permite un control detallado y completo. Además, no basta con subir un CSV: hay que ejecutar un comando cada vez para volver a crear los recursos, lo cual resulta difícil para el personal de operaciones sin conocimientos de web.

Control fiable mediante integración con hojas de cálculo

Por ello, reunimos los idiomas y las versiones correctas en una hoja de cálculo, obtenemos esa hoja en formato CSV durante el build y realizamos un reemplazo de texto, de modo que las expresiones se puedan corregir con la forma correcta.

Gracias a esto, el personal de operaciones puede controlar en cierta medida las traducciones simplemente actualizando la hoja de cálculo, sin tocar el código.

Conclusión

La traducción automática con Google Cloud Translation API, tras muchos ensayos y errores, terminó siendo un sistema más práctico de lo que esperábamos. Creo que es suficiente como una forma sencilla y económica de hacer un sitio multilingüe.

(El presidente dice que también quiere soportar árabe con RTL, pero eso supondrá una gran obra...)