Ansel utilise Gettext  pour traduire toutes les parties du projet :

  • L’application logicielle (écrite en C),
  • Le site web (modèles Hugo et contenu Markdown),
  • La documentation/manuel utilisateur, inséré dans le site web en tant que module (modèles Hugo et contenu Markdown aussi).

Cela garantit que le même flux de travail peut être utilisé pour traduire tous les fichiers, mais aussi que certaines chaînes traduites peuvent être partagées (par exemple, les contrôles du GUI traduits de l’application peuvent être directement insérés dans la documentation).

Organisation des fichiers de traduction

Le code source du site web, de la documentation et du logiciel contient tous un sous-dossier po/ immédiat, contenant :

  • un fichier .pot qui contient toutes les chaînes disponibles et traduisibles dans leur langue originale (en anglais),
  • de nombreux fichiers .po correspondant aux chaînes traduisibles dans leur langue originale avec leur traduction (dans un fichier par langue).

Les fichiers de traduction sont tous nommés en suivant la convention code-langue.po. Par exemple :

  • pour l’allemand,
    • la traduction du logiciel est de.po,
    • la traduction du site web est content.de.po,
    • la traduction de la documentation est content.de.po,
  • pour le portugais brésilien,
    • la traduction du logiciel est pt_BR.po,
    • la traduction du site web est content.pt_br.po,
    • la traduction de la documentation est content.pt_br.po.

Traduire quand vous ne pouvez pas utiliser CLI/Git

Vous devrez localiser le fichier .po pertinent pour votre langue pour la partie du projet que vous souhaitez traduire :

  1. Téléchargez ce fichier et ouvrez-le avec Poedit ,
  2. Effectuez les corrections et modifications nécessaires,
  3. Ajoutez votre nom dans un commentaire pour les chaînes que vous traduisez si vous souhaitez être crédité sur la page :
    • Les chaînes traduites automatiquement auront TRANSLATOR ChatGPT là, une fois que vous vérifiez ces chaînes, veuillez supprimer cette ligne,
    • Ajoutez ensuite un commentaire contenant TRANSLATOR Votre Nom sur une nouvelle ligne. Gardez les autres contributeurs (non ChatGPT) là, s’il y en a.
  4. Enregistrez le fichier et :
    • Alternative 1 (plus facile pour le contributeur, plus d’étapes pour le mainteneur): déposez-le sur mon cloud privé ,
    • Alternative 2 (plus d’étapes pour le contributeur, plus facile pour le mainteneur): soumettez-le avec Git et ouvrez une demande de fusion contre le dépôt Github approprié.

Traduction pour les utilisateur avancés

Cela mettra à jour le fichier .pot en utilisant le code source du projet. Vous devrez avoir Git installé, et Hugo 0.146  installé sur votre ordinateur.

  1. Clonez le code source du projet concerné :
    • le logiciel :
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel.git
3$ cd ansel
    • le site web :
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel-website.git
3$ cd ansel-website
    • la documentation :
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel-doc.git
3$ cd ansel-doc
    Ensuite, mettez à jour le dépôt en utilisant :
    1$ git pull
  2. Mettez à jour les fichiers .pot et .po du code source (cette étape est la même pour les 3 projets) :
    1$ sh tools/update-translations.sh
  3. Traduisez le fichier .po pertinent en utilisant Poedit ou directement dans un éditeur de texte (voir Traduction sans CLI/Git),
  4. Testez et révisez votre traduction :
    • Pour le logiciel, vous devrez construire Ansel sur votre OS. Veuillez consulter la documentation.
    • Pour le site web et la documentation, vous pouvez exécuter :
      1sh build-modules.sh
2hugo
    Méfiez-vous des erreurs critiques de po4a, notamment pour les caractères \n mal appariés, et des erreurs de Hugo, notamment concernant la syntaxe des shortcodes.
  5. Pour le site web et la documentation, nettoyez les fichiers Markdown traduits (générés automatiquement par po4a utilisant le fichier .po) avant de faire un commit, en utilisant :
    1sh tools/build-translations.sh --remove
  6. Commentez tous les fichiers .pot et .po et ouvrez une demande de fusion contre le dépôt Github pertinent. Ne jamais commenter les fichiers traduits .md (Markdown).

Traduire les images

Ce qui suit s’applique uniquement au site web et à la documentation.

Les images peuvent être traduites également, par exemple les captures d’écran de l’application. Les images sont stockées dans le dossier assets/ si elles sont réutilisées sur plusieurs pages (ressources globales), sinon, elles sont stockées dans le même dossier que le fichier Markdown qui les utilise (ressources locales). Qu’elles soient globales ou locales, le processus de traduction est le même, seule la base du dossier change.

Si, par exemple, vous souhaitez traduire le fichier assets/screenshot.jpg pour la langue LANG (qui est le code ISO de la langue, comme de, nl, pt_br, zn_cn, etc.) :

  1. ajoutez et commentez un nouveau fichier d’image assets/screenshot.LANG.jpg dans le dépôt Git de la documentation ou du site web,
  2. dans le fichier content.LANG.po, localisez l’entrée contenant la balise Markdown de l’image originale, qui sera quelque chose comme ![texte alternatif](screenshot.jpg),
  3. traduisez la balise Markdown en remplaçant l’URL de l’image, comme ![texte alternatif traduit](screenshot.LANG.jpg,
  4. enregistrez et commentez le fichier content.LANG.po,
  5. créez une demande de fusion contre le dépôt du site web Ansel ou des docs Ansel.

Outils automatiques et scripts d’assistance

Initialiser la traduction de la documentation avec celle du logiciel

Parce que la documentation et le logiciel partagent les mêmes chaînes pour les contrôles du GUI, vous pouvez paresseusement initier les chaînes de la documentation à partir de celles du logiciel si elles correspondent exactement (y compris la casse). Cela nécessite un interprète Python et le package regex (installez avec pip install -U regex). À partir du code source de la documentation, vous pouvez appeler :

1$ python tools/merge-translations.py chemin/vers/software chemin/vers/doc

Traduction automatique de la documentation et du site web avec ChatGPT

ChatGPT-4o fait un très bon travail de traduction de texte formaté en Markdown à partir de l’anglais, bien que pas dans toutes les langues. Vous aurez besoin d’une clé API privée à stocker dans le dossier de la documentation ou du site web dans un fichier .chatgpt.api_key. Ensuite, les appels à l’API ChatGPT ne sont pas gratuits, et le paiement minimal de 5 $US vous permet de traduire entièrement le site web en 4 langues.

Le script tout-en-un peut être appelé en utilisant :

1$ sh auto-translate.sh LANG

où LANG est le code de la langue cible (de, fr, pt_br, etc.). Cela traitera la traduction par lots de 90 à 120 chaînes pour se conformer aux limitations de l’API ChatGPT. Cela :

  • analyse le fichier original po/content.LANG.po et exporte le lot à traduire dans un fichier temporaire po/content.LANG.txt,
  • envoie le fichier po/content.LANG.txt à ChatGPT et récupère la réponse dans po/content.LANG.generated.txt,
  • corrige les incohérences de formatage les plus courantes que ChatGPT peut introduire et injecte les traductions dans po/content.LANG.po,
  • construit des fichiers Markdown traduits (en suivant la convention de nommage page.LANG.md),
  • construit le site web avec Hugo.

Si toutes ces étapes se terminent sans erreur, alors vous pouvez exécuter à nouveau le script pour traiter le prochain lot jusqu’à la fin. Si des erreurs apparaissent, vous devrez les corriger. Nous exécutons un seul lot à chaque appel pour laisser à l’utilisateur l’opportunité de trouver des erreurs tant qu’il n’y a pas trop de modifications à inspecter.

Erreurs courantes :

  • rien ne sera traduit : vérifiez la réponse de ChatGPT dans le fichier po/content.LANG.generated.txt, parfois il est incapable de comprendre sa mission. Vous pouvez essayer à nouveau, parfois ça marche au 3ème appel. Mais souvent, il n’y a rien à faire et certaines langues/chaînes ne peuvent pas être traduites du tout.
  • lors de la construction du site web avec Hugo, certains shortcodes ne peuvent pas être trouvés. C’est parce que les shortcodes sont déclarés comme ceci : {{< shortcode_name >}}. Parfois, ChatGPT essaiera de traduire shortcode_name et le shortcode ne fonctionnera plus. La solution est de ramener le nom anglais pour le shortcode et ses attributs,
  • même chose avec les graphes Mermaid , ChatGPT peut essayer de traduire des commandes et propriétés qui ne devraient pas être traduites,
  • les chaînes originales se terminent par le caractère de nouvelle ligne \n et les chaînes traduites ne le font pas (ou l’inverse). Le script essaie de nettoyer cela, mais certains cas limites ne sont pas pris en charge. Les chaînes originales msgid et leur traduction msgstr dans le fichier .po doivent avoir le même nombre de caractères \n au même endroit,
  • guillemets doubles incorrectement échappés : les chaînes Gettext msgid et msgstr doivent être délimitées par des guillemets doubles non échappés " à chaque extrémité de la chaîne. Tout autre guillemet double, dans la chaîne Gettext, doit être échappé en utilisant \".

La meilleure façon de corriger les erreurs est d’ouvrir le fichier .po pertinent dans un éditeur de texte. Si vous ne trouvez pas l’erreur et ne parvenez pas à la résoudre, vous pouvez essayer d’ouvrir le fichier dans Poedit, mais en sauvegardant, cela effacera généralement complètement les chaînes défectueuses sans les corriger, donc la traduction devra être recommencée depuis le début.

Construire des fichiers Markdown traduits

Pour le site web et la documentation, Hugo  gère les traductions de n’importe quelle page donnée new_page.md en utilisant la convention de nommage new_page.LANG.md, où LANG est le code de langue. Hugo prend en charge nativement l’écriture manuelle de ces fichiers traduits dans le même dossier que leur original, cependant, ici nous les générons en utilisant le fichier de traduction .po et le programme po4a. Les scripts build-modules.sh et tools/auto-translate.sh gèrent cela en interne, mais vous pourriez vouloir générer ces fichiers manuellement :

  1. Mettez à jour les fichiers .pot et .po avec le code source :
    1$ sh tools/update-translations.sh
  2. Créez les fichiers .md traduits :
    1$ sh tools/build-translations.sh --add
  3. Nettoyez les fichiers .md traduits :
    1$ sh tools/build-translations.sh --remove

Il est important de ne jamais commettre les fichiers .md traduits avec Git, car ils sont régénérés uniquement à partir de ce script lors de la construction du site web. Cela est uniquement pour l’hygiène du dépôt, il n’y a pas de désavantage technique. Nettoyer les fichiers .md traduits avant de les valider garantit l’absence d’erreurs.

Perdu dans la traduction ?

Si vous avez des soucis ou des questions, n’hésitez pas à demander sur le canal dédié aux traducteurs Matrix .

Notes aux traducteurs

Politique sur les majuscules

Le projet darktable a donné la priorité à tout mettre en minuscules, ce qui rend l’interface difficile à lire, surtout pour les infobulles comportant plusieurs phrases. Les majuscules ancrent visuellement le début des phrases et d’autres textes importants, comme les boutons, les contrôles, etc. Ce n’est pas un hasard si toutes les langues ont convergé vers leur utilisation (bien que l’allemand ait sa manière particulière de les mettre partout), elles aident à la lisibilité, que vous aimiez leur esthétique ou non.

Le code source d’Ansel réutilise la plupart des étiquettes de darktable et ajoute une majuscule initiale dans la plupart des endroits où elles sont nécessaires (en-têtes de module, boutons). Cela est fait par un peu de code utilisant la fonction C g_unichar_toupper() de Gtk Glib, de sorte que le texte anglais d’origine reste en minuscules pour conserver la compatibilité avec les traductions.

Cette correction programmatique fonctionne pour les caractères non accentués, quelle que soit la langue utilisée (chaînes par défaut en anglais ou traductions). Cependant, elle ne fonctionne pas pour les caractères accentués initiaux, qui ne seront pas mis en majuscules. Dans ce cas, il est demandé aux traducteurs de forcer leur traduction à utiliser des caractères accentués initiaux en majuscules lorsqu’ils sont grammaticalement corrects dans leur langue.

Les nouvelles étiquettes ou les anciennes étiquettes récemment modifiées (ce qui briserait de toute façon les traductions) auront des majuscules initiales à partir de maintenant, dans le code source (version anglaise), pour que cela soit progressivement corrigé.

Traduction des termes techniques

Les termes techniques liés à la théorie des couleurs et à la colorimétrie doivent être traduits exactement de l’anglais, avec une attention particulière car ces termes peuvent également exister dans le langage courant (non technique) mais avec un sens différent. La Commission électrotechnique internationale  fournit un moteur de recherche où vous pouvez rechercher les termes techniques anglais et obtenir les traductions précises dans différentes langues, y compris les principales langues européennes ainsi que l’arabe et le chinois.

Notes aux traducteurs francophones

La traduction de darktable comporte des bizarreries incompréhensibles pour quiconque utilise un ordinateur de bureau depuis plus de 10 ans. Voici une liste rapide des erreurs à corriger :

  • “set” est traduit “positionné” mais sa traduction correcte est “réglé”. C’est illogique car “settings” est correctement traduit “réglages”. Dans Ansel, on ne positionne que des masques (ou leurs nœuds de contrôle) dans le plan 2D. Le reste, ce sont des réglages.
  • “reset” est traduit “repositionné” mais sa traduction correcte est “réinitialiser”.
  • En anglais, un grand nombre de verbes ont la même graphie pour leur infinitif et leur participe-passé, voire même existent comme substantif (“set”, dans l’exemple ci-dessus, peut être traduit “réglé” ou “régler” ou comme “ensemble” sous sa forme substantivée). Si une action (pas encore effectuée) est requise, l’infinitif doit être utilisé en français. Si une action est déjà effectuée, c’est le participe-passé qui doit être employé. Les choses se corsent pour les substantifs car l’anglais ne requiert pas toujours de déterminant devant, il faut donc le déduire du contexte. À surveiller : “click” (cliquer ou clic), “type” (type ou entrer/taper), etc.
Translated from English by : Aurélien Pierre, ChatGPT. In case of conflict, inconsistency or error, the English version shall prevail.