Putting things together

HINT: This page is under construction (tokideveloper).

Website elements concerning translation

This section describes the elements on the website concerning translation.

The elements (on documentation pages) are:

• There is an always-visible bar at the top of the page having links to translations named after the languages using the language codes from ISO 639-1.
  • Available translations (at least X% translated) are written in blue.
  • Unavailable translations (fewer than X% translated) are written in red.
• There is a banner just over the page content stating that this is an unverified translation since the Qubes OS developers can't read it.
• On the sidebar, there is a button labeled "Translate this Page" leading to the Transifex project where the Qubes OS website becomes translated.
• (Attachments shall not be translated for now.)
• Untranslated sentences and translated but not updated sentences are highlighted. The type of that highlighting and its meaning are described in a banner, too.

Process elements concerning translation

This section describes the steps beginning at accepting a pull request P on qubes-os.github.io till accepting the pull request of the translated version of P.

The steps are in general:

1. Accept a pull request (PR) on the repo qubes-os.github.io.
2. Process the updated/new files for making them appropriate for Transifex (the translation platform for the Qubes OS website).
3. Upload the processed files to Transifex.
4. Let translators and reviewers do their work on Transifex.
5. Download translated files regularily.
6. Check the downloaded files for some rules of consistency.
7. Post-process the checked files.
8. Put the checked files to the repo named like qubes-translated.
9. Let Jekyll render the HTML files automatically.
10. Proofread the rendered HTML files.

When a contributor submits a PR on qubesos.github.io and the PR has been accepted by the Qubes OS project then

1. (TODO: to be reviewed) the modified files will be automatically edited by a script (gsganden/sentence_separator) which inserts newline characters where heuristically appropriated (finished sentences). This way, each sentence will reside on its own line making the reuse of already translated sentences easier since Transifex can handle already translated lines. REMARK: The script does not take care of the syntax of Markdown pages. Maybe we should write something on our own? Also, the script cannot handle all abbreviations properly. Maybe we should add a Markdown rule that each abbreviation should end with a period followed by two spaces?
2. …
3. Consistency checks after downloading a translated file from Transifex:
   • In each paragraph, all internal and external links including their fragments remain as is.
   • The structural context (enumerations, headlines, code blocks etc.) must remain as is for all lines.
   • The underlining line of a headline should have the correct number of characters (warning).
   • …
4. Post-processing checked files:
   • Merge and adapt YAML front matters.
   • Annotate headings with HTML IDs from the original headings
   • Amend underlinings if necessary. (to be implemented)
   • …

Repository elements concerning translation

• .tx directory
• translated data files
• list of supported languages
• qubes-translated repository
• qubes-data-translated(?) respository

How to add and enable a new language

How to disable a language

How to re-enable a language