Internationalisation

Prise en charge de plusieurs langues

Doxygen prend en charge plusieurs langues de manière intégrée. Cela signifie que les fragments de texte générés par doxygen peuvent être produits dans d'autres langues que l'anglais (par défaut). La langue de sortie est choisie via l'option de configuration OUTPUT_LANGUAGE dans le fichier de configuration (avec le nom par défaut et connu sous le nom de Doxyfile). Pour basculer entre les langues à l'intérieur d'un bloc de commentaires, la commande \~ peut être utilisée.

Actuellement (version 1.14.0), 42 langues sont prises en charge (classées par ordre alphabétique) : afrikaans, arabe, arménien, portugais brésilien, bulgare, catalan, chinois, chinois traditionnel, croate, tchèque, danois, néerlandais, anglais, espéranto, finnois, français, allemand, grec, hindi, hongrois, indonésien, italien, japonais (+ En), coréen (+ En), letton, lituanien, macédonien, norvégien, persan, polonais, portugais, roumain, russe, serbe, serbe cyrillique, slovaque, slovène, espagnol, suédois, turc, ukrainien et vietnamien.

Le tableau des informations relatives aux langues prises en charge est le suivant. Il est classé par langue par ordre alphabétique. La colonne Statut a été générée à partir de sources et indique approximativement la dernière version à laquelle le traducteur a été mis à jour.

La plupart des personnes sur la liste ont indiqué qu'elles étaient également occupées à faire d'autres choses, donc si vous voulez aider à accélérer les choses, faites-le-leur savoir (ou à moi).

Si vous souhaitez ajouter la prise en charge d'une langue qui n'est pas encore répertoriée, veuillez lire la section suivante.

Ajouter une nouvelle langue à doxygen

Ce court HOWTO explique comment ajouter la prise en charge de la nouvelle langue à doxygen :

Suivez simplement les étapes suivantes :

1 . Dites-moi pour quelle langue (par exemple VotreLangue) vous souhaitez ajouter la prise en charge. Si personne d'autre ne travaille déjà sur la prise en charge de cette langue, vous serez désigné comme responsable de la maintenance de la langue.

2 . Ajoutez au fichier doxygen/src/config.xml, à l'endroit approprié dans la partie OUTPUT_LANGUAGE, la ligne :

<value name='YourLanguage'/>

3 . Créez une copie de doxygen/src/translator_en.h et nommez-la doxygen/src/translator_<your_2_letter_country_code>.h J'utiliserai xx dans le reste de ce document (et XX pour la version en majuscules).

4 . Modifiez doxygen/src/language.cpp : Ajoutez le code suivant :

#include<translator_xx.h>

Maintenant, dans setTranslator(), ajoutez

case OUTPUT_LANGUAGE_t::YourLanguage: theTranslator = new TranslatorYourLanguage; break;

5 . Editez doxygen/src/translator_xx.h :

• Utilisez l'éditeur compatible UTF-8 et ouvrez le fichier en utilisant le mode UTF-8 (mode non BOM).
• Renommez TRANSLATOR_EN_H en TRANSLATOR_XX_H deux fois (c'est-à-dire dans les commandes de préprocesseur #ifndef et #define au début du fichier).
• Renommez TranslatorEnglish en TranslatorYourLanguage
• Dans le membre idLanguage(), remplacez « english » par le nom de votre langue (utilisez uniquement des caractères minuscules). Selon la langue, vous souhaiterez peut-être également modifier les fonctions membres latexLanguageSupportCommand() et autres (vous les reconnaîtrez lorsque vous commencerez le travail).
• Modifiez toutes les chaînes renvoyées par les fonctions membres qui commencent par tr. Essayez de faire correspondre la ponctuation et les majuscules ! Pour saisir des caractères spéciaux (avec des accents), vous pouvez :

  • Les saisir directement si votre clavier le prend en charge. N'oubliez pas que le texte est censé être enregistré en utilisant le codage UTF-8. Doxygen traduira les caractères en correct et laissera la sortie HTML et man en UTF-8.
  • Utilisez des codes HTML comme ä pour un a avec un tréma (c'est-à-dire ä). Voir la spécification HTML pour les codes.

6 . Modifiez doxygen/doc/maintainers.txt et ajoutez-vous à la liste des mainteneurs comme :

TranslatorYourLanguage
<your name>: <your dot email at your dot domain>

7 . Créez la documentation en passant la commande de construction appropriée (comme : make docs).

8 . Vous pouvez maintenant utiliser OUTPUT_LANGUAGE = your_language_name dans le fichier de configuration pour générer une sortie dans votre langue.

9 . La méthode préférée est de cloner le dépôt doxygen sur GitHub et de faire une Pull Request. Vous pouvez également m'envoyer le fichier translator_xx.h afin que je puisse l'ajouter à doxygen. Envoyez également votre nom et votre adresse e-mail pour être inclus dans la liste maintainers.txt.

Maintenir une langue

Les nouvelles versions de doxygen peuvent utiliser de nouvelles phrases traduites. Dans une telle situation, la classe Translator nécessite l'implémentation de nouvelles méthodes : son interface change. Bien entendu, les phrases anglaises doivent être traduites dans les autres langues. Au moins, les nouvelles méthodes doivent être implémentées par la classe de traduction liée à la langue ; sinon, doxygen ne compilerait même pas. Attendre que tous les responsables de la langue aient traduit les nouvelles phrases et envoyé les résultats ne serait pas très pratique. Le texte suivant décrit l'utilisation des adaptateurs de traduction pour résoudre le problème.

Le rôle des adaptateurs de Translator. Lorsque l'interface de la classe Translator est modifiée dans une nouvelle version, la nouvelle classe TranslatorAdapter_x_y_z est ajoutée au fichier translator_adapter.h (ici x, y et z sont des nombres qui correspondent à la version officielle actuelle de doxygen). Tous les traducteurs qui dérivaient auparavant de la classe Translator dérivent désormais de cette classe d'adaptateur.

La classe TranslatorAdapter_x_y_z implémente les nouvelles méthodes requises. Si la nouvelle méthode remplace une ou plusieurs méthodes similaires mais obsolètes (par exemple si le nombre d'arguments a changé et/ou si la fonctionnalité de l'ancienne méthode a été modifiée ou enrichie), la classe TranslatorAdapter_x_y_z peut utiliser la méthode obsolète pour obtenir le résultat le plus proche possible de l'ancien résultat dans la langue cible. Si ce n'est pas possible, le résultat (la traduction par défaut) est obtenu à l'aide du traducteur anglais, qui est (par définition) toujours à jour.

Par exemple, lorsque la nouvelle méthode trFile() avec paramètres (pour déterminer la mise en majuscule de la première lettre et la forme singulière/plurielle) a été introduite pour remplacer l'ancienne méthode trFiles() sans arguments, le code suivant est apparu dans l'une des classes d'adaptateurs de traducteur :

/*! Ceci est l'implémentation par défaut de la méthode obsolète
  * utilisée dans la documentation d'un groupe avant la liste des
  * liens vers les fichiers documentés. Ceci est peut-être localisé.
  */
virtual QCString trFiles()
{ return "Files"; }

/*! Ceci est l'implémentation localisée de l'équivalent plus récent
  * utilisant la méthode obsolète trFiles().
  */
virtual QCString trFile(bool first_capital, bool singular)
{
  if (first_capital && !singular)
    return trFiles(); // méthode éventuellement localisée et obsolète
  else
    return english.trFile(first_capital, singular);
}

La méthode trFiles() n'est pas présente dans la classe TranslatorEnglish, car elle a été supprimée étant obsolète. Cependant, elle était utilisée jusqu'à présent et son appel a été remplacé par :

trFile(true, false)

dans les fichiers sources doxygen. Il est probable que de nombreux traducteurs de langues aient implémenté la méthode obsolète, il est donc parfaitement logique d'utiliser le même résultat dépendant de la langue dans ces cas. TranslatorEnglish n'implémente pas l'ancienne méthode. Elle dérive de la classe abstraite Translator. D'autre part, l'ancien traducteur pour une autre langue n'implémente pas la nouvelle méthode trFile(). Pour cette raison, elle dérive d'une autre classe de base – TranslatorAdapter_x_y_z. La classe TranslatorAdapter_x_y_z doit implémenter la nouvelle méthode trFile() requise. Cependant, l'adaptateur de traducteur ne serait pas compilé si la méthode trFiles() n'était pas implémentée. C'est la raison pour laquelle l'ancienne méthode a été implémentée dans la classe d'adaptateur de traducteur (en utilisant le même code, qui a été supprimé de TranslatorEnglish).

Le moyen le plus simple serait de passer les arguments au traducteur anglais et de renvoyer son résultat. Au lieu de cela, l'adaptateur utilise l'ancien trFiles() dans un cas particulier – lorsque le nouveau trFile(true, false) est appelé. C'est le cas le plus utilisé au moment de l'introduction de la nouvelle méthode - voir ci-dessus. Bien que cela puisse paraître trop compliqué, la technique permet aux développeurs des sources principales de modifier l'interface du traducteur, tandis que les utilisateurs peuvent même ne pas remarquer le changement. Bien sûr, lorsque le nouveau trFile() est utilisé avec des arguments différents, le résultat anglais est renvoyé et il sera remarqué par les utilisateurs non anglophones. Ici, le mainteneur du traducteur de langue doit implémenter au moins cette méthode particulière.

Que dit la classe de base d'un traducteur de langue ? Si la classe du traducteur de langue hérite d'une classe d'adaptateur, une maintenance est nécessaire. Dans ce cas, le traducteur de langue est considéré comme non à jour. En revanche, si le traducteur de langue dérive directement de la classe abstraite Translator, le traducteur de langue est à jour.

Les classes d'adaptateur de traducteur sont chaînées de sorte que l'ancienne classe d'adaptateur de traducteur utilise l'adaptateur de traducteur plus récent comme classe de base. L'adaptateur le plus récent effectue moins de travail d'adaptation que l'ancien. La classe d'adaptateur la plus ancienne dérive (indirectement) de toutes les classes d'adaptateur. Le nom de la classe d'adaptateur est choisi de manière à ce que son suffixe soit dérivé de la version officielle précédente de doxygen qui n'avait pas besoin de l'adaptateur. De cette façon, on peut dire approximativement quand la classe de traducteur de langue a été mise à jour pour la dernière fois - voir les détails ci-dessous.

L'adaptateur de traducteur le plus récent dérive de la classe abstraite TranslatorAdapterBase qui dérive directement de la classe abstraite Translator. Il ajoute uniquement le membre privé English-translator pour une implémentation facile de la traduction par défaut dans les classes d'adaptateur, et il impose également l'implémentation d'une méthode pour notifier à l'utilisateur que la traduction de langue n'est pas à jour (à cause de cela, certaines phrases dans les fichiers générés peuvent apparaître en anglais).

Une fois que la classe d'adaptateur la plus ancienne n'est plus utilisée par aucun des traducteurs de langue, elle peut être supprimée du projet doxygen. Les responsables doivent essayer d'atteindre l'état avec le nombre minimal de classes d'adaptateur de traducteur.

Pour simplifier la maintenance des classes de traducteur de langue pour les langues prises en charge, le script Python translate.py a été développé (situé dans le répertoire doxygen/doc). Il extrait les informations importantes sur les méthodes obsolètes et nouvelles des fichiers sources pour chacune des langues. Les informations sont stockées dans le fichier ASCII du rapport du traducteur (translator_report.txt).

Vous pouvez trouver ce fichier sous le nom de translater_report.txt.

En regardant la classe de base du traducteur de langue, le script devine également le statut du traducteur – voir la dernière colonne du tableau avec les langues ci-dessus. Le fichier translater.py est appelé automatiquement lorsque la documentation doxygen est générée. Vous pouvez également exécuter le script manuellement chaque fois que vous pensez qu'il peut vous aider. Bien entendu, vous n'êtes pas obligé d'utiliser les résultats du script. Vous pouvez trouver les mêmes informations en regardant la classe d'adaptateur et ses classes de base.

Comment dois-je mettre à jour mon traducteur de langue ? Tout d'abord, vous devez être le mainteneur de la langue ou l'informer des changements. Le texte suivant a été écrit pour les mainteneurs de la langue en tant que public principal.

Il existe plusieurs approches à adopter lors de la mise à jour de votre langue. Si vous n'êtes pas extrêmement occupé, vous devez toujours choisir la plus radicale. Lorsque la mise à jour prend beaucoup plus de temps que prévu, vous pouvez toujours décider d'utiliser un adaptateur de traducteur approprié pour terminer les modifications plus tard et faire fonctionner votre traducteur.

La manière la plus radicale de mettre à jour le traducteur de langue est de faire dériver votre classe de traducteur directement de la classe abstraite Translator et de fournir des traductions pour les méthodes qui doivent être implémentées - le compilateur vous dira si vous avez oublié d'en implémenter certaines. En cas de doute, jetez un œil à la classe TranslatorEnglish pour reconnaître le but de la méthode implémentée. Regarder la classe d'adaptateur utilisée précédemment peut parfois vous aider, mais cela peut aussi être trompeur car les classes d'adaptateur implémentent également les méthodes obsolètes (voir l'exemple précédent de trFiles()).

En d'autres termes, les traducteurs de langue à jour n'ont pas du tout besoin des classes TranslatorAdapter_x_y_z, et vous n'avez pas besoin d'implémenter autre chose que les méthodes requises par la classe Translator (c'est-à-dire les méthodes virtuelles pures du Translator - elles se terminent par =0;).

Si tout se compile correctement, essayez d'exécuter le fichier translator.py et jetez un œil au rapport du traducteur (fichier ASCII) dans le répertoire doxygen/doc. Votre traducteur est marqué comme à jour uniquement si le script ne détecte rien de spécial. Si le traducteur utilise la classe de base Translator, il peut encore y avoir des remarques liées à votre code source. Dans ce cas, le traducteur est marqué comme presque à jour. À savoir, les méthodes obsolètes - qui ne sont pas du tout utilisées - peuvent être répertoriées dans la section pour votre langue. Supprimez simplement leur code (et exécutez à nouveau le fichier translator.py). De plus, vous serez informé lorsque vous aurez oublié de modifier la classe de base de votre classe de traducteur vers une classe d'adaptateur plus récente ou directement vers la classe Translator.

Si vous n'avez pas le temps de terminer toutes les mises à jour, vous devriez quand même commencer par l'approche la plus radicale décrite ci-dessus. Vous pouvez toujours remplacer la classe de base par la classe d'adaptateur de traducteur qui implémente toutes les méthodes non encore implémentées.

Si vous préférez mettre à jour votre traducteur progressivement, jetez un œil à TranslatorEnglish (le fichier translate_en.h). À l'intérieur, vous trouverez les commentaires comme new since 1.2.4 qui séparent toujours un certain nombre de méthodes qui ont été implémentées dans la version indiquée. Implémentez le groupe de méthodes qui sont placées sous le commentaire qui utilise les mêmes numéros de version que votre classe d'adaptateur de traducteur. (Par exemple, votre classe de traducteur doit utiliser TranslatorAdapter_1_2_4, si elle n'implémente pas les méthodes sous le commentaire new since 1.2.4). Lorsque vous les implémentez, votre classe doit utiliser un adaptateur de traducteur plus récent.

Exécutez le script translater.py de temps en temps et donnez-lui votre identification xx (depuis translater_xx.h) pour créer un rapport de traducteur plus court (également produit plus rapidement) - il ne contiendra que les informations relatives à votre traducteur. Une fois que vous atteignez l'état où la classe de base doit être remplacée par un adaptateur plus récent, vous verrez la note dans le rapport du traducteur.

Attention : n'oubliez pas de compiler doxygen pour découvrir s'il est compilable. Le translater.py ne vérifie pas si tout est correct par rapport au compilateur. À cause de cela, il peut parfois mentir sur la classe de base nécessaire.

Les traducteurs de langue les plus obsolètes conduiraient à l'implémentation d'adaptateurs trop compliqués. À cause de cela, les développeurs de doxygen peuvent décider de dériver ces traducteurs de la classe TranslatorEnglish, qui est par définition toujours à jour.

Ce faisant, toutes les méthodes manquantes seront remplacées par la traduction anglaise. Cela signifie que les méthodes non implémentées renverront toujours le résultat anglais. De tels traducteurs sont marqués à l'aide du mot obsolete. Vous devriez lire vraiment obsolète. Aucune estimation de la dernière mise à jour ne peut être faite.

Il est souvent possible de construire de meilleurs résultats à partir des méthodes obsolètes. Pour cette raison, les classes d'adaptateur de traducteur doivent être utilisées si possible. D'un autre côté, l'implémentation d'adaptateurs pour des traducteurs vraiment obsolètes entraîne trop de frais de maintenance et d'exécution.