Repenser la traduction de la documentation : considérer les traductions comme des actifs logiciels versionnés

Dans les grands dépôts de documentation, les problèmes de traduction échouent rarement de manière évidente. Au lieu de cela, ils échouent silencieusement et s’accumulent avec le temps. Récemment, nous avons pris une décision fondamentale sur la façon dont Co-op Translator gère les traductions.

Les traductions sont désormais considérées comme des « Actifs Logiciels Versionnés », et pas seulement comme des résultats statiques.

Quand les traductions deviennent silencieusement un passif

Dans la plupart des projets, une traduction est considérée valide une fois terminée, jusqu’à ce que quelqu’un remarque explicitement un problème. Cependant, à mesure que le texte source évolue et que les exemples de code changent, le contenu traduit — même s’il est fluide — devient obsolète. Ce n’est plus un problème de qualité de traduction ; c’est un problème de maintenance.

Nous avons dû changer notre question centrale :

« Cette traduction est-elle correcte ? » (X)
« Cette traduction est-elle toujours synchronisée avec la source actuelle ? » (O)

La décision : les traductions comme actifs versionnés

À partir de Co-op Translator 0.16.2, nous avons délibérément défini les traductions comme des actifs versionnés. Cela s’applique non seulement aux fichiers Markdown, mais aussi aux images, aux notebooks et à tout autre artefact traduit.

Plutôt que d’inventer un nouveau mécanisme, nous nous sommes tournés vers des outils de gestion des dépendances logiciels comme pip, poetry et npm. Lorsqu’une dépendance est obsolète, ce n’est pas qu’elle est « erronée » — elle est simplement désynchronisée par rapport à la version actuelle. Nous avons appliqué cette même logique à la documentation.

Changements clés et avantages

1. Des marqueurs intégrés vers un état explicite

Auparavant, les métadonnées de traduction étaient intégrées dans les fichiers sous forme de commentaires, ce qui les rendait fragmentées et faciles à manquer. Maintenant, nous utilisons des fichiers d’état JSON spécifiques à la langue pour suivre la version source, l’artefact traduit et son état de synchronisation. L’état de la traduction est désormais une partie de premier ordre et exploitable du dépôt.

2. Extension aux images et notebooks

Le même modèle s’applique aux actifs non textuels. Si une image source change, la version traduite est immédiatement signalée comme « désynchronisée ». Cela assure la cohérence entre tous les types de contenu dans le dépôt.

3. Maintenance observable

Cette conception permet :

Détection explicite de la dérive : Fini les suppositions sur les fichiers obsolètes.
Signaux cohérents : Textes, images et notebooks suivent tous les mêmes règles de synchronisation.
Scalabilité : La maintenance passe d’une tâche réactive à un flux de travail observable et gérable.

Conclusion

En modélisant les traductions comme des actifs logiciels, l’ambiguïté disparaît. L’état devient visible, et la maintenance devient gérable. La question n’est plus de savoir s’il existe une dérive de traduction, mais plutôt : « La voyez-vous ? »

Références :