Comment j'ai automatisé ma propre documentation multilingue avec Localizeflow

Le Problème : La traduction n’était pas difficile. La synchronisation, oui.

Au cours des trois derniers mois, j’ai géré à la fois de la documentation et du contenu de blog en coréen et en anglais.

Mon workflow était simple :

Rédiger en coréen.
Créer la version anglaise.
Maintenir les deux au fil du temps.

Au début, cela semblait gérable.
Dans beaucoup de cas, je pouvais simplement demander à l’IA de mettre à jour l’autre langue, et cela fonctionnait étonnamment bien.

Pendant un moment, cela semblait efficace.

Mais une fois que les docs ont commencé à évoluer plus rapidement — nouvelles fonctionnalités, captures d’écran mises à jour, changements d’API — les choses ont commencé à se dégrader silencieusement.

Chaque fois que je mettais à jour la version anglaise, je devais :

Me rappeler que le coréen devait aussi être mis à jour.
Trouver manuellement ce qui avait changé.
Vérifier à deux fois que je n’avais rien manqué.

Au départ, je synchronisais étroitement les deux versions.

Mais à un moment donné, j’ai remarqué quelque chose d’inconfortable :

Je mettais à jour les docs en anglais immédiatement…
et je me disais que je « mettrais le coréen à jour plus tard ».

Le « plus tard » venait rarement.

La traduction en elle-même n’était pas la partie difficile.

Ce qui était difficile, c’était de garder les deux langues synchronisées.

Et en tant que fondateur, mon attention ne devait pas être consacrée à courir derrière des paragraphes obsolètes entre les langues.

À un moment donné, j’ai réalisé quelque chose d’un peu ironique :

Je construisais un produit d’automatisation de localisation
et je maintenais manuellement ma propre documentation multilingue.

Cela n’avait pas de sens.

J’ai donc décidé de dogfooder Localizeflow sur la documentation et le blog de Localizeflow lui-même.

La Décision : Automatiser ou abandonner une langue

Il n’y avait que deux options réalistes :

Arrêter de maintenir le coréen.
Ou automatiser le workflow.

Abandonner une langue me semblait faux.
Mais continuer manuellement semblait inefficace.

Si la documentation multilingue demande de la discipline et une attention constante,
elle ne survivra pas dans une startup en mouvement rapide.

Alors au lieu de retirer une langue,
j’ai décidé de retirer la friction.

J’ai installé Localizeflow sur notre dépôt de documentation.

Pas de YAML.
Pas de configuration supplémentaire.
Juste l’installation de l’application GitHub.

C’était tout.

Je ne voulais pas un autre tableau de bord.
Je ne voulais pas un autre portail de traduction.

Je voulais que mon workflow GitHub existant reste intact.

Et c’est ce qui s’est passé.

Si vous êtes curieux du flux d’intégration exact, vous pouvez consulter le guide d’installation :
https://docs.localizeflow.com/

Avant d’aller plus loin, une petite note sur la stack.
Nous utilisons Astro comme générateur de site statique.
Astro ne fournit pas un support multilingue fortement opinionné au départ — du moins pas de la même façon que certains frameworks documentaires.

C’était intentionnel.

Je voulais tester Localizeflow dans un environnement un peu moins « aidant » en premier.
Si ça fonctionne bien avec Astro, ça devrait marcher encore plus fluide avec Hugo, Docusaurus, ou Mintlify — qui offrent des primitives i18n plus robustes.

Maintenant, voyons ce qui a réellement changé.

À quoi ressemblait la configuration

Après avoir installé l’application GitHub pendant l’inscription, j’ai connecté mon dépôt de documentation en cliquant sur le bouton « Connect repositories ».

Une fois connecté, cliquer sur le dépôt vous fait entrer dans le flux d’intégration.

Au lieu d’un long processus de configuration, cela s’est résumé à trois décisions :

Langues
Structure de sortie
Règles de glossaire

L’ensemble du processus a pris quelques minutes.

Ce qui m’a marqué, ce n’était pas seulement la rapidité,
mais le fait que je n’avais pas à modifier l’infrastructure.

Je n’ajoutais pas de scripts CI.
Je ne restructurais pas les dossiers.

Je confirmais surtout comment mon dépôt fonctionnait déjà.

Cela m’a paru important.

Car d’après mon expérience, les outils d’« automatisation » demandent souvent des changements système.

Celui-ci, non.

1. Sélection des langues cibles

La première décision fut de sélectionner les langues cibles.

Chaque langue devient un flux de Pull Requests de traduction.
Ce choix de conception rend les changements visibles, pas cachés.

Cela s’intègre naturellement dans le workflow GitHub.

2. Définir où vivent les traductions

Pour les chemins de sortie, j’ai utilisé la fonction d’analyse du dépôt.

Elle a scanné le dépôt et suggéré les chemins source et cible.

J’ai passé la suggestion en revue et l’ai confirmée.

Avant de continuer, j’ai vérifié un aperçu de ce que la structure des dossiers deviendrait après génération des traductions.

Cet aperçu comptait.

Il montrait exactement où les fichiers traduits vivraient, sans rien modifier encore.

Je n’avais pas à raisonner manuellement sur les correspondances des dossiers depuis zéro.

Je validais simplement ce que le système déduisait à partir de la structure existante.

3. Règles de glossaire

Avant de terminer la configuration, j’ai ajouté un petit glossaire.

Des termes comme :

Localizeflow
GitHub App
Co-op Translator

restent inchangés dans les traductions.

Cela évite des corrections répétitives dans les PR plus tard.

Temps total de configuration

Moins de cinq minutes.

Mais plus important encore :

Pas de reconfiguration CI.
Pas de nouvelles pipelines.
Pas de migration de dossiers.

La configuration ne semblait pas adopter un nouveau système.

Elle semblait activer une capacité dans l’existant.

Ce qui arrive quand j’édite l’anglais aujourd’hui

Voici ce qui a changé en pratique.

Avant :

Modifier le document anglais.
Ouvrir manuellement le document coréen.
Chercher les sections modifiées.
Mettre à jour.
Commiter les deux.

Maintenant :

Je modifie le fichier Markdown anglais.
Localizeflow détecte les changements de contenu via comparaison de hachage.
Une Pull Request de traduction est automatiquement générée.
Je revoie et fusionne.

C’est tout.

Je ne fais plus de « traduction ».
Je revois une PR.

Et cette différence psychologique est énorme.

Après la configuration, le tableau de bord Localizeflow n’est pas quelque chose que je surveille activement.

L’avancement du travail est posté directement dans la Pull Request sous forme de mises à jour de statut structurées.

Si vous ouvrez la PR, vous voyez immédiatement :

La progression actuelle
Les langues terminées
Les tâches restantes
Les éventuelles erreurs

Cela se comporte plus comme un statut CI que comme un outil de traduction séparé.

Cette conception le rend natif à GitHub.

Ce qui a réellement été amélioré

1. Je pense maintenant dans une seule langue

Je ne mets à jour que la source anglaise.

Je ne me demande plus :
« Ai-je aussi mis à jour le coréen ? »

Cette charge cognitive a disparu.

2. Les changements ne s’accumulent pas

Avant, les petites mises à jour s’accumulaient parce que mettre à jour les deux langues semblait pénible.

Maintenant, même de petits ajustements de doc sont faciles.

Ce qui signifie que la qualité de la documentation s’améliore indirectement.

3. Ça reste dans mon workflow

Tout se passe via des Pull Requests.

Pas de tableau de bord séparé.
Juste revoir et fusionner.

4. Le temps de mise à jour est tombé à quelques minutes

Avant, même un petit changement dans la documentation signifiait modifier deux fichiers.

Maintenant, mettre à jour une page prend le même temps quel que soit le nombre de langues supportées.

Le coût marginal d’ajouter une langue est en fait nul.

Ce qui nécessite encore du travail

Le dogfooding a aussi mis en lumière quelques limites :

Avec Astro, après la génération des traductions, j’ai encore dû ajuster manuellement certaines URL pour référencer correctement les routes localisées. Cela pourrait ne pas être un problème avec des générateurs statiques offrant un routage i18n natif plus robuste.
J’ai implémenté un simple sélecteur de langue dans l’en-tête pour faciliter la navigation entre les pages localisées.

Même avec ces petites étapes manuelles, l’effort global de maintenance est considérablement réduit.

Le vrai résultat

Avant :

Maintenir deux langues semblait une surcharge.

Maintenant :

Maintenir plusieurs langues semble durable.

Et cela change l’équation stratégique.

Quand la localisation cesse d’être douloureuse,
la portée globale devient par défaut — et non un fardeau.

Réflexion finale

Il ne s’agissait pas de prouver que le produit fonctionne.

Il s’agissait de prouver que le workflow fonctionne sous la pression réelle d’un fondateur.

Quand tu construis des fonctionnalités, parles avec des utilisateurs, gères l’opération —
la documentation est la première chose qui dérape.

Si les docs multilingues exigent de la discipline,
elles ne survivront pas.

Si elles exigent juste de revoir une PR,
elles pourraient.

Le dogfooding de Localizeflow a rendu une chose claire :

La traduction est facile.
La synchronisation est le vrai problème.

Et la synchronisation peut être automatisée.

À qui s’adresse ce workflow

Ce workflow pourrait vous parler si vous :

Maintenez des README multilingues
Gérez un projet OSS rapide
Gérez une documentation lourde en MDX
Mettez fréquemment à jour des exemples, captures d’écran, ou références d’API
Ou oubliez simplement de mettre à jour les traductions après avoir modifié la source

Si la documentation multilingue ne semble durable que quand le rythme est lent,
elle ne survivra probablement pas quand votre projet accélérera.

L’automatisation ne retire pas la responsabilité.
Elle retire la friction.

Et dans les environnements rapides,
retirer la friction est souvent ce qui rend la constance possible.

Si vous maintenez des docs multilingues et souhaitez voir à quoi cela ressemblerait dans votre dépôt,
je serais ravi de faire un exemple en direct avec vous.