Documentation workbench
This function is used to display the progress of the translation work. The LANTRA and LANREF setups are used to assign in advance the translation language and the reference language.
It is also used to extract documentations or field helps in order to translate them using translation software able to process XML files. The extraction is performed in a default xml directory, created, if it does not exist, in the documentation directory defined by the DIRDOC setup.
Prerequisite
Refer to documentation Implementation
Screen management
This function is used to display the progress of a translation in a given translation language with respect to a reference language.
It is also used to extract in XML format the documentations and field helps to be translated.
The function contains 3 tabs:
- the first tab presents the translation progress, it can be loaded using the button
- the second tab is used to search those documentations whose translation is not updated, by means of the button. The search can be limited to a specific type, code or code range. It is then possible to process the documentations one by one by right clik, or to process several documentations at the same time.
- the third tab is used to search those field helps whose translation is not updated, by entering a set of criteria and using the button. The search can be limited to a specific code or code range. It is then possible to process the field helps one by one by right clik, or to process several field helps at the same time.
Header
Presentation
Used to enter the translation target language and the reference language.
Close
Fields
The following fields are present on this tab :
| Defines the translation language. |
|
|
| Defines the language from which the validation of the translation is verified. In the case of the extraction of an XML file for translation, the extracted text will be that in the given reference language. |
Close
Tab Progress
Presentation
Displays what has been translated and what remains to be translated for the documentations as well as the field helps in a general and detailed manner by documentation type.
It should be underlined that only those documentations that have been fully validated in the reference language may have to be translated. The validity date of a translated documentation must be equal to the date of the documentation in the reference language, otherwise it will need to be translated.
For the field helps, the creation date of the field help must be equal to the date of the last modification in the reference language, otherwise the field help will need to be translated.
The extract/import mechanism manages the transfer from the reference language to the translation langauge for the previously mentioned dates.
Close
Fields
The following fields are present on this tab :
Grid Distribution
| Displays the number of translated field helps and documentation plus those that remain to be translated. |
|
|
|
|
| Displays the number of translated field helps and documentation plus those that remain to be translated. |
|
|
|
|
Summary
| Presents the number of completely validated documentations and the total number of documentations for the reference language and the translation language. |
|
|
|
|
|
|
| Presents the total number of field helps for the reference language and the translation language. |
|
|
|
|
|
|
Grid Detail by type
| The grid displays by documentation type :
|
|
|
|
|
|
|
|
|
|
|
Close
Action icon
Non-validated documentations
Displays the list of the documentations that are not validated.
Translated documentations
Close
Tab Documentation
Presentation
After searching given documentations to be translated by means of the criteria, it is possible to process:
- a single documentation by right click,
- all or some documentations by selecting the requested lines before triggering the action using the button at the bottom of the screen .
For further explanations on the Process action, refer to the Annex entitled 'Translation process of a documentation'.
Close
Fields
The following fields are present on this tab :
Criteria
| Used to indicate whether the search criteria is a particular documentation type or all. |
|
|
| Used to indicate one module or all as a search criterion. |
|
|
|
|
|
|
|
|
|
| Used to indicate the search criterion for a code range by using the start and end range or all codes. |
|
|
|
|
Grid Search
| Used to define if the line must be processed when the process is launched by the button at the bottom of the screen. |
| This field defines the type for the documentation. Each type is associated with a type of documented element (functional documentation, describing a record in the dictionary or the parameterization values, describing the structure of the dictionary, miscellaneous). When a documentation type corresponds to an object code, a Documentation entry is automatically created in the menu bars for the object in question. It is then possible to document the records entered in the object in question. It is for this reason the functional help is codes AFC (code for the Functions object), the help on the general parameters is coded ADP (code for the Parameters object)... The rules for naming the documentation are defined in a documentation appendix. |
| This field defines the code for the documentation. It corresponds in principal to the code for the record (function, parameter...) that is being documented. The rules for naming the documentation are defined in a documentation appendix. |
| This field is the title for the paragraph. If it is empty, a default title is assigned as a function of the paragraph type (whether in creation or in modification mode). In the case of miscellaneous paragraphs that do not appear in the materials tables (of the type MIN), the fact of entering the title with the character " ! " deactivates the insertion of a title. |
| Indicate the validation date or the last modification found in the object for the selected reference language. |
| Indicate the validation date or the last modification found in the object for the selected translation language. |
| Indicate if the object already exist for the selected translation language. |
|
|
|
|
|
|
Close
Action icon
Standard Rerouting Action
When faced with an entry grid with multiple choices and a Yes/No answer on each line, this function makes it possible to answer Yes to all the lines starting from the current line.
Standard Rerouting Action
When faced with an entry grid with multiple choices and a Yes/No answer on each line, this function makes it possible to answer No to all the lines starting from the current line.
Process documentation
Starts the process for the current line of the table. This produces the XML file that will be used to perform the translation.
A directory were the XML files will be extracted will need to be specified. This directory corresponds by default to the xml sub-directory of the directory selected to store the documentation extracted in HTML format. The files of the documentation chapters are directly extracted to the specified directory and the files linked to a documentation are located in the FILE sub-directory of the xml extraction directory.
For further explanations on the Process action, refer to the Annex entitled 'Translation process of a documentation'.
Close
Tab Field helps
Presentation
After searching given field helps to be translated by means of the criteria, it is possible to process:
- a single field help by right click,
- all or some field helps by selecting the requested lines before triggering the action using the button at the bottom of the screen .
For further explanations on the Process action, refer to the Annex entitled 'Translation process of a documentation'.
Close
Fields
The following fields are present on this tab :
Criteria
| Used to indicate one module or all as a search criterion. |
|
|
|
|
|
|
|
|
|
| Used to indicate the search criterion for a code range by using the start and end range or all codes. |
|
|
|
|
Grid Search
| Used to define if the line must be processed when the process is launched by the button at the bottom of the screen. |
| Indicate the keyword that is the reference for the field help. |
| Indicate the validation date or the last modification found in the object for the selected reference language. |
| Indicate the validation date or the last modification found in the object for the selected translation language. |
| Indicate if the object already exist for the selected translation language. |
|
|
|
|
Close
Action icon
Standard Rerouting Action
When faced with an entry grid with multiple choices and a Yes/No answer on each line, this function makes it possible to answer Yes to all the lines starting from the current line.
Standard Rerouting Action
When faced with an entry grid with multiple choices and a Yes/No answer on each line, this function makes it possible to answer No to all the lines starting from the current line.
Process field help
Starts the process for the current line of the table. This produces the XML file that will be used to perform the translation.
A directory were the XML files will be extracted will need to be specified. This directory corresponds by default to the xml sub-directory of the directory selected to store the documentation extracted in HTML format.The field documentation files are located in the FLD sub-directory of the xml extraction directory.
For further explanations on the Process action, refer to the Annex entitled 'Translation process of a documentation'.
Close
Specific Buttons
This button, also accessible using the short cutIt is used to refresh the display of the first tab. |
Displays in a new table the documentations that have been translated and those that remain to be translated by module and by documentation type. |
This button is used to load the grid in the Documentation tab. It starts the search of those documentations that need translation, based on the entered criteria. |
This button is used to load the grid in the Field Help tab. It starts the search of those field helps that need translation, based on the entered criteria. |
Appendix: Documentation translation process
Preliminary notes
To date, only the function documentation provides a Validated checkbox and a validation date. By principle, a documentation must only be Validated if it is considered to be completed, and the field helps that are integrated in said documentation are also considered to be completed. Only the fully validated documentations are available for translation.
Within an ongoing translation flow, modifications can occur at a given moment, and some re-translation can prove necessary. In that case, the documentation needs to be revalidated at a new date and it will be submitted again for translation.
Whenever a functional documentation integrates field help documentations, the field documentations integrated into this functional documentation need to be translated at the same time.
Process action
Before being able to extract a documentation or a field help for translation purposes, the documentation structure needs to exist in the translation language and match the structure of the reference documentation.
The Process action is used to carry out all the necessary phases up to the extraction process.
- Generation: this operation will create the paragraphs of the documentation for the translation language, by reusing the tab titles and the function title and by leaving the explanatory (to be translated) paragraphs empty. It is important that all the texts of the function are translated beforehand (it concerns ATEXTE and APLSTD), otherwise, all the already translated terminology will not be retrieved.
- Copy: The First, some text has been entered in the paragraphs (this precisely belongs to the elements to be translated). The structure of the paragraphs may also have been modified. To transfer these modifications, a documentation copy function needs to be launched. It is important to note that the texts of the paragraphs are not copied. Only the attachments, additonal paragraphs (without the text), the INC paragraph modifications, the titles of the new paragraphs (MIS) and their allocation of the FAL activity code are transferred.
The field helps are created and their characteristics are copied in this phase.
- Extraction: Each documentation and field help is extracted into an XML file that will be subsequently translated using a software able to translate XML files. A directory were the XML files will be extracted will need to be specified. This directory corresponds by default to the xml sub-directory of the directory selected to store the documentation extracted in HTML format.The files of the documentation chapters are directly extracted to the specified directory and the files linked to a documentation are located in the FILE sub-directory of the xml extraction directory. The field documentation files are located in the FLD sub-directory of the xml extraction directory.
Integration of the translated files
After having translated the files via an external tool, the documentation integration function will make it possible to import the files and allocate the flags and validity dates used to check the translation validity.
Important note
Any documentation translated via this process must not be revalidated manually with a different date.
In other words, even if the documentation is reworked, it is prohibited to give it a validation date other than the date allocated by the export/import process.
If a paragraph is added (for instance, a MIS paragraph specific to the translation language) to the translated documentation, this translated documentation needs to be revalidated with the date allocated by the translation process.
If another validity date was allocated, the translation validity control with respect to the reference language would always flag the translation as invalid and would always submit the documentation for transaltion.
Appendix: format of the files created
The format of the XML file of the function or object documentation, as it can be found in the xml directory, is as follows:
- a standardized xml header,
- a DOC tag with the TYPE and NAME attributes (that define the type and code of the documentation),
- inside the DOC tag, for each paragraph, a PAR tag with the LAN, LEV, SUBLEV, PAR, MSK, STY, VLDDAT, VLDFLG, ACT and MOD attributes (that define the language, level, sub-level, paragraph code, screen, style, validity date, validity flag, activity code and module),
- inside the PAR tag, a TIT tag is given for the title of the paragraph (if any),
- inside the PAR tag, an HTML tag contains the text of the paragraph in XHTML format.
The field documentation files are located in the FLD sub-directory of the xml extraction directory. The format is as follows:
- a standardized xml header,
- an FLD tag with the NAME, LAN, MOD, GEN, LNKHLP, LNKORD, CREDAT, UPDDAT attributes (that define the name, language, module, generic attribute of the documentation, linked help, link, creation date and modification date),
- Inside the FLD tag, an HTML tag contains the text of the paragraph in XHTML format.
The files linked to a documentation are located in the FILE sub-directory of the xml extraction directory. The name of the file is constructed in the following fashion:
COD_LAN_TYP_LEV_SUBLEV_LIG_NOMFICHIER_LGCLE.EXT, where:
- COD_LAN_TYP_LEV_SUBLEV_LIG is generated from the the key of the linked file in the ADOCBLB table (this aims at ensuring the name unicity).
- LGCLE contains the length of the previous key in order to be able to correctly extract the documentation code.
- NOMFICHIER and EXT correspond to the name of the file (name and extension) if it is mentioned in the ADOCBLB table, or to a name composed of "IMG" characters, followed by the line number on 3 characters (prefixed with zeros, if necessary), then followed by the ".jpg" extension.