À propos de ce document

Contribuer

Les sources de ce document sont hébergées sur GitLab dans le dépôt extending-lilypond/extending-lilypond.gitlab.io.

Pour signaler une erreur ou suggérer une amélioration, vous pouvez ouvrir une page de bug sur GitLab, ou bien me contacter directement. Vous pouvez également vous servir du bouton « Éditer cette page en anglais » dans la barre de droite. Cela vous emmènera dans un éditeur facile à utiliser pour proposer des changements simples au texte anglais (qui seront ensuite répercutés dans la traduction).

Compilation

Les sources sont en Markdown MyST, compilées avec Sphinx.

Il vous faut Python et Hatch. Les autres dépendances sont installées automatiquement par Hatch. Pour compiler ce guide, exécutez la commande hatch run build en, puis ouvrez le fichier public/en/index.html dans votre navigateur pour voir le résultat.

Le guide contient des extraits de code LilyPond. Chaque extrait est compilé par LilyPond et l’image est affichée en-dessous du code. Pour compiler les extraits, exécutez hatch run lilypond en.

Traduction

Les traductions se font dans des fichiers au format PO, qui associent un paragraphe traduit à chaque paragraphe en anglais. Il y a actuellement deux traductions, en français, et en allemand (la seconde est un chantier en cours). Les traductions supplémentaires sont les bienvenues (mais acceptez ce conseil : ne vous lancez dans ce travail que si vous pensez avoir une bonne compréhension de ce que vous allez traduire, sinon vous risquez d’être bloqué).

Dans les instructions suivantes, remplacez LANG par le code de votre langue (comme fr, de, etc.).

Avant de commencer à travailler sur une traduction, lancez la commande

$ hatch run update LANG

pour synchroniser les fichier PO avec l’original anglais, en ajoutant et supprimant des entrées, et en marquant comme obsolètes celles qui ont été modifiées.

Pour voir le travail qui reste à faire, utilisez la commande

$ hatch run todo LANG

Pour compiler la documentation dans votre langue,

$ hatch run build LANG

et ouvrez public/LANG/index.html.

Les images produites par LilyPond sur les extraits de code sont partagées entre toutes les langues. Ainsi, si vous avez déjà exécuté hatch run lilypond en, les extraits que vous n’avez pas changés dans la traduction auront une image. Néanmoins, si vous changez certains extraits, vous devez compiler les extraits traduits avec hatch run lilypond LANG.

Pour démarrer une nouvelle traduction, commencez par ajouter le code de langue (LANG) à la fin du fichier LINGUAS. Lorsque vous l’aurez-fait, la première fois que vous exécuterez hatch run update LANG, un dossier LANG/ apparaîtra avec les fichiers PO à traduire.

Les extraits de code sont également inclus comme des « paragraphes » dans les fichiers PO. Vous avez le choix de traduire ou non les commentaires et noms de variable qui s’y trouvent. Dans le tutoriel Scheme, il est souhaitable de le faire. A contrario, certains exemples dans le guide d’extension sont particulièrement longs, et il est préférable de ne pas les traduire, car les mettre à jour lorsqu’ils changent dans l’original deviendrait pénible. Dans ce cas, copiez simplement l’original dans la traduction. (Ne laissez pas simplement la traduction vide, car hatch run todo LANG prendrait alors l’entrée pour non traduite.)

Vous pouvez aussi reformater les fichiers .po. Il est recommandé de le faire avant chaque commit, pour éviter que des mises à jour futures des fichiers .po pour s’adapter aux évolutions de l’original ne reformatent les parties que vous avez déjà traduites.

$ hatch run pofmt LANG

Vérification des hyperliens

Pour vérifier qu’il n’y a pas de lien mort, exécuter

$ hatch run linkcheck en

ou (pour une traduction)

$ hatch run linkcheck LANG