Maîtriser la traduction (i18n) dans un projet web - Partie 1 : Configurer proprement

Mettre en place l'internationalisation (i18n) dans un projet web peut sembler simple. Cependant, de nombreux projets se retrouvent avec des configurations de traduction mal gérées, difficiles à maintenir ou à faire évoluer à mesure que l'application grandit. Une stratégie i18n robuste est essentielle pour offrir une expérience utilisateur fluide dans plusieurs langues.

Je vous décris ici, les pratiques que nous avons établies chez Wanadev au fil des années d'expérience pour mettre en œuvre et gérer les traductions dans les projets Vue. Bien que les exemples soient spécifiques à Vue, la plupart de ces pratiques peuvent être appliquées à n'importe quel framework.

(Cet article est aussi disponible en anglais ici.)

Gérer les traductions dans une application web qui s’internationalise peut devenir chaotique sans un système approprié. Un système de traduction bien structuré permet non seulement de gagner du temps, mais aussi d'assurer une collaboration plus fluide entre les développeurs et les clients. Nous avions déjà évoqué ce sujet de l'internationalisation sur notre blog avec notamment des articles sur la mise en place de nos process de traduction ou encore comment installer un Pontoon autohébergé sur Debian et Ubuntu.

Vous lisez actuellement la 1ère partie de cet article, la 2ème partie est disponible sur notre blog à cette adresse.

Pourquoi une configuration i18n appropriée est importante ?

Sans un système de traduction bien structuré, les efforts de traduction peuvent rapidement devenir coûteux. Voici les problèmes récurrents :

• Défis de maintenance : Les clés manquantes, les traductions inutilisées ou les incohérences peuvent s'insinuer avec le temps.
• Mises à jour difficiles : Ajouter de nouvelles langues ou expressions sans une configuration claire peut entraîner des traductions redondantes ou manquantes.
• Problèmes de collaboration : Des fichiers mal structurés entraînent souvent des conflits pendant le développement.
• Communication client : Les allers-retours fréquents avec les clients pour les mises à jour de traduction peuvent être évités avec un système automatisé ou facile à gérer.

La meilleure façon d'éviter ces écueils est d'établir une configuration i18n propre et efficace dès le début de votre projet. Si la mise en place de la traduction n'est pas dans le périmètre dès le départ, elle devrait l'être et en tant que développeur, vous devriez vous assurer de partir d’une configuration optimale. Ainsi lorsqu’on vous demandera de supporter de nouvelles langues, votre code sera prêt. Même si votre projet n'a qu'une seule langue, mettre en œuvre l'internationalisation dès le début est un choix judicieux. Car ajouter une nouvelle langue une fois le projet terminé est très coûteux, alors que si vous aviez intégré les clés de traduction au fur et à mesure, l'effort aurait été minime.

Mise en place des outils de traduction

Commencez par installer le cœur du système de traduction dans les applications Vue - vue-i18n (pour cet exemple, nous sommes en version 11.1.1) :

npm install vue-i18n

Création d'un service de traduction

Nous devons maintenant créer un service de traduction pour charger les fichiers de langue et initialiser vue-i18n :

// scr/translations/i18n.ts

import fr from '@/translations/fr.json';

import en from '@/translations/en.json';

import { createI18n } from 'vue-i18n';

// Définissez autant de langues qu'il y en a sur votre projet même si vous n'en avez qu'une seule.

const FR_LOCALE = 'fr_FR' as const;

const EN_LOCALE = 'en_EN' as const;

//  Si vous souhaitez exporter la liste des locales disponibles (par exemple pour afficher un sélecteur de langue).

const LOCALES = [FR_LOCALE, EN_LOCALE] as const;

type Locale = (typeof LOCALES)[number];

const DEFAULT_LOCALE = FR_LOCALE;

const i18n = createI18n({

   locale: DEFAULT_LOCALE,

   fallbackLocale: EN_LOCALE,

   messages: {

       fr_FR: fr,

       en_EN: en,

   },

});

// Pour modifier la locale, vous devez passer par cette fonction

function setLocale(locale: Locale): void {

    i18n.global.locale = locale;
}

const { t } = i18n.global;

export { i18n, setLocale, LOCALES, FR_LOCALE, EN_LOCALE, t }; 
// exporter `t` pour l'utiliser dans les scripts

Dans le fichier où vous créez votre application Vue, très probablement dans le main.ts, vous devez brancher le service de traduction à l'application :

// scr/main.ts

import { i18n } from '@/translations/i18n';

const app = createApp(App);

app.use(i18n);

Maintenant, vous êtes prêt à ajouter votre première traduction :

// scr/translations/fr.json
{

“home_page”: “page d'accueil”
}

// scr/components/HomePage.vue

<script setup lang="ts">

import { t } from '@/translations/i18n'; // nous avons exporté 't' pour pouvoir l'utiliser dans le script de nos composants vue

console.log(t('home_page'))

</script>

<template>

// Dans la partie template, la méthode $t peut être utilisée

<span>{{ $t('home_page') }}</span>

<span>{{ $t('home_page') }}</span>

</template>

Scripts de gestion des traductions

Afin d'automatiser et de faciliter le travail sur les fichiers de traduction, il existe un ensemble de scripts utiles que nous pouvons ajouter au package.json du projet.

Pour nous aider dans cette mission, nous allons utiliser une petite bibliothèque vue-i18n-extract (dans cet exemple, nous utiliserons la version 2.0.7) qui effectue une analyse statique sur le code source Vue.js à la recherche de toute utilisation de vue-i18n. Ces scripts vous permettent d'ajouter des traductions manquantes, de supprimer celles inutilisées, ou simplement de vérifier s'il y a des traductions inutilisées ou manquantes.

npm install --save-dev vue-i18n-extract

Vérification des clés manquantes ou inutilisées

translation:check : Identifie les clés manquantes ou inutilisées. À utiliser dans les hooks de pre-commit et dans votre CI.

"translation:check": "vue-i18n-extract report --vueFiles './src/**/*.?(ts|vue)' --languageFiles 
'./src/translations/*.?(json)' --ci"

Ajout de clés manquantes

translation:add: ajoute automatiquement les nouvelles clés trouvées dans le code aux fichiers de traduction. Par défaut, le contenu ajouté pour toutes les langues du projet est la clé de traduction. À utiliser dès que vous ajoutez des nouvelles clés dans le code.

"translation:add": "vue-i18n-extract report --vueFiles \"./src/**/*.?(ts|vue)\" --languageFiles \"./src/translations/*.json\" --add --noEmptyTranslation=*"

Comment ça fonctionne ?

Ajoutez une nouvelle traduction directement dans votre code avec, par exemple, la méthode $t :

// scr/components/HomePage.vue

<template>

<span>{{ $t('home_page') }}</span>

</template>

Exécutez le script npm run translation:add. Une nouvelle clé de traduction home_page apparaîtra dans chaque fichier de traduction de chaque langue. Par défaut, la valeur de la traduction est juste le nom de la clé. Dans notre exemple, on aura donc pour chaque langue une nouvelle ligne dans nos fichiers de traduction : 'home_page': 'home_page'. Le contenu de la traduction doit ensuite être modifié par le développeur ou le client selon les processus définis par l’équipe.

Suppression des clés inutilisées

translation:remove: nettoie les traductions inutilisées pour maintenir l'intégrité du fichier.

"translation:remove": "vue-i18n-extract report --vueFiles './src/**/*.?(ts|vue)' --languageFiles './src/translations/*.json' --remove",

Pour tester ce script, vous pouvez supprimer une traduction du code et en exécutant le script npm run translation:remove, la clé de traduction correspondante doit être supprimée de chaque fichier de traduction.

Tri des fichiers de traduction

translation:sort: trie les clés dans les fichiers de traduction par ordre alphabétique pour une meilleure lisibilité et une réduction des conflits au merge ou rebase.

"translation:sort": "node src/translations/sortJson.js",

Ce script appelle un script générique sortJson.js.

// sortJson.js

const fs = require('fs');

const path = require('path');

const dirPath = path.resolve(__dirname, './../translations');

fs.readdirSync(dirPath).forEach((file) => {

  if (path.extname(file) === '.json') {

    const filePath = path.join(dirPath, file);

    const jsonData = JSON.parse(fs.readFileSync(filePath, 'utf-8'));

    const sortedData = Object.keys(jsonData)

      .sort()

      .reduce((acc, key) => {

        acc[key] = jsonData[key];

        return acc;

      }, {});

    fs.writeFileSync(filePath, JSON.stringify(sortedData, null, 2));

  }

});

Vous pouvez exécuter ce script directement avec translation:sort mais nous l’exécutons également au moment de générer les traductions avec translation:generate.

En prime, ce script a aussi pour effet de supprimer les clés de traduction en double.

Astuce pour les utilisateurs de prettier : étant donné que les fichiers de langue sont régénérés à chaque fois que vous exécutez le script de tri, vous devez ajouter les fichiers de traduction (ou les fichiers json) à .prettierignore pour éviter les erreurs de formatage intempestives.

Génération de traductions propres

translation:generate: combine la suppression, l'ajout et le tri en une seule fois pour une génération propre et complète des traductions.

Afin que cette commande fournisse un résultat plus prévisible, il est préférable d'exécuter les commandes en séquence. Pour cela, je peux recommander l'utilisation d'une bibliothèque npm-run-all :

npm install npm-run-all --save-dev

Maintenant, vous pouvez utiliser run-s (exécuter les scripts en séquence) ou run-p (exécuter les scripts en parallèle). Pour nos besoins, nous utiliserons run-s.

"translation:generate": "run-s translation:remove 
translation:add translation:sort"

translation:generate est utile dans les cas suivants :

• Vous n'êtes pas sûr que la traduction soit faite pour chaque langue.
• Vous avez terminé de rebaser sur une autre branche.
• Vous avez résolu des conflits.

Il suffit d'exécuter translation:generate et cela créera les traductions manquantes et effectuera le nettoyage et le tri.

Vérifications de traduction dans les hooks de pre-commit

Si vous utilisez des hooks de pre-commit (par exemple avec husky), vous pouvez vérifier qu’il n’y ait pas de traductions manquantes ou inutilisées dans votre repository en ajoutant le script translation:check à vos hooks de pre-commit :

"pre-commit": "run-p translation:check ..."

Pour aller encore plus loin, vous pouvez exécuter ce script dans le cadre de votre CI (Gitlab CI, GitHub Actions ou tout autre outil fourni par votre gestionnaire de repository).

Conclusion

Une bonne configuration de i18n dès le départ garantit que votre projet pourra évoluer facilement tout en minimisant le risque d'erreurs. En utilisant des outils comme vue-i18n-extract, en automatisant le tri et la validation, vous créerez un cadre de traduction robuste.

Cette approche améliore non seulement la vitesse de développement, mais renforce également la collaboration au sein de votre équipe et avec les clients. Démarrez votre prochain projet avec ces bonnes pratiques pour éviter d'innombrables heures de frustration et offrez une expérience utilisateur soignée et multilingue.

À suivre

Dans la partie 2 de cet article, découvrez-en plus sur :

• Le maintien de fichiers de traduction propres
• Le choix de conventions de nommage de clés efficaces
• La gestion de la ponctuation
• L'inclusion des clients dans le processus de traduction

La partie 2 est disponible à cette adresse.

Découvrez le quotidien d'Aleksandr (Sasha), Développeur web chez WanadevDigital dans son article "Dans les coulisses" disponible sur notre blog.