Mise en place multilingue d'un site Astro SSG avec l'API Google Translate

Un jour, notre PDG nous a lancé : « Et si on rendait notre site multilingue ? Il paraît qu'il existe une API, Google Cloud Translation, qui permet de traduire automatiquement pendant le build ! »

Notre site est un site statique (SSG) construit avec Astro. Nous avons donc décidé de l'implémenter tout en étudiant l'API Google Cloud Translation.

Préparation : activation de la clé API et création d'un compte de service

Activation de Cloud Translation API

Dans la console Google Cloud, activez « Cloud Translation API » depuis « API et services ».

Création d'un compte de service et d'une clé

Pour utiliser l'API, créez un compte de service puis téléchargez la clé JSON.

Cette clé JSON contient une clé privée : veillez à ne jamais la rendre publique.

Attribuer l'accès au compte de service

Accédez à IAM et ajoutez l'adresse e-mail du compte de service en tant que principal, avec le rôle « Utilisateur de Cloud Translation API ».

Comment générer les pages multilingues

La première approche testée consistait à copier le fichier Astro, à appeler directement l'API de traduction et à générer automatiquement des fichiers Astro multilingues.

Si les pages ont bien pu être générées, des problèmes sont apparus : les blocs de code étaient cassés, les composants importés n'étaient pas pris en charge, et les cas où des balises figuraient dans des attributs ne fonctionnaient pas correctement. J'ai donc changé d'approche.

Au final, j'ai opté pour un traitement postbuild simple, qui traduit le HTML statique généré après la compilation.

Paramètres de langue synchronisés avec le fichier i18n d'Astro

Pour gérer la structure multilingue du site, j'ai utilisé le fichier de configuration i18n d'Astro existant (LOCALES_SETTING) comme « fichier de configuration » du script de traduction.

Pour ajouter une langue, il suffit d'ajouter une entrée ici.

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

Implémentation du changement de langue

Le menu déroulant de sélection de langue est également généré à partir du fichier de configuration i18n évoqué précédemment. Comme le label correspond au nom de chaque option de langue, je ne souhaite pas le traduire. J'ai donc ajouté un traitement qui remplace la valeur par le label d'origine. (Il s'avère que translate="no" n'a aucun effet avec Cloud Translation API.)

Au passage, on m'a demandé d'ajouter des drapeaux dans le menu déroulant. Après essai, j'ai constaté que les drapeaux dans un sélecteur de langue constituent un anti-pattern. Par exemple, un germanophone résidant en Autriche pourrait être déconcerté en voyant le drapeau allemand. Un pays et une langue ne correspondent pas forcément. C'est évident une fois qu'on y pense. Dans certains cas, cela peut même devenir une question sensible.

Mise en cache pour limiter le recours à l'API au strict minimum

À ce stade, le mécanisme de génération multilingue est quasiment terminé. Reste le problème du coût.

Après de nombreux essais et builds successifs, le coût d'utilisation de l'API a rapidement dépassé 10 000 yens.

Je me suis donc orienté vers une mise en cache lors du build : les combinaisons de textes japonais et de traductions traitées par l'API sont enregistrées dans un fichier translate-cache.json. Lors du build suivant, les traductions sont appliquées depuis ce JSON. Seuls les textes absents du cache sont envoyés à l'API, et les résultats sont ajoutés au JSON.

Voici à quoi ressemble la sauvegarde.

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

Cela réduit considérablement les coûts ! Selon la fréquence des mises à jour, les frais d'exploitation restent de quelques centaines de yens par mois.

Points d'attention pour l'exploitation

Lorsqu'un article est ajouté dans le CMS et que le build est déclenché par un deploy hook, le serveur ne peut accéder qu'aux anciens fichiers de cache présents sur Git. Nous avons donc décidé d'appliquer strictement une règle opérationnelle : lors de l'ajout de contenu, le build est effectué en local, puis les fichiers de cache mis à jour sont poussés sur Git.

Contrôler les traductions incohérentes

Il s'agit toujours de traduction automatique, et certaines traductions bizarres apparaissent çà et là.
Les incohérences de graphie sont particulièrement visibles dans les noms propres : le nom de notre société, « Liberogic », devient parfois « Liberlogic » ou « Libelogic », et les formes juridiques (Inc., Ltd., etc.) ne sont pas harmonisées.

Google Cloud Translation API dispose bien d'une fonction de glossaire, mais elle ne fait qu'assister la traduction automatique et ne permet pas un contrôle fin et complet. De plus, il ne suffit pas d'importer un CSV : il faut exécuter une commande et recréer les ressources à chaque fois, ce qui est difficile à gérer pour les équipes opérationnelles peu familiarisées avec le web.

Un contrôle fiable grâce à l'intégration de Google Sheets

Nous avons donc regroupé les langues et les corrections dans une feuille de calcul. Au moment du build, cette feuille est récupérée au format CSV, puis un traitement de remplacement de texte corrige les termes avec la graphie correcte.

Ainsi, les équipes opérationnelles peuvent, en mettant simplement à jour la feuille de calcul, contrôler dans une certaine mesure les traductions sans toucher au code.

Conclusion

Après plusieurs essais et erreurs, nous avons mis en place un dispositif plus utile que prévu pour la traduction automatique avec Google Cloud Translation API. Nous estimons qu'il est tout à fait suffisant pour un passage au multilingue simple et économique !

(Le président souhaite aussi prendre en charge l'arabe, langue de droite à gauche (RTL), mais cela représentera un chantier important…)