This repository gathers all files involved in translation of shell scripts and
documents provided in the Slint distribution and its website https://slint.fr

Readers not accustomed with internationalization and localization can read:
https://slint.fr/doc/internationalization_and_localization_of_shell_scripts.html 

For Slint the `po4a` application is used to process documents in asciidoc
format and the Crowdin platform https://crowdin.com/project/slint is used by
translators to download and upload the PO files and optionally translate
on-line.
The translation manager can use the `crowdin` client application to to manage
the files transfers from/to the Crowdin platform.

Content of the main directories:
* `configuration`: configuration files for `po4a` and the `crowdin` client
  application.
* `po`: POT and PO files
* `localization_toolbox`: helpers for translation of shell scripts. 
* `sources`: internationalized shell scripts, and documents in asciidoc format,
   to be translated.
* `translations`: translations of documents in `sources`,in the same formats. 

All shell scripts from which text strings are extracted and gathered in a
single POT file are stored in a sub-directory of `sources`, like slint-scripts
for slint-scripts.pot. Instead there is only one document in asciidoc format  
in `sources` of which text strings are extracted in POT file.
For each POT file there is a sub-directory under `po` gathering the POT file
and the corresponding PO files, and sub-directories under `sources` and
`translations` with the same name.

We will describe below the processes involved for providing translations to be
included in the Slint installer, Slint systems and the website https://slint.fr

Upon creation of a new source file:
1. If the source file is a shell script, its writer identify the text strings
   to be translated and marking them as such in the script itself. This step
   is not necessary if the source file is a document in asciidoc format.
2. The translation manager stores the source file in the relevant sub-directory
   of the `sources` directory.
3. The translation manager converts the source file to a POT file and stores
   it in the relevant sub-directory of the `po` directory. The conversion is
   done, depending on the format of the source file:
   . In case of a shell script running `xgettext`, directly or through the 
     script `toolbox.sh` provided in the `localisation_toolbox` directory.
   . In case of an document in asciidoc format, running `po4a` with as argument
     the relevant configuration file in the `configuration` directory.
4. The translation manager up upload the POT file to Crowdin using the
   `crowdin` client application.
5. Crowdin automatically creates the PO files.
6. The translator either translate directly in Crowdin, or download the PO
   file, translate it using a PO editor then upload the edited PO file to
   Crowdin.
7. The translation manager downloads the translations in PO format using
   `crowdin` to the relevant sub-directory of the `po` directory.
8. The translation manager converts the PO file to a translated file that will
   be stored in the relevant sub-directory of the `translations` directory. 
   The conversion is done, depending on the format of the source file:
   . In case of a shell script running `msgfmt` , directly or through the
     script `toolbox.sh` provided in the `localisation_toolbox` directory.
     In this case the translation in the MO format.
   . In case of an document in asciidoc format, running `po4a` with as argument
     the relevant configuration file in the `configuration` folder.
     In this case the translation is in the asciidoc format, that will be
     converted to html/
9. The translations in are used these ways, depending on the translation unit:
   . The translations of `slint-scripts` are included in a Slint package also
     named slint-scripts.
   . The translations of `auto`, `rc.S` and `SeTkeymap` are included in the
     Slint installer.
   . The translations of `HandBook`, `homepage` `news` and of the articles
     included in `wiki` are converted to html by the script build_website.sh
     available in https://github.com/DidierSpaier/slint-website that then
     uploads them to the https://slint.fr web site
   . The translations of `HandBook` are also converted to html by the script
     slint-docs.SlackBuild that builds the slint-doc package to install in
     the system the translated HandBook to allow reading it off line.

In case of an update of an already translated source file:
. at step 4 the updated POT file is uploaded by the translation manager,
. at step 5 Crowdin automatically updates existing PO files accordingly,
. at step 6 the translators edit them as need be, adding or editing translated
  text strings.