XmlTranslationFile

Navigate through the wiki

In this page is discussed the content of the translation file and how to add your favourite language into it.

• Introduction
• Contents
  • Meaning of {i}
• Adding a translation

Introduction

The translation file contains information which are used to generate :

• the comments (à la doxygen) of the methods,
• specific names, like 'copy constructor', 'std getter', ...
• messages printed in the terminal by the program.

There can be as many language present as wanted in the translation file, the only constraints are:

1. the English translation is present,
2. the file can be validated against Language.xsd (i.e. all the needed fields are present).

Back on top

Contents

The minimal file is:

<?xml version="1.0" encoding="UTF-8"?>

<translations xmlns="http://www.w3schools.com"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.w3schools.com Languages.xsd">

  <!-- File containing the messages used by XmlCppClassGenerator. The
       only requirement is that the english language is present. The
       file can be checked against a xml schema file,
       Language.xsd. Any language compatible with utf-8 encoding can
       be used. -->

  <translation language="en">
    <!-- English set of messages, this MUST be present in the file,
         since it is the default language. -->
    <langName> English </langName>
    <nativeName> English </nativeName>
    <comments>
      <stdGetter nbr="1"> /** @brief Getter for {0}.\n  *\n  * Allows to access {0}.\n  *\n  * @return a const reference on {0}.\n  */ </stdGetter>
      <stdSetter nbr="2"> /** @brief Setter for {0}.\n  *\n  * Allows to change the value of {0}.\n  *\n  * @param {1} new value of {0}.\n  */ </stdSetter>
      <ptrGetter nbr="1"> /** @brief Getter for {0}.\n  *\n  * Allows to get a pointer on {0}.\n  *\n  * @return a const pointer on {0}.\n  */ </ptrGetter>
      <ptrSetter nbr="2"> /** @brief Setter for {0}.\n  *\n  * Allows to change the value of {0}.\n  *\n  * @param[in] {1} pointer on new value of {0}.\n  */ </ptrSetter>
      <refGetter nbr="1"> /** @brief Getter for {0}.\n  *\n  * Allows to access {0}.\n  *\n  * @return a reference on {0}.\n */ </refGetter>
    </comments>
    <strings>
      <constructor> constructor </constructor>
      <destructor> destructor </destructor>
      <getter> getter </getter>
      <setter> setter </setter>
      <refGetter> reference getter </refGetter>
      <method> method </method>
      <member> member </member>
      <copyConstructor> copy constructor </copyConstructor>
      <affectationOperator> affectation operator </affectationOperator>
      <comparisonOperator> comparison operator </comparisonOperator>
      <class> class </class>
      <struct> structure </struct>
      <header> header </header>
      <implementation> implementation file </implementation>
      <local> local </local>
      <system> system </system>
    </strings>
    <prgmMessages>
      <rootElementError nbr="1"> Check your input file &apos;{0}&apos; is not the root element </rootElementError>
      <ioError nbr="2"> I/O error({0}) : {1}.\n </ioError>
      <objectFound nbr="1"> Found description for a &apos;{0}&apos; object. </objectFound>
      <moveInfo nbr="1"> Will save the copy of {0} to {0}.BAK. </moveInfo>
      <addItem nbr="2"> Adding a &apos;{0}&apos; {1}. </addItem>
      <genMethod nbr="3"> Auto adding a &apos;{0}&apos; {1} for {2}. </genMethod>
      <alreadyPresent nbr="2"> A {0} is already present in {1}. </alreadyPresent>
      <objExist nbr="1"> An object {0} exists. </objExist>
      <objIsFile nbr="1"> The object {0} is a file. </objIsFile>
      <objIsOther nbr="1"> The object {0} is not a file, aborting writing process. </objIsOther>
      <processing nbr="1"> Processing file {0}. </processing>
      <nooutput nbr="0"> No output will be produced. </nooutput>
      <validationError nbr="1"> An error occured while trying to check file {0}.\nOutput of xmllint follows: </validationError>
      <undefAccess nbr="2"> {0}: don&apos;t know what to do with access &apos;{1}&apos;. </undefAccess>
      <templateOutput nbr="2"> The {0} {1} is a template, implementation file won&apos;t be generated. </templateOutput>
      <processingInclude nbr="3"> A {0} include statement &quot;{1}&quot; added to {2}. </processingInclude>
      <credits nbr="2"> // Created with {0} {1}. </credits>
      <unknownObjectType nbr="1"> Object type '{0}' is unknown. </unknownObjectType>
    </prgmMessages>
  </translation>

  <translation language="fr">
    <langName> French </langName>
    <nativeName> Français </nativeName>
    <!-- French translation / Traduction française -->
    <comments>
      <stdGetter nbr="1"> /** Accesseur pour {0}.\n  *\n  * Permet d&apos;accéder à {0}.\n  *\n  * @return une référence constante sur {0}.\n  */ </stdGetter>
      <stdSetter nbr="2"> /** Mutateur pour {0}.\n  *\n  *  Permet de changer la valeur de {0}.\n  *\n  * @param {1} nouvelle valeur de {0}.\n  */ </stdSetter>
      <ptrGetter nbr="1"> /** Accesseur pour {0}.\n  *\n  *  Permet de récupérer un pointeur sur {0}.\n  *\n  * @return l'addresse de {0}.\n  */ </ptrGetter>
      <ptrSetter nbr="2"> /** Mutateur pour {0}.\n  *\n  *  Permet de changer la valeur de {0}.\n  *\n  * @param[in] {1} pointeur sur la nouvelle valeur de {0}.\n  */ </ptrSetter>
      <refGetter nbr="1"> /** Accesseur pour {0}.\n  *\n  *  Permet d'&apos;accéder à {0}.\n  *\n  * @return une référence sur {0}.\n */ </refGetter>
    </comments>
    <strings>
      <constructor> constructeur </constructor>
      <destructor> destructeur </destructor>
      <getter> accesseur </getter>
      <setter> mutateur </setter>
      <refGetter> accesseur par référence </refGetter>
      <method> méthode </method>
      <member> membre </member>
      <copyConstructor> constructeur de copie </copyConstructor>
      <affectationOperator> opérateur d'affectation </affectationOperator>
      <comparisonOperator> opérateur de comparaison </comparisonOperator>
      <class> classe </class>
      <struct> structure </struct>
      <header> en-tête </header>
      <implementation> fichier d&apos;implémentation </implementation>
      <local> local </local>
      <system> système </system>
    </strings>
    <prgmMessages>
      <rootElementError nbr="1"> Vérifier votre fichier d'entrée &apos;{0}&apos; n'est pas l&apos;élément racine. </rootElementError>
      <ioError nbr="2"> Erreur E/S ({0}) : {1}.\n </ioError>
      <objectFound nbr="1"> Une description d'un objet &apos;{0}&apos; a été trouvée. </objectFound>
      <moveInfo nbr="1"> La copie de {0} sera sauvée dans {0}.BAK. </moveInfo>
      <addItem nbr="2"> Ajout d'un(e) {1} &apos;{0}&apos;. </addItem>
      <genMethod nbr="3"> Ajout auto d'un(e) {1} &apos;{0}&apos; pour {2}. </genMethod>
      <alreadyPresent nbr="2"> La classe {1} contient déjà un(e) {0}. </alreadyPresent>
      <objExist nbr="1"> Un objet {0} existe. </objExist>
      <objIsFile nbr="1"> L&apos;objet {0} est un fichier. </objIsFile>
      <objIsOther nbr="1"> L&apos;objet {0} n&apos;est pas un fichier, arrêt de l&apos;écriture. </objIsOther>
      <processing nbr="1"> Traitement du fichier {0}. </processing>
      <nooutput nbr="0"> Aucun fichier ne sera généré. </nooutput>
      <validationError nbr="1"> Une erreur s'est produite lors de la vérification du fichier {0}.\nVoir la sortie de xmllint ci-dessous : </validationError>
      <undefAccess nbr="2"> {0} : ne sait pas quoi faire du mode d'accès &apos;{1}&apos;. </undefAccess>
      <templateOutput nbr="2"> La {1} {0} est un template, le fichier d'implémentation ne sera pas généré. </templateOutput>
      <processingInclude nbr="3"> Ajout d'une directive include {0} &quot;{1}"&quot; pour {2}. </processingInclude>
      <credits nbr="2"> // Créé avec {0} {1}. </credits>
      <unknownObjectType nbr="1"> Le type d&apos;objet '{0}' est inconnu. </unknownObjectType>
    </prgmMessages>
  </translation>

</translations>

As can be seen on the previous snippet, many {0}, {1} are present in the file. They are processed by the python class providing the output (either in a file or in the terminal), and the {i} are replaced using the string.format() function (link to documentation).

Back on top

Meaning of {i}

In order to create a valid translation, the meaning of each occurrence of {i} should be known.

• For the comments section, every {0} will be replaced by the name of the class member. This means that for a class MyClass having a member MyMember, every {0} will be replaced by MyMember, whilst existing {1} will be replaced by myMember (i.e. the member name with the first letter lower-cased). Note that the various children of the comments element node have a mandatory attribute, nbr which is the number of strings that will be replaced.
• For the strings element node children, nothing special has to be said. These are just usual strings, which can be used either in the created files or in the terminal output.

• In the prgmMessages section, the replacement string is different for each children:

  • rootElementError: {0} will be replaced by the expected root element name.
  • moveInfo: both occurrences of {0} are replaced by the name of the copied file.
  • genMethod: the {0} is replaced by the access type (i.e. public, protected or private), {1} by the method type (copy constructor, std getter, ...) and {2} by the member name. The same string is used when automatic methods other than get/set are added, then the {2} is replaced by the class name.
  • alreadyPresent: {0} is replaced by the method type and {1} by the class name.
  • objExist, objIsFile, objIsOther and processing: {0} is replaced by the name of the file that should be created.
  • validationError: {0} is replaced by the name of the XML file from which the class description should be loaded.
  • ioError: {0} is replaced by the error number, and {1} by the error string. These fields are provided by catching the error when a file cannot be opened for writing with the command

  try :
  File = open( fileName, 'w' )
  except IOError, ( errno, strerror ) :
  #...

Back on top

Adding a translation

If you want to add a translation, you have to add a translation node to the translations root element. A simple way to do it is to copy the English version and translate each child one by one. As long as your language can be written using UTF-8 encoding, there is no problem. The value of the language attribute is the ISO-639-1 language code. This last requirement is not strictly speaking mandatory, but in case you want to commit your changes, it will help the package maintainer. The two fields langName and nativeName represent the name of the language in English and in the concerned language respectively (i.e. for French, langName=French whilst nativeName=Français), this helps the user to know which one is their favourite language and the maintainer to know which languages are present.

Note that you may need to change the order of appearance of {0} and {1} ({2}, ...) for the new sentence to make sense. For instance, the French translation of

<genMethod nbr="3"> Auto adding a &apos;{0}&apos; {1} for {2}. </genMethod>

is

<genMethod nbr="3"> Ajout auto d'un(e) {1} &apos;{0}&apos; pour {2}. </genMethod>

Back on top