PR#9: A new page proposal - Tanslation projects in Weblate (hosting.adoc). Information for projects (owners) to use Weblate. - fedora-l10n/docs

		`@@ -1,3 +1,5 @@`
		`# docs`

		`- Localization group documentations`
		`\ No newline at end of file`
		`+ Localization group documentations`
		`+`
		`+ Documentation is made using [asciidoc](http://asciidoc.org) format.`
		`\ No newline at end of file`

modules/ROOT/nav.adoc

file modified

		`@@ -1,2 +1,4 @@`
		`* xref:join.adoc[Join Localization community]`
		`* xref:weblate.adoc[How to use Weblate]`
		`+ * xref:doc_l10n.adoc[Documentation Translation Workflow]`
		`+ * xref:hosting.adoc[Translation projects in Weblate]`

modules/ROOT/pages/doc_l10n.adoc

file added

+119

		`@@ -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 _<component_name>-<module_name>_, or just _<component_name>_ 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: _<component_name>-<module_name>_ or _<component_name>_ if _ROOT_ module. +`
		`+ - Description: translation of _<documentation_repository_url>_.`
		`+ - 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`

modules/ROOT/pages/hosting.adoc

file added

+95

		`@@ -0,0 +1,95 @@`
		`+ include::{partialsdir}/attributes.adoc[]`
		`+`
		`+ // hosting.adoc? - is there a better file name for this page, will be part of URL?`
		`+`
		`+ = Translation projects in Weblate`
		`+`
		`+ == Fedora's online translation platform`
		`+`
		`+ The Fedora Project runs a web-based online translation platform powered by https://weblate.org[Weblate]. This Fedora {WEBLATE}[Weblate instance] is available at {WEBLATE} and is used by Fedora translators for translating Fedora subprojects, be it a software development project, a website or the documentation.`
		`+`
		`+ === Considerations to upstream projects`
		`+`
		`+ In line with the Fedora Project's vision of a world where everyone benefits from free and open source software built by inclusive, welcoming, and open-minded communities any free and open source software project is welcome to use this platform.`
		`+`
		`+ Few examples of motivation behind this approach:`
		`+`
		`+ * We support any project sharing the same xref:project:ROOT:index.adoc[values] as the Fedora Project`
		`+ * To improve upstream i18n support`
		`+ * A potential source of growth in the Fedora Community itself`
		`+`
		`+ As the Fedora l10n Team, we believe we are enough _"mature and consistent with our values to be ready to welcome projects which have different technical choices from those the Fedora implements"_ (Jean-Baptiste Holcroft, a member of the Fedora L10N Team, 2020).`
		`+`
		`+ ////`
		`+ Here could go what a project can expect from us`
		`+ and on the other hand what they should be ready for`
		`+`
		`+ What makes us different with https://hosted.weblate.org?`
		`+`
		`+ We are a structured community sharing open-source values with`
		`+ experienced translators`
		`+ * Structured community: we have language teams https://fedoraproject.org/wiki/L10N_Teams and a global {TRANSML}[translator`
		`+ mailing list]`
		`+ * we have open-source values: https://docs.fedoraproject.org/en-US/project/#_freedom`
		`+`
		`+ Rule examples:`
		`+ * announce translation readiness to translators one week before release?`
		`+ * include translators in credits`
		`+ * allow translation of website and man-pages`
		`+ ////`
		`+`
		`+ == Request a new translation project on Weblate`
		`+`
		`+ In spite of the effort to be open and inclusive as much as possible, some associated concerns has led us to enforce it is not possible to create a translation project in the platform for everyone:`
		`+`
		`+ * A translation of an (open source) project has to be ensured`
		`+`
		`+ _Not what an individual has decided to translate._`
		`+`
		`+ * A project does not have to learn the weblate internals`
		`+ * Configuring Weblate is not so obvious`
		`+`
		`+ _Preferable is to do the first configuration for a project by us to reduce e.g. the migration costs._`
		`+`
		`+`
		`+ In order to request an establishment of a new translation project in {weblate}[Weblate], open a link:https://pagure.io/fedora-l10n/tickets[ticket].`
		`+`
		`+ // Do we want to prepare a 'request template'?`
		`+ .Project request template`
		`+ ====`
		`+ Project: // debbuild`
		`+`
		`+ Website: //https://github.com/debbuild/debbuild`
		`+`
		`+ Repository: //https://github.com/debbuild/debbuild`
		`+`
		`+ Name of the development branch:`
		`+`
		`+ Filemask: //po/*`
		`+`
		`+ Username: //ngompa`
		`+`
		`+ Optional:`
		`+`
		`+ Any announcement/warning you would like to display to the translators? (it will be displayed in Weblate)`
		`+`
		`+ A need to activate any specific checks? (this is a setting per component)`
		`+`
		`+ A need to automatically detect new translation files? (typical usecase: website translation with one translation file per page)`
		`+ ====`
		`+`
		`+ // These features has already been implemented in Weblate`
		`+ ////`
		`+ two features in Weblate to respect Fedora values:`
		`+ - set a lincence in every component`
		`+ - licence change should trigger a notification`
		`+ ////`
		`+ // Should be a licence a part of the template?`
		`+ // [optional] what is the license of translation? (please use a code from https://spdx.org/licenses/)`
		`+ // Should we emphasize that a licence change will be notified`
		`+`
		`+ The specified username(s) will be set in the initial configuration of the project in Weblate as the project's administrator(s).`
		`+`
		`+ Once the initial configuration is made the project contact(s) will be notified.`
		`+`
		`+ Request made by upstream projects will be reviewed on an individual basis upon submission of the ticket. Priority will be given to projects that create software packaged for Fedora. // or 'by Fedora'??`

modules/ROOT/pages/index.adoc

file modified

+12 -2

		`@@ -4,9 +4,11 @@`

		`image::translation.png[]`

		`- The goal of the Fedora Localization Team (l10n) is to bring everything around Fedora (the Software, Documentation, Websites, and culture) closer to local communities (countries, languages and in general cultural groups).`
		`+ The goal of the Fedora Localization Team (L10N) is to bring everything around Fedora (software, documentation, websites, and the culture) closer to local communities (countries, languages and in general cultural groups).`

		`Usually, this involves doing translations via PO files but is certainly not limited to that.`
		`+ Beside the focus on translating, a part of the Fedora L10N Team's responsibilites is to develop and maintain neccessary tools and related processes which facilitate flows of a localization content between projects and translators;`
		`+ thus, projects can concentrate on development, while translators purely on translation.`

		`[[find-l10n]]`
		`== Where to find Fedora l10n team`
		`@@ -15,4 +17,12 @@`
		`Matrix room:: {CHAT}[#l10n:fedoraproject.org] in https://chat.fedoraproject.org[Fedora Chat]`
		`IRC channel:: https://web.libera.chat/?channels=#fedora-l10n[#fedora-l10n] on https://libera.chat/[Libera IRC]`

		`- Issues can be filed in https://pagure.io/fedora-l10n/tickets[our ticketing repo], as well.`
		`+ Questions or problems associated with localization can be filed as an issue in https://pagure.io/fedora-l10n/tickets[our tracking repo], as well.`
		`+`
		`+ == Next reading`
		`+`
		`+ Translators, particularly those new-coming, can continue with reading information about a xref:join.adoc[membership] of this team and a short guide to our online xref:weblate.adoc[translation platform].`
		`+`
		`+ Some insights into our translation tooling used in the Fedora Project, for example for translating the https://docs.fedoraproject.org[Fedora documentation] can be found xref:doc_l10n.adoc[here].`
		`+`
		`+ Projects considering the use of our translation platform for their translations might find relevant information xref:hosting.adoc[here].`

site.yml

file modified

+1 -1

		`@@ -7,7 +7,7 @@`
		`branches: HEAD`
		`ui:`
		`bundle:`
		`- url: https://releases.pagure.org/fedora-docs/fedora-docs-ui/ui-bundle-1.04.zip`
		`+ url: https://gitlab.com/fedora/docs/docs-website/ui-bundle/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable`
		`snapshot: true`
		`default_layout: with_menu`
		`output:`

peartown commented a year ago

This new page contains information we would like to communicate to (upstream) project owners, regarding our Weblate translation platform. Basically, the information should make clear what projects that would like to use Weblate should expect from our side and what they should be ready for on their side in order to use Weblate for their localization.

This is a firs shot in collecting such information.

I'd like to have it in the stg first, ask the L10N team for comments and reviews on the subject before it, hopefully, will go live.

peartown commented a year ago

My local build worked, so hopefully all asciidoc is right.

darknao commented a year ago

looks good!

Pull-Request has been merged by darknao

a year ago

jibecfed commented a year ago

this is good, thank you :)

to help you on the weblate page, you have content there: https://pagure.io/fedora-docs/translations-scripts/blob/master/f/README.md?text=True#_118

peartown commented a year ago

Before I'll continue in further changes, I'd like to clarify to myself few things.

...you have content there...

Does it mean we don't enforce the initial creation of a translation project in Weblate by us any more?

Now, we have a 'technical' design information in doc-l10n.adoc page about the existing build pipeline of Fedora Documentation. I thing we could possibly place to this page also similar info about a pipeline associated with Fedora Websites in near future. So, basically, I'd like to devote this page to the technical design descriptions behind localization.

While a sort of 'policy' rationale(s) and procedures, or maybe how-tos involved in translation in this new page (hosting.adoc). (Maybe another separate page with how-tos?) Therefore, I'd like to move the weblate project creation from doc-l10n to hosting.adoc.

If you have any comment, it would again really help.