Documentation in Different Languages
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.
The following is an example of how to effectively call the CODESYS LibDoc Scripting Collection for generating the localization files:
cd <config-dir>
sphinx-build -b gettext -c . -d Build\Source\pottrees -t libdoc_html Source Build\Source\pot
sphinx-intl update -p Build\Source\pot -d Source\locale -l de -l es -l fr
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 is an example of how to effectively call the CODESYS LibDoc Scripting Collection for translating documents into other languages:
cd <config-dir>
sphinx-intl build -d Source\locale
sphinx-build -b html -c . -d Build\Source\doctrees -t libdoc_html -D language=en Source Build\Source\html\en
sphinx-build -b html -c . -d Build\Source\doctrees -t libdoc_html -D language=de Source Build\Source\html\de
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:
Deployment of Translated Documents
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 SP6 (CDS-40294), 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.
