Présentation

Les éléments textuels constitutifs d'une documentation produite par AdeliaDoc peuvent être classés selon quatre catégories :

• Les textes prédéfinis associés aux annotations AdeliaDoc, et insérés automatiquement dans la documentation lors de la génération :  il s'agit principalement des textes spécifiques au vocabulaire Adélia tels que  "procédure", programme", "classe", "entité logique", etc.
• Les textes liée aux fonctionnalités transversales du support de documentation, générés automatiquement par Sphinx lors de la production de la documentation : il s'agit principalement de textes relatifs aux fonctionnalités de navigation, recherche, indexation, et autres textes liés à des directives utilisées par AdeliaDoc.
• Les textes issus des annotations ajoutées par les développeurs.
• Le cas échant, en cas de substitution, les désignations de programmes

L'ensemble des textes associés aux deux dernières catégories sont intégrés en l'état dans les rubriques appropriées de la documentation générée. En tant que tels, ils ne sont donc pas localisables.

Pour les deux autres catégories, les langues supportées sont celles supportées par la version de Sphinx qui a été déployée sur le poste où s'exécute AdeliaDoc, et dont la liste est consultable sur le site officiel.

Le cadre ayant été établi, sont détaillées ci-dessous les étapes à suivre pour localiser un projet de documentation AdeliaDoc.

Configuration générale

Comme expliqué dans la documentation relative aux paramètres d'appels d'AdeliaDoc, la langue d'un projet de documentation est fixée lors de la création du projet, c'est-à-dire lors de l'exécution de adeliadoc.exe avec le paramètre action  positionné à "init", en valorisant correctement le paramètre lang .

Il est néanmoins possible de changer a posteriori le code de la langue, en modifiant manuellement le paramètre language du fichier de configuration Sphinx "conf.py". Ce fichier est situé à la racine du projet de documentation.

La liste et la codification des langues supportées est quant à elle consultable sur le site de Sphinx.

Par ailleurs, en lien avec la langue choisie, le format de restitution des dates peut être personnalisé en modifiant en conséquence les paramètres date_sep et date_format du fichier de configuration AdeliaDoc associé au projet de documentation.

Méthodologie de localisation des textes prédéfinis

• En standard, les langues française (fr) et anglaise (en) sont nativement supportées par AdeliaDoc. Aucune action n'est donc requise pour ces deux langues, sauf si la traduction proposée en standard n'est pas satisfaisante dans le contexte régional (cf. point suivant).
• Dans le cas où les traductions proposées dans ces deux langues ne sont pas satisfaisantes, ou dans le cas d'un besoin de localisation dans une langue autre, la méthode consiste à créer autant de fichiers "adeliadoc_localisation_cdlang.txt" que nécessaire ("cdlang" doit correspond à une des valeurs des codes langues supportées), dans le répertoire d'installation d'Adélia Studio (ce qui veut dire qu'ils sont communs à l'ensemble des projets de documentation).
• Ces fichiers doivent répondre aux caractéristiques suivantes : 
  

  • Ils doivent être constitués de paires clé/valeur, selon la structuration et le contenu suivant, avec comme référence de traduction les langues française et anglaise (le digramme "%s" correspondant à des valeurs de variables contextuelles substituées à l'exécution par AdeliaDoc) :

     Langue de référence : francais

    [localisation]

    program = Programme %s (%s)

    procedure = Procédure %s

    class = Classe %s (%s)

    logical_entity = Entité logique %s 

    parameters = Paramètres

    members = Attributs

    modified = Modifié le : %s

    version = Version

    parameter_out = Entrée

    parameter_in = Sortie

    documentation_title = Bienvenue dans la documentation %s

    documentation_purpose = Cette documentation contient des rubriques d'aide sur les programmes et les procédures publiques

    contents = Rubriques

    indices = Index

     Langue de référence : anglais

    [localisation]

    program = Program %s (%s)

    procedure = Procedure %s

    class = Class %s (%s)

    logical_entity = Logical entity %s 

    parameters = Parameters

    members = Members

    modified = Modification date : %s

    version = Version

    parameter_out = Out

    parameter_in = Indocumentation_title = Welcome to %s documentation

    documentation_purpose = This documentation contains help topics about programs and public procedures.

    contents = Contents

    indices = Indices and tables

• • Ils doivent être encodés en UTF-8 sans BOM.
  • Les textes associés aux clés "documentation_title" et "documentation_purpose" correspondent à des valeurs par défaut utilisées par AdeliaDoc pour générer la page d'accueil d'un projet de documentation (ce qui correspond à la "home page" de l'aide au format HTML). Cette page est initialisée à la création du projet, et n'est plus jamais modifiée par AdeliaDoc.
    De ce fait, et comme indiqué ci-dessous, il est préférable de personnaliser, projet par projet, la page d'accueil en adaptant ces textes en fonction des besoins, plutôt que d'agir au niveau des ces valeurs par défaut issues des fichiers de localisation des textes prédéfinis, qui eux sont communs à tous les projets.
• Si le format standard de la date ne convient pas (c'est-à-dire celui défini au niveau des paramètres régionaux de la session Windows® courante), il peut être adapté en modifiant en conséquence les paramètres date_sep et date_format du fichier de configuration AdeliaDoc associé à chaque projet de documentation.
• Enfin, et comme présenté dans le cadre de la personnalisation et de la configuration de la documentation, il est possible pour chaque projet de personnaliser les valeurs par défaut des textes localisés figurant dans le fichier de configuration Sphinx conf.py, ainsi que ceux situés dans le fichier correspondant à la page accueil index.rst.
  Dans les deux cas, il est bien sûr indispensable de respecter le formalisme et la syntaxe propres à ces fichiers.