Hicimos multilingüe un sitio Astro SSG con la API de Google Translate

Un día, el presidente nos dio la orden: "Vamos a multiidiomdizar nuestro sitio web. Al parecer existe Google Cloud Translation API que puede traducir automáticamente durante la compilación."

Nuestro sitio está construido con Astro como un sitio estático (SSG). Decidimos investigar Google Cloud Translation API e implementarlo.

Preparación previa: activación de claves API y creación de cuentas de servicio

Habilitación de Cloud Translation API

Habilitar Cloud Translation API desde "APIs y servicios" en Google Cloud Console.

Creación de cuenta de servicio y clave

Para utilizar la API, crea una cuenta de servicio y descarga la clave JSON.

Esta clave JSON contiene una clave privada; asegúrate de nunca hacerla pública.

Otorgar permisos de acceso a la cuenta de servicio

Ve a IAM y añade la dirección de correo electrónico de la cuenta de servicio al principal con el rol "Cloud Translation API User".

Cómo generar páginas multilingües

El primer enfoque que probé fue "copiar archivos Astro, llamar a la API de traducción in situ y generar automáticamente archivos Astro multilingües".

Se generó la página, pero surgieron problemas: las secciones de código se rompieron, los componentes importados no se podían traducir y las etiquetas dentro de atributos no funcionaban bien. Por eso cambié de estrategia.

Al final opté por un postbuild sencillo: "realizar la traducción en el HTML estático generado después de la compilación".

La configuración de idioma se vincula con la configuración i18n de Astro

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

Si quieres añadir un idioma, solo tienes que 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 menú desplegable de selección de idioma también se genera desde el archivo de configuración i18n. Dado que el label es el nombre del elemento seleccionado, no quiero traducirlo. Por eso añadí un proceso para sobrescribir el valor del label. (Parece que translate="no" no funciona con Cloud Translation API)

Por cierto, me pidieron que añadiera banderas en el menú desplegable de idiomas e intenté hacerlo, pero parece que 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. En otras palabras, el país y el idioma no siempre coinciden. Ahora que lo mencionas, tienes razón. En algunos casos podría convertirse en un tema delicado.

Almacenar en caché para minimizar el uso de API

Hasta aquí, el mecanismo de generación multilingüe estaba prácticamente completo. Sin embargo, el problema era el costo.

Mientras realizaba varias pruebas y compilaba una y otra vez, los costos de uso de API superaron rápidamente los 10.000 yenes.

Así que durante la compilación, guardé en caché las combinaciones de japonés y traducción procesadas por API en un archivo llamado translate-cache.json, y en la siguiente compilación apliqué desde este JSON. Cambié la especificación para que solo consultara la API para los elementos que no existían y añadiera los resultados al JSON.

Se guarda de esta manera.

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

Con esto, ¡reducimos significativamente los costos! Dependiendo de la frecuencia de actualización, los costos operativos se mantienen en unos pocos cientos de yenes al mes.

Consideraciones operacionales

Cuando se añade un artículo en el CMS y se dispara una compilación mediante un webhook de despliegue, el servidor solo puede hacer referencia al archivo de caché antiguo que existe en Git. Por eso, establecimos una regla operativa estricta: cuando se añade contenido, compilar localmente y luego insertar el archivo de caché actualizado en Git.

Controlar traducciones incorrectas

Al fin y al cabo, traducción automática. Aparecen errores de traducción aquí y allá.
El nombre de nuestra empresa "Liberogic" se escribía de manera inconsistente como "Liberlogic" o "Libelogic", y había falta de uniformidad en la notación de la forma legal (Inc., Ltd., etc.), lo que resultaba en variaciones notables en los nombres propios.

Cloud Translation API tiene una función de glosario, pero solo asiste la traducción automática sin permitir un control detallado completo. Además de cargar CSV, es necesario ejecutar comandos cada vez para recrear los recursos, lo que resulta difícil para los responsables de operaciones sin experiencia en desarrollo web.

Control confiable a través de integración con hojas de cálculo

Entonces, consolidamos el idioma y las correcciones en una hoja de cálculo, y al momento de compilar, obtenemos esta hoja de cálculo en formato CSV, realizamos un procesamiento de reemplazo de texto y así podemos sobrescribir la notación correcta.

Con esto, los responsables de operaciones pueden controlar la traducción hasta cierto punto simplemente actualizando la hoja de cálculo, sin tocar el código.

Conclusión

La traducción automática con Google Cloud Translation API, aunque requirió prueba y error, resultó ser un sistema más práctico de lo esperado. Para una multilingüe sencilla y económica, considero que es más que suficiente.

(El presidente quiere que también soportemos árabe RTL, pero eso será una obra importante...)