From 557ca121c7aad92ad2263ab8b404e289f57a088d Mon Sep 17 00:00:00 2001 From: peartown Date: Mar 25 2024 23:26:34 +0000 Subject: Modify hosting.adoc - added info about placeholders to good practice Plus added preamble of the page. --- diff --git a/modules/ROOT/pages/hosting.adoc b/modules/ROOT/pages/hosting.adoc index 166c7eb..09637bc 100644 --- a/modules/ROOT/pages/hosting.adoc +++ b/modules/ROOT/pages/hosting.adoc @@ -4,7 +4,12 @@ include::{partialsdir}/attributes.adoc[] = Translation Projects in Weblate Fedora Localization Team -2024-01-07 +2024-01-20 +:experimental: + +Information for project owners if they assess or intend to use the Fedora Project's online translation platform (based on the Weblate software project) for translating their project. +How to access the platform or request creation of a translation project, why the Fedora Localization Team believes it is worthwhile to offer it to a wider range of projects than solely those of the Fedora Project itself, and handful gathered practical advice for administering the translation project. + == Fedora's online translation platform @@ -20,6 +25,7 @@ Examples of free and open source projects which can be found on Fedora Weblate t . https://www.freedesktop.org/wiki/Software/Plymouth/[Plymouth] ==== + === Considerations to upstream projects *Any free and open source software project is welcome to use this platform.* @@ -31,6 +37,7 @@ Not only is it in line with the Fedora Project's vision of a world where everyon 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 @@ -49,6 +56,7 @@ Rule examples: * allow translation of website and man-pages //// + == Request a new translation project on Fedora 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 by everyone: @@ -89,6 +97,7 @@ The specified username(s) will be set in the initial configuration of the projec 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. + == Project configuration good practice Once the requested translation project is created for you in Weblate, you can continue with https://docs.weblate.org/en/latest/admin/projects.html[setting] its other options. @@ -96,6 +105,7 @@ There are several approaches to creating a project's components, for example. Weblate provides different means to recieve and send changes between Weblate and your repository, so it is hard task to cover all possibilies here or prepare a common guide. But what we have learned from helping to set various projects: +// webhooks Do not forget to set, if appropriate, a https://docs.weblate.org/en/latest/api.html#notification-hooks[webhook] in the project options in order to automatically receive changes from your VCS, such as ---- @@ -104,7 +114,49 @@ https://translate.fedoraproject.org/hooks/gitlab //for GitLab https://translate.fedoraproject.org/hooks/github //for GitHub ---- +// repository push URL Weblate is able to https://docs.weblate.org/en/latest/admin/continuous.html#pushing-changes-from-weblate[push translations] to your repository by setting 'Repository push URL' option of a component configuration. For GitHub there is https://github.com/weblate[Weblate user] which should be given a commit access to the repository. The same applies for GitLab. For Pagure there is https://pagure.io/user/weblatebot[weblatebot user]. + +// pleaceholders flag +Weblate provides a wide range of quality checks on strings. +A `placeholders` flag can be set to add a quality check on texts from source string that must not be missing in the translation. +If missing, a warning will pop up to the translator. +Besides being extracted from the translation file, placeholders can be added manually by project administrators on a *per-component* or *per-string* basis, but not project-wide. + +To set placeholders for a component: + +. Go to the component page (e.g. https://translate.fedoraproject.org/projects/dnf5/dnf5/[dnf5 translation component] of the https://github.com/rpm-software-management/dnf5/[DNF5] project) +. Use the menu menu:Manage[Settings] +. On the menu:Settings[] page, go to btn:[Translation] tab +. Scroll until you see btn:[Translation flags] field +. Write the `placeholders` flag expression in there ++ +-- +==== +For example: `placeholders:{}:{0}:{1}:{2}` +==== + +Such placeholders might be good for whole component as these terms might come up very often, like in a translation string _Failed to cleanup repository cache in path "{0}": {1}_. +-- + +To set a placeholders for a specific string (which will override its component's placeholders): + +. When editing a string, go to the right-side sidebar and find btn:[Flags] item +. Click on the pencil icon to edit the flags +. In the btn:[Translation flags] field, write the `placeholders` flag expression in there ++ +-- +==== +For example: `placeholders:--alldeps:--resolve` +==== + +These command-line options might be very good per-string placeholders if there isn't much of their occurence in the given component, like in a translation string _Option "--alldeps" should be used with "--resolve"_. +-- + +Further reference from Weblate software documentation: + +* https://docs.weblate.org/en/latest/user/checks.html#placeholders[Syntax on placeholders] +* https://docs.weblate.org/en/latest/admin/checks.html#custom-checks[Customizing behavior using flags]