From c3eeeee8abdbe2da514c574ef34a46973b08cbc4 Mon Sep 17 00:00:00 2001 From: darknao Date: Oct 09 2022 21:10:03 +0000 Subject: add docs l10n workflow --- diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index e5d25fc..c7dec67 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1,2 +1,3 @@ * xref:join.adoc[Join Localization community] * xref:weblate.adoc[How to use Weblate] +* xref:doc_l10n.adoc[Documentation Translation Workflow] diff --git a/modules/ROOT/pages/doc_l10n.adoc b/modules/ROOT/pages/doc_l10n.adoc new file mode 100644 index 0000000..6810d6a --- /dev/null +++ b/modules/ROOT/pages/doc_l10n.adoc @@ -0,0 +1,119 @@ +include::{partialsdir}/attributes.adoc[] +:experimental: + += Documentation Translation Workflow + +This document outlines how the localization workflow works for the Fedora Documentation Website. + +== Localization pipeline +=== Description + +The localization process of the documentation works in three steps: + +- Extract strings from the English sources and produce POT files. +- Translators translate these POT files and produce PO files. +- We consume these PO files to construct translated sources, and finally to build the translated website. + +Step 1 and 3 is handled by the <<_core_scripts, localization pipeline scripts>>. +Step 2 take place in Weblate. + +=== Core scripts + +Localization pipeline scripts are hosted on Pagure in the link:https://pagure.io/fedora-docs/translations-scripts[translation-scripts] repository. +This set of scripts run everyday at 21h UTC on our Openshift cluster. + +The main script _build.py_ extracts all strings from adoc files in all components, create POT files, then use translated PO files to generate translated adoc files that will be used to build the final documentation website. + +Translated adoc files are stored in the link:https://pagure.io/fedora-docs/translated-sources/[translated sources] repository. + +== Translation repositories +=== Design rationale +Documentation content is divided into components (spaces with their own navigation menu). + +Each component can have multiple versions, and also multiple modules. + +The primary function of modules is the ability to store different parts of components in different git repositories. But they can be also stored in a single repository. + +One repository can even hold multiple components. And moving components or modules between repositories have no influence on the output. + +This is also valid for translations, moving components around should not change the content for translators. + +That's why we need to organize the PO and POT wiles not according to repositories, but according to the components, modules, and versions. + +.Standard Antora repository structure +[listing#ex-standard-dirs-root] +---- +📒 repository <.> + 📄 antora.yml <.> + 📂 modules <.> + 📂 ROOT <.> + 📁 attachments <.> + 📁 examples <.> + 📁 images <.> + 📁 pages <.> + 📁 partials <.> + 📄 nav.adoc <.> + 📂 named-module <.> + 📁 pages + 📄 nav.adoc + 📁 packages <.> +---- +<.> The repository name has no influence on the documentation & translation output. +By default, Antora assumes the documentation content source is at the root of a repository unless the `start_path` or `start_paths` is defined in the link:https://gitlab.com/fedora/docs/docs-website/docs-fp-o/-/blob/prod/site.yml[Fedora Doc's playbook]. +<.> A component version descriptor file, named [.path]_antora.yml_, is required at each content source root. +<.> Required directory named [.path]_modules_. +A [.path]_modules_ directory must contain, at a minimum, either a _ROOT_ module directory or a named module directory. +<.> Optional _ROOT_ module directory. +A module directory must contain at least one family directory. +<.> Optional _attachments_ family directory. +<.> Optional _examples_ family directory. +<.> Optional _images_ family directory. +<.> Optional _pages_ family directory. +<.> Optional _partials_ family directory. +<.> Optional navigation file named [.path]_nav.adoc_. +<.> Optional named module directory. +<.> Antora won't process the files in this directory because it's located outside the [.path]_modules_ directory. + +=== Structure description + +Translations are stored in dedicated repositories in the link:https://pagure.io/projects/fedora-docs-l10n/%2A[fedora-docs-l10n] Pagure namespace. + +Each repository uses the following structure: + +.Standard translation repository structure +[listing#ex-translation-dirs-root] +---- +📒 component-module <.> + 📂 pot <.> + 📁 version <.> + 📄 page.pot + 📁 po <.> + 📂 language-code <.> + 📁 version + 📄 page.po +---- +<.> The repository name is _-_, or just __ for the _ROOT_ module. +<.> _pot_ directory contain the source translation files used to start new translations. +<.> The version directory is named from the _version_ key in the component _antora.yml_. If not defined, it will be named _master_. +<.> _po_ directory contain translations that come directly from Weblate. +<.> The language-code directory is named using codes as defined by ISO 639-1, ISO 639-2 or ISO 639-3 when required. (ie.: _de_, _pt_BR_ or _zh_Hans_). + +CAUTION: Renaming components or modules results in the loss of translations for that component and/or module. + +IMPORTANT: While the content of those repositories is automatically generated by the localization pipeline and Weblate, each repository must first be created manually. + +=== Repository creation + +. Log in https://pagure.io and, in the top menu, click on: menu:Create[New project]. + - Project name: *_-_* or *__* if _ROOT_ module. + + - Description: *translation of __*. + - Project Namespace: *fedora-docs-l10n*. + - Select "*Create README*". +. In the new repository, go in menu:Settings[Project Options]: + + In the Web-hooks field, add: https://translate.fedoraproject.org/hooks/pagure/, then click btn:[Update] +. In menu:Settings[Users & Groups]: + + Click btn:[add group], select the *fedora-docs-l10n* group, choose *commit* in the second list, then click btn:[Add]. +. In menu:Settings[Hooks > Fedmsg]: + + Check "*Active*", then click btn:[Update]. + +== Weblate project +Documentation related projects are prefixed with _fedora-docs-l10n_. + +=== Project creation +TBD