Introduction

The text elements in a document produced by AdeliaDoc can be classified into four categories:

• Predefined texts associated with AdeliaDoc annotations and automatically inserted into the documentation during generation:  these are mainly specific texts in Adelia vocabulary such as "procedure", "program", "class", "logical entity", etc.
• Texts relating to the cross-functional features of the documentation, automatically generated by Sphinx when producing documentation: these are mainly texts relating to navigation, search and indexing features and other texts relating to directives used by AdeliaDoc.
• Texts of annotations added by developers.
• If applicable, if there is a substitution, the program description.

All the texts associated with the latter two categories are integrated as they are into the appropriate sections of the generated documentation. As such, they cannot be localized.

For the other two categories, the supported languages are those supported by the version of Sphinx deployed on the machine running AdeliaDoc, a list of which can be viewed on the official website.

Below are the steps for localizing an AdeliaDoc documentation project.

General configuration

As explained in the documentation relating to AdeliaDoc call parameters, a documentation project's language is set when creating the project, i.e. when executing adeliadoc.exe with the action parameter set to "init" and assigning the lang parameter the correct value.

You can, however, change the language code later by manually changing the language parameter in the Sphinx "conf.py" configuration file. This file is in the documentation project root.

The list of supported languages and their codes is available on the Sphinx website.

In addition, in relation to the chosen language, the date retrieval format can be customized by changing the date_sep and date_format parameters of the AdeliaDoc configuration file associated with the documentation project.

Predefined text localization methodology

• French (fr) and English (en) are natively supported by AdeliaDoc as standard. Therefore, no action is required for these two languages unless the translation provided as standard is not appropriate in the regional context (see next point).
• If the translations provided in these two languages are not satisfactory, or localization into another language is required, the method involves creating as many "adeliadoc_localisation_cdlang.txt" files as necessary ("cdlang" must correspond to one of the values of the supported language codes), in the Adelia Studio installation directory (which means they are common to all the documentation projects).
• These files must have the following characteristics: 
  

  • They must have key/value pairs with the following structure and content, with French and English as a translation reference (the digraph "%s" corresponds to the context variable values substituted on execution by AdeliaDoc):

     Reference language: French

    [location]

    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

     Reference language: English

    [location]

    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

• • They must be encoded in UTF-8 without BOM.
  • The texts associated with "documentation_title" and "documentation_purpose" keys correspond to the default values used by AdeliaDoc to generate the home page of a documentation project (which corresponds to the help "home page" in HTML format). This page is initialized when the project is created and is not modified again by AdeliaDoc.
    Therefore, as stated below, it is preferable to customize the home page of each project by adapting these texts as required rather than modifying default values from predefined text localization files which are common to all the projects.
• If the standard format of the date is not appropriate (i.e. the one defined in the regional settings for the current Windows® session), it can be adapted by changing the date_sep and date_format parameters in the AdeliaDoc configuration file associated with each documentation project.
• Finally, as explained in relation to the customization and configuration of the documentation, the default values of the localized texts in the Sphinx configuration file conf.py, as well as those in the file corresponding to the index.rst home page, can be customized for each project.
  In both cases, it is of course vital to comply with the form and syntax rules specific to these files.