Traduction du site web Debian

Pour rendre le travail des traducteurs aussi facile que possible, les pages sont générées un peu différemment de ce à quoi beaucoup d'entre vous sont habitués. Les pages web sont en fait générées en utilisant un source qui utilise le langage de balisage wml. Il y a des répertoires distincts pour chaque langue.

Si vous prévoyez de démarrer une nouvelle traduction du site web Debian, veuillez lire la section sur le démarrage d'une nouvelle traduction.

Traduire une page

Nous utilisons WML pour séparer le contenu spécifique à une page des éléments communs à plusieurs pages. Ce qui signifie qu'il faut éditer un certain nombre de fichiers source WML au lieu d'éditer des fichiers HTML. Veuillez récupérer les sources actuelles en utilisant Git. Vous aurez besoin de récupérer au moins les répertoires : webwml/english/ et webwml/<votre_langue>/.

Pour traduire une page de l'anglais dans votre langue préférée, il faut traduire le fichier .wml original et le placer dans le répertoire correspondant de votre langue. Le chemin relatif ainsi que le nom devront être les mêmes que ceux de la version anglaise pour que les liens puissent fonctionner.

En-têtes de traduction

Nous recommandons tout spécialement au traducteur d'ajouter une ligne supplémentaire dans les en-têtes, juste à la suite de la dernière déclaration #use, pour enregistrer le numéro de version exact du document qu'il vient de traduire. De cette manière, les mises à jour sont facilitées. La ligne ressemble à cela : #use wml::debian::translation-check translation="<git_commit_hash>" Veuillez noter que si vous créez le fichier traduit en utilisant l’outil copypage.pl (ce qui est fortement recommandé), l’empreinte numérique du commit de Git sera générée automatiquement. L’utilisation de copypage.pl est expliquée dans la suite du texte.

Plusieurs équipes de traduction utilisent également cette ligne pour indiquer le traducteur officiel de chaque page web. Ainsi, vous recevrez automatiquement des courriels quand les pages dont vous êtes le responsable sont mises à jour dans la version anglaise et nécessitent votre attention pour la mise à jour de la traduction. Pour cela, ajoutez simplement votre nom comme responsable à la fin de la ligne #use pour la faire ressembler à ceci : #use wml::debian::translation-check translation="git_commit_hash" maintainer="votre_nom". Le script copypage.pl permet de le faire automatiquement si la variable d'environnement DWWW_MAINT est configurée, ou en utilisant l'option -m de la ligne de commande.

Les en-têtes de page web peuvent être générés très simplement en utilisant le script copypage.pl qui se trouve à la racine du répertoire webwml. Le script va copier la page au bon endroit, créer les répertoires et les fichiers Makefile si nécessaire et ajouter l'en-tête qui convient de façon automatique. Vous serez alerté si une page à copier existe dans le dépôt, soit parce que la page a été supprimée du dépôt (à cause d'un décalage trop important par rapport à la page d'origine), soit parce que quelqu'un d'autre a déjà propagé une traduction et que votre copie locale du dépôt n'est pas à jour.

Avant d'utiliser copypage.pl, vous devez d’abord configurer un fichier language.conf dans le répertoire racine webwml, qui sera utilisé pour déterminer la langue vers laquelle vous traduisez. Ce fichier ne nécessite que deux lignes. La première indique le nom de la langue (par exemple, french) et la seconde peut facultativement indiquer le nom du traducteur responsable. La langue peut aussi être configurée à l'aide de la variable d'environnement DWWW_LANG et votre nom avec la variable d'environnement DWWW_MAINT pour qu'il soit ajouté en tant que responsable de la traduction à l'en-tête des fichiers WML créés. Ou, comme troisième possibilité, vous pouvez indiquer la langue, et (facultativement) le responsable, sur la ligne de commande à l’aide de -l french -m "Martin Dupond" et ne pas utiliser du tout le fichier language.conf. D'autres fonctionnalités sont disponibles dans le script, il suffit de le lancer sans argument pour obtenir l'aide.

Une fois que vous avez, par exemple, exécuté la commande : ./copypage.pl fichier.wml, traduisez le texte d'origine directement dans le fichier. Les commentaires contenus dans les fichiers indiquent s'il y a des portions de texte à ne pas traduire. Suivez ces commentaires. N'effectuez pas de modifications non justifiées dans la mise en page. S'il faut faire des corrections, il faut également que ces corrections soient apportées dans le fichier original.

Construction et publication des pages

Étant donné que nous utilisons la négociation de contenu, les fichiers HTML ne sont pas nommés fichier.html mais fichier.<lang>.html, où <lang> est le code à deux lettres de la langue, telle qu'elle est définie dans l'ISO 639 (par exemple, fr pour le français).

Vous pouvez construire les fichiers HTML à partir des fichiers WML en lançant make fichier.<lang>.html. Si cela fonctionne, vérifiez la syntaxe à l'aide de weblint fichier.<lang>.html.

REMARQUE : les pages web sont reconstruites automatiquement régulièrement sur le serveur www-master, en se basant sur les sources wml dans Git. Ce procédé est en grande partie résistant aux erreurs. Cependant, si vous téléversez un fichier défectueux au tout début de la traduction (par exemple, la première indication du fichier index.wml), cela brisera le processus de construction et paralysera les autres mises à jour vers le site web. Veuillez accorder une attention particulière à ces fichiers.

Lorsque la page est prête, vous pouvez l'envoyer dans Git. Si vous possédez l'autorisation, faites-le vous-même. Téléversez (push) le commit dans le dépôt webwml de Git. Sinon, envoyez-le à une personne ayant un accès en écriture dans le dépôt.

Commencer une nouvelle traduction

Si vous voulez démarrer une traduction des pages web de Debian dans une nouvelle langue, envoyez-nous un message (en anglais) à webmaster@debian.org.

Tout d'abord, cloner notre arbre des sources comme décrit dans notre page d'introduction à Git.

Une fois que vous avez réalisé une extraction (checkout) de Git, commencez par créer un nouveau répertoire de départ pour votre traduction, à coté des répertoires english/ et autres. Le nom du répertoire de traduction doit être en anglais et être écrit en minuscule (par exemple, « french », et pas « Français »).

Copiez les fichiers Make.lang et .wmlrc du répertoire english/ dans le répertoire de votre traduction. Ces fichiers sont essentiels pour construire vos traductions à partir des fichiers WML. Ils ont été conçus de sorte qu'une fois copiés, vous aurez uniquement a effectuer les modifications suivantes :

  1. La variable LANGUAGE doit être changée dans le fichier Make.lang ;
  2. Les variables CUR_LANG, CUR_ISO_LANG et CHARSET doivent être modifiées dans le fichier .wmlrc. Ajoutez aussi CUR_LOCALE si cette variable est nécessaire au tri alphabétique ;
  3. Certaines langues peuvent nécessiter un traitement spécial à cause du jeu de caractères utilisé. Cela peut être fait avec les options --prolog et --epilog de wml. Utilisez les variables WMLPROLOG et WMLEPILOG dans Make.lang dans ce but ;
  4. La variable LANGUAGES doit être changée dans le fichier de premier niveau webwml/Makefile afin que votre langue soit prise en compte comme les autres sur www.debian.org. Nous préférerions que vous laissiez ce changement à la charge des webmestres, parce que vous pourriez ne pas vous rendre compte que votre traduction n'a pas été correctement faite, ce qui pourrait bloquer le processus de génération du reste du site ;

Une fois que vous aurez fait cela, ajoutez la ligne suivante dans un nouveau fichier appelé « Makefile » dans le nouveau répertoire : 

include $(subst webwml/répertoire_de_votre_langue,webwml/english,$(CURDIR))/Makefile

(Remplacez bien sûr répertoire_de_votre_langue avec le nom de répertoire de votre langue.)

Créez maintenant un sous-répertoire « po » à l'intérieur du répertoire de votre langue, et copiez le même Makefile dans ce répertoire (cp ../Makefile .).

Dans le répertoire po/, lancez make init-po pour générer un ensemble initial de fichiers *.po.

Maintenant que le squelette est prêt, vous pouvez commencer à ajouter vos traductions dans les balises WML communes que nous utilisons dans les modèles. Les premiers modèles de traduction que vous devez traduire sont ceux qui apparaissent sur l'ensemble de nos pages web, comme les en-têtes, les entrées dans la barre de navigation, et les pieds de pages.

Commencez à traduire dans le fichier po/templates.xy.po (où xy est le code à deux lettres de votre langue). Pour chaque msgid "quelque_chose" il y a un msgstr "" à l'intérieur duquel vous devez ajouter la traduction du quelque_chose entre les guillemets après msgstr.

Vous n'avez pas besoin de traduire toutes les chaînes de caractères dans dans tous les fichiers .po, traduisez uniquement celles qui sont réellement nécessaires aux pages traduites. Pour savoir si vous avez besoin de traduire une chaîne de caractères, lisez les commentaires dans le fichier .po juste au dessus de chaque étiquette msgid. Si le fichier référencé se trouve dans le répertoire english/template/debian, vous devrez alors le traduire à coup sûr. Sinon, vous pourrez le faire plus tard, lorsqu'il sera question de traduire les pages web qui l’utilisent.

Le but de l'utilisation de fichiers po/ est de rendre les choses plus faciles pour les traducteurs, qu'ils n'aient ainsi (presque) jamais besoin d'éditer quoique ce soit dans le répertoire english/template/debian lui-même. Si vous trouvez quoi que ce soit d'erroné dans la manière dont quelque chose est mis en place dans le répertoire des modèles, nous vous prions de vous assurer que le problème est résolu d'une façon générale (n'hésitez pas à demander à quelqu'un d'autre de le faire pour vous), plutôt que de publier les traductions dans les modèles, ce qui serait (habituellement) un problème majeur.

Si vous n'êtes pas sûr d'avoir fait les bonnes modifications, demandez à la liste de diffusion debian-www avant d'envoyer les fichiers dans le dépôt.

REMARQUE : si vous éprouvez le besoin de modifier n’importe quoi d’autre, envoyez un courrier à debian-www indiquant ce que vous avez changé et pourquoi, de façon à ce que le problème soit corrigé.

Une fois que le squelette d'un modèle a été traduit, vous pouvez commencer à traduire la page d'accueil et les autres fichiers *.wml. Pour connaître la liste des fichiers qui doivent être traduits, vérifiez la page de conseils. Traduisez les pages *.wml tel que décrit au début de la page.

Ressusciter des traductions obsolètes

Comme décrit dans la façon de maintenir les traductions à jour, les traductions périmées du site web risquent d'être supprimées automatiquement si beaucoup de temps s'est écoulé sans mise à jour.

Si vous trouvez que certains fichiers ont été supprimés dans le passé et que vous voulez extraire les fichiers à nouveau pour une édition future, vous pouvez chercher dans l’historique des commits en utilisant les commandes normales de Git.

Par exemple, si le fichier supprimé est « supprimé.wml », vous pouvez chercher dans l’historique en exécutant :

   git log --all --full-history -- <chemin/vers/fichier/supprimé.wml>

Vous pouvez retrouver le commit exact qui a supprimé le fichier désiré en même temps que la chaîne de l’empreinte numérique du commit. Pour afficher l’information détaillée sur la modification, vous pouvez utiliser la sous-commande git show :

  git show <COMMIT_HASH_STRING> -- <chemin/vers/fichier/supprimé.wml>

Si le commit est exactement celui qui a supprimé le fichier, vous pouvez restaurer le fichier dans l’espace de travail en utilisant git checkout :

  git checkout <COMMIT_HASH_STRING>^ -- <chemin/vers/fichier/supprimé.wml>

Une fois retrouvé, il faut évidemment mettre à jour le document avant de le renvoyer. Sinon, il risque d'être supprimé par ailleurs.

Le reste de l'histoire

La description ci-dessus sera probablement suffisante pour vous permettre de démarrer. Après, vous pourrez avoir envie de lire les liens ci-dessous qui donnent des explications plus détaillées et de nombreuses informations utiles.

Nous espérons que le travail que nous avons fait vous rendra la tâche de traduction des pages la plus facile possible. Comme cela a déjà été dit, si vous avez des questions, vous pouvez les poser sur la liste debian-www.