There are various ways of providing documentation in different languages.
The entire Sphinx project is copied with all associated *.rst files, which are translated completely into another language. A disadvantage of this option is that content coherence is lost in different languages. When changes are made in one language, it is difficult to properly align the other languages.
Sphinx uses MessageCatalogBuilder for supporting the creation of file collections (POT Output Format). These contain all parts of the documentation to be translated by aligning the source language segments with the target language. With the help of appropriate tools, a kind of translation memory is generated which forms the basis of translating other libraries.
The Source directory should be the starting point for translating documentation into another language. The changes to the library by the developer and the updates in the framework document by the technical writer have been summarized in this document with the libdoc merge script.
Calling the libdoc transform pot <struct> script provides a complete language catalog for the Sphinx project. In addition, a language-specific catalog is created in the <struct>/_locale directory for each required language.
This command extracts translatable messages from the document to *.pot files and sets up the Source\_locale directory (message catalog) by generating *.po files.
The result is a set of directories (locale\<lang>\LC_MESSAGES) that contain *.po files:
The *.po files are then processed by the translator. A possible tool for smaller projects is Poedit.
The individual text segments can then be translated from the *.po files. A translation memory is created in the process and, as time goes on, the processing of recurring texts (data types, parameters, and so on) becomes more and more efficient. When the translation process is complete, the *.po file is converted into a *.mo file, which Sphinx can use for generating the library documentation into another language.
Calling the libdoc transform html <struct> de script generates a Sphinx project in HTML and translated in German.
The following extract from the index.rst file is a sample of the English language documentation:
The following extract is the German translation of the same file:
The compiled library format is the choice for the deployment of libraries. When saving a library as *.compiled-library, the current documentation of this library is generated automatically and integrated in the *.compiled-library as a *.lmd file.
In the compiled-library format, various internal information is bundled in a zip archive. As of CODESYS V3.5 SP6, the capability is provided for attaching more than one language to a library in the compiled-library format. This can be done manually or by means of a script for handling the *.compiled-library. This is based on the idea that a *.compiled-library is actually a zip archive. Therefore, the *.compiled-library can be handled with conventional tools for zip archives. The respective language variant of the documentation is generated as a *.lmd file, appended with the extension *.auxiliary, and added to the archive.
Example:
The “__lmd__.auxiliary” file shows the language variant that is selected when the required translation is not available. When the library is installed, the respective *.lmd file is extracted and installed in language-specific memory. When CODESYS is started in a particular language (setting for online help), that language is provided when viewing the library in that language in the library manager.
Requirements:
To be able to sign libraries, the following requirements are necessary:
CODESYS V3.5 SP16 or newer
An X509 certificate that can be used for code signing
Access to an RFC-3161 Timestamping Server
Setting Library Compatibility to CODESYS V3.5 SP16 or newer
Procedure:
Configure Security Manager
Select certificate
Select “Enforce signing of compiled libraries”
Select “Enforce timestamping of signed compiled libraries”
Enter the URL of the Timestamping-Server
Setup Library Compatibility
Save library as “compiled library”
If a compiled library is to contain localised documentation, the notes below must be observed.
Place the files created for the new languages __lmd__<language>.aux in a directory <library name>.lmd parallel to the library project <library name>.compiled-library-v3.
If the files are correct, then they are included in the compiled library file when saving the library project by means of the “Save Project as Compiled Library” command.