Guide du contributeur pour la traduction de la documentation

Guide de contribution

Ce guide permet une cohérence syntaxique et graphique sur l'ensemble de la documentation.

Il est à lire en intégralité au moins une fois avant toute contribution et à réviser en cas de doute afin de faciliter le travail de correction.

N'oubliez pas, avant tout début de traduction de consulter la liste des restes à faire et de vous signaler auprès de l'administrateur du site en ouvrant une issue GitHub.

Documentation rédigée en Markdown

La documentation doit être rédigée en Markdown.

Le repo Git est un fork de la documentation officielle, et contient à ce titre pour les parties non-traduites encore les fichiers de celle-ci dans leurs versions anglaise, déjà formatés en markdown.

Vous n'aurez donc pas besoin de connaître intégralement le langage pour participer.

Toute contribution qui n'utiliserait pas cette syntaxe ne pourra pas être incluse sans un double-travail de correction.

Pour l'intégralité des fonctionnalités de ce langage de rédaction, se référer à ce guide.

Conservation de la structure

Nous tenons à respecter la même structure que la documentation officielle.

C'est pourquoi il vous est demandé de seulement traduire les différents textes, n'ajoutez ou ne supprimer aucun bloc structurel par rapport à la version officielle, qu'il s'agisse de code, de conseils ou de tableau.

La scission éventuelle dd certains paragraphes que vous jugez trop long est toléré si cela améliore la lisibilité.

Ne changez pas non plus la structure du dossier, aucun fichier ne doit être renommé, déplacé ou supprimé.

Aussi et surtout ne modifiez pas les liens ou les ancres contenues dans les différentes pages : une fonctionnalité permet le temps de la traduction partielle de rediriger le visiteur vers le site officiel lorsque la page demandée n'est pas disponible.

Laissez aussi les liens vide du type <a name="mon-ancre"></a> présents au-dessus de chaque titre. Ceux-ci sont présents afin de créer des ancres pour les sommaires

Liens des menus

Les menus sur le site sont générés automatiquement depuis les fichiers contenus dans le dossier config.

Il convient pour toute page traduite entièrement qui serais liée directement par un lien du menu de le traduire et de dé-commenter sa ligne afin d'activer l'affichage du lien dans le menu du site.

Lisibilité

Afin de faciliter la correction et l'entretien de la documentation, certaines règles à respecter seront fortement appréciées lors de la validation. Ces mêmes règles très simples vous aideront aussi à la rédaction et à la relecture.

N'hésitez pas sur les retours à la ligne

Contrairement aux fichiers qui n'ont pas encore été traduits, n'hésitez pas à rajouter des retours à la ligne.

La longueur préconisée de nombre de caractères par ligne se situe entre 120 et 160, mais vous ne serez pas jugé(e) si vous dépassez ces limites.

Gardez en tête que les retours chariots ne sont pas pris en compte en markdown (comme en HTML). Seule une ligne vide entre deux blocs de caractères créera un nouveau paragraphe. N'hésitez donc pas à insérer un retour à la ligne après un point ou même une virgule afin de faciliter la relecture et correction.

Remarque : attention aux tableaux. Un retour à la ligne dans ces blocs structurés n'est pas permis par le langage.

Mise en surbrillance des variables, méthodes, noms et chemins de fichiers

Il convient lors de l'utilisation de variables, méthodes, noms de fichiers ou chemins de fichiers dans une phrase, d'utiliser des blocs de code "inline" afin de les mettre en surbrillance. Pour cela entourez le mot à mettre en avant avec des `backticks` comme le Markdown le permet.

Traduction des noms de variables et de méthodes

Oui : nous conseillons et conseillerons toujours de coder en anglais pour des raisons de bonnes pratiques. Néanmoins il est plus facile de comprendre pour certains si certaines parties du code sont en français.

Les exemples de codes n'ont pas à être littéralement traduits tant qu'il explique correctement la fonctionnalité.
Si possible, pour contenter les deux mondes : soyez inventifs, et essayez de trouver des mots anglais facilement compréhensible. Ainsi une fonction onDoSomeComplexStuff() pourrait être traduite onLogin() tant que cela reste adapté.

Les chaînes de caractères en tant que valeurs seront elles toujours traduites en français.

Ce site utilise des cookies

Ils permettent de vous fournir la meilleur expérience visiteur possible.

En poursuivant la navigation sur ce site, vous acceptez l'utilisation de ces cookies.