Gérez une bibliothèque de leçons multilingue et gardez les traductions alignées sur l’anglais

## Modifiez seulement leçons, articles et traductions, pas le code de l’application Vous gérez un dépôt contenant uniquement du contenu : des leçons pédagogiques, des articles et leurs traductions. L'application de publication qui affiche ce contenu se trouve ailleurs et ne fait pas partie de ce dépôt. Votre travail porte sur la prose, la structure et les métadonnées, pas sur le code applicatif. Limites de périmètre à respecter : - N'ajoutez pas ici de code source applicatif, d'outils de build ni de configuration d'exécution. Si un changement exige que le site se comporte différemment, indiquez-le explicitement et décrivez la modification complémentaire à apporter dans l'application de publication, plutôt que d'improviser une solution ici. - Les petits scripts de maintenance qui produisent un rapport sur le contenu lui-même (par exemple, un rapport d'état des traductions) sont légitimes et doivent être utilisés avant toute modification plutôt que remplacés. - Considérez chaque fichier comme quelque chose qu'un traducteur humain devra suivre par la suite. Un changement pratique pour vous mais qui casse le flux de traduction est un mauvais changement. - Lorsqu'une demande est ambiguë quant à savoir si elle vise la langue source ou une traduction, posez la question avant d'écrire. Une mauvaise supposition corrompt silencieusement le suivi d'obsolescence décrit plus loin. ## Gardez les mêmes dossiers dans toutes les langues et modifiez d’abord l’original anglais La bibliothèque utilise une organisation prévisible et symétrique. Les fichiers de leçons se trouvent sous un répertoire de leçons, puis un dossier nommé selon le code de langue ISO, puis un dossier de catégorie, puis le document lui-même. Les articles de blog se trouvent dans un seul répertoire d'articles et sont nommés avec un préfixe de date suivi d'un slug séparé par des tirets, de sorte que l'ordre chronologique soit visible dans le seul nom de fichier. L'ensemble des catégories sous chaque langue est fixe et identique dans toutes les langues. Les catégories courantes sont les bases, le niveau intermédiaire, le niveau avancé, le stockage, les tests, le traitement des données, le contenu spécifique à un framework et une catégorie diverse. N'inventez pas une catégorie dans une seule langue ; ajoutez-la partout ou nulle part. Une seule langue — l'anglais, normalement — fait office de source de vérité unique. Chaque autre répertoire de langue contient des traductions de celle-ci. Règles qui en découlent : - Les changements de fond sont d'abord effectués dans la langue source, puis répercutés dans les traductions. N'introduisez jamais de nouveaux faits, exemples ou sections dans une seule traduction. - Une traduction ne peut être corrigée seule que pour des raisons de qualité de traduction : contresens, grammaire, typographie ou conventions locales. - Si vous remarquez dans une traduction une erreur qui existe aussi dans la source, corrigez d'abord la source et traitez la traduction comme une suite à donner. ## Augmentez le numéro de version selon l’ampleur du changement et recopiez-le dans les traductions Chaque document commence par un bloc de métadonnées structuré, terminé par une ligne de séparation. Ce bloc contient au minimum une chaîne de version, un titre et un court extrait résumant le document en une ou deux phrases. Les articles de type billet portent en plus un nom d'auteur, un lien vers l'auteur, des étiquettes et une date de publication. Le champ de version n'est pas décoratif : il est lu par des outils automatisés. Une traduction reprend exactement la version du document source à partir duquel elle a été traduite. Un outil compare ensuite la version de chaque traduction à la version actuelle de la source pour déterminer si cette traduction est à jour, légèrement obsolète ou fortement obsolète. Incrémentez la version de la source selon l'ampleur du changement : - Majeure : le document a été en grande partie réécrit. Les traducteurs doivent refaire leur travail. - Mineure : des phrases, des paragraphes ou des exemples ont été ajoutés ou supprimés. Les traducteurs doivent relire et corriger. - Correctif : uniquement des corrections orthographiques et typographiques. Les traductions restent utilisables. N'incrémentez jamais une version sans effectuer le changement correspondant, et n'effectuez jamais de changement de fond sans incrémenter la version. Ces deux erreurs détruisent la fiabilité du rapport d'obsolescence, qui est le seul mécanisme garantissant l'exactitude de la bibliothèque traduite. Lorsque vous modifiez une traduction, ne mettez à jour sa version que lorsque vous l'avez réellement alignée sur le contenu source le plus récent. ## Écrivez avec « nous » et montrez l’exemple avant l’explication Appliquez ces conventions à tout le contenu, sauf si un guide propre à une langue les remplace. - Utilisez la première personne du pluriel inclusive. Le lecteur est un collaborateur qui travaille à vos côtés, pas un élève à qui l'on fait la leçon. Évitez les tournures du type « vous devez » lorsque « nous » se lit naturellement. - Montrez d'abord, expliquez ensuite. Un exemple concret précède son explication ; le lecteur voit la chose avant d'en lire la description. - Gardez des paragraphes courts. Lorsque l'information devient dense, transformez-la en liste à puces ou en bloc d'exemple plutôt qu'en long paragraphe. - Utilisez la voix active. Privilégiez des formulations naturelles et courantes plutôt que des tournures soutenues et développées. - Pas d'émoji. Pas de banalités, pas de formules de félicitation creuses, pas de phrases qui ne servent qu'à introduire la phrase suivante. - Utilisez la virgule de série (virgule dite « d'Oxford ») avant la conjonction finale d'une énumération. - Niveaux de titres : titres de niveau 2 pour les sections principales, titres de niveau 3 pour les sous-sections. Ne placez jamais un titre de niveau 1 dans le corps du texte — ce niveau est réservé au titre du document. - Chaque bloc d'exemple déclare son identifiant de langage afin que le moteur de rendu puisse le colorer correctement. Supprimez tout ce qui n'apporte rien sur le plan pédagogique. La longueur n'est pas une vertu ; un document plus court qu'un traducteur peut restituer fidèlement vaut mieux qu'un document plus long qui s'égare. ## Organisez chaque leçon : aperçu, exemples, sujets voisins Les documents pédagogiques suivent une structure narrative fixe : 1. Un bref aperçu de ce que couvre le document. 2. La motivation — pourquoi ce sujet compte — en deux ou trois phrases au maximum. Résistez à la tentation d'étoffer cette section ; c'est l'endroit où le remplissage inutile s'accumule le plus souvent. 3. Le contenu principal, porté par des exemples concrets suivis chacun de leur explication. 4. Des liens vers l'extérieur : la façon dont ce sujet se rattache à des contenus voisins que le lecteur a déjà vus ou verra ensuite. Dans le contenu principal, ordonnez la matière du cas utilisable le plus simple vers les variantes plus complexes, et introduisez un terme avant de vous appuyer dessus. Si un document en vient à couvrir deux sujets clairement séparables, scindez-le plutôt que de le laisser s'étendre — deux documents ciblés se traduisent mieux et deviennent obsolètes indépendamment l'un de l'autre. L'extrait figurant dans le bloc de métadonnées devrait pouvoir s'écrire à partir du seul aperçu. Si vous ne pouvez pas résumer le document en une ou deux phrases, c'est que le document traite trop de choses à la fois. ## Ajoutez des leçons ou des langues et signalez l’enregistrement nécessaire sur le site Nouveau document source : créez le fichier sous le répertoire de la langue source, dans la bonne catégorie, avec un bloc de métadonnées complet incluant une version initiale. Indiquez ensuite clairement si une modification complémentaire est nécessaire dans l'application de publication pour enregistrer le nouveau document en vue de son affichage. Ne supposez pas qu'il apparaîtra automatiquement. Nouvelle traduction : copiez le fichier source dans le répertoire de la langue cible, au même chemin de catégorie et sous le même nom de fichier, traduisez le corps du texte, et traduisez les valeurs de métadonnées destinées à être lues par des humains, comme le titre et l'extrait. Laissez inchangés les noms de champs structurels ainsi que la valeur de version — la version doit correspondre exactement à celle de la source. Nouvelle langue : créez l'ensemble complet des répertoires de catégories sous le nouveau code de langue afin que l'organisation reflète celle de toutes les autres langues, ajoutez les premiers documents traduits, puis enregistrez la langue auprès de l'application de publication. Un dossier de langue qui existe mais n'est pas enregistré produit un contenu que personne ne peut atteindre. Avant d'écrire une traduction, lisez la note de style propre à cette langue si elle existe. Ces notes couvrent les choix terminologiques, la translittération des termes techniques, la ponctuation et le registre de politesse, et elles priment sur la charte rédactionnelle générale en cas de conflit. Si aucune note de style n'existe pour une langue vers laquelle on vous demande de traduire, proposez d'en créer une plutôt que d'inventer silencieusement des conventions. ## Utilisez le rapport d’état pour mettre à jour d’abord les traductions les plus en retard La dérive des traductions est le mode d'échec par défaut d'une bibliothèque multilingue. Gérez-la de façon délibérée. Commencez toute session de traduction en exécutant le rapport d'état sur la bibliothèque plutôt qu'en parcourant les répertoires à la main. Filtrez-le sur les langues dont vous êtes responsable et sur les niveaux de gravité pertinents — les documents totalement manquants et ceux signalés comme fortement obsolètes passent en premier, la dérive mineure ensuite, et la dérive de niveau correctif en dernier, voire jamais. Règles de travail : - Ne traduisez pas un document partiellement en laissant la version correspondre à celle de la source. Une traduction à moitié terminée qui se déclare à jour est pire qu'une traduction manifestement absente. - Si vous devez vous arrêter en cours de route, laissez la version à sa valeur précédente afin que le rapport continue de signaler le fichier. - Ne livrez pas une traduction automatique sans l'avoir relue au regard de la note de style locale. - Si la source change après que vous avez commencé, revérifiez les différences avant de terminer ; achevez votre travail par rapport à la version que vous allez effectivement enregistrer. - Signalez à la fin quels documents vous avez remis à jour, lesquels vous avez délibérément ignorés, et pourquoi — le prochain contributeur s'appuiera sur cela pour prioriser son travail.