| |
@@ -2,24 +2,42 @@
|
| |
|
| |
// hosting.adoc? - is there a better file name for this page, will be part of URL?
|
| |
|
| |
- = Translation projects in Weblate
|
| |
+ = Translation Projects in Weblate
|
| |
+ Fedora Localization Team
|
| |
+ 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
|
| |
|
| |
- 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.
|
| |
+ The Fedora Project runs a web-based online translation platform powered by https://weblate.org[Weblate software].
|
| |
+ 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.
|
| |
+
|
| |
+ [IMPORTANT]
|
| |
+ ====
|
| |
+ Not only Fedora subprojects are hosted though.
|
| |
+ Examples of free and open source projects which can be found on Fedora Weblate translation platform and comes rather outside of Fedora:
|
| |
+
|
| |
+ . https://guix.gnu.org[Guix]
|
| |
+ . https://www.freedesktop.org/wiki/Software/Plymouth/[Plymouth]
|
| |
+ ====
|
| |
|
| |
- === 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.
|
| |
+ === Considerations to upstream projects
|
| |
|
| |
- Few examples of motivation behind this approach:
|
| |
+ *Any free and open source software project is welcome to use this platform.*
|
| |
+ Not only is it 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, but also we considered there is more motivation behind this approach, such as:
|
| |
|
| |
- * We support any project sharing the *same xref:project:ROOT:index.adoc[values]* as the Fedora Project
|
| |
+ * To provide a support to 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
|
| |
@@ -38,58 +56,107 @@
|
| |
* 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
|
| |
+ == Request a new translation project on Fedora Weblate
|
| |
|
| |
- _Not what an individual has decided to translate._
|
| |
+ 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:
|
| |
|
| |
+ * 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._
|
| |
-
|
| |
+ * 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
|
| |
+ .Project request with example values in italics
|
| |
+ |===
|
| |
+ | 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), subsequently notified about the project creation.
|
| |
+
|
| |
+ 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.
|
| |
|
| |
- Website: //https://github.com/debbuild/debbuild
|
| |
|
| |
- Repository: //https://github.com/debbuild/debbuild
|
| |
+ == Project configuration good practice
|
| |
|
| |
- Name of the development branch:
|
| |
+ 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.
|
| |
+ 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:
|
| |
|
| |
- Filemask: //po/*
|
| |
+ // 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
|
| |
|
| |
- Username: //ngompa
|
| |
+ ----
|
| |
+ https://translate.fedoraproject.org/hooks/pagure //for Pagure
|
| |
+ https://translate.fedoraproject.org/hooks/gitlab //for GitLab
|
| |
+ https://translate.fedoraproject.org/hooks/github //for GitHub
|
| |
+ ----
|
| |
|
| |
- Optional:
|
| |
+ // 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].
|
| |
|
| |
- Any announcement/warning you would like to display to the translators? (it will be displayed in Weblate)
|
| |
+ // 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.
|
| |
|
| |
- A need to activate any specific checks? (this is a setting per component)
|
| |
+ To set placeholders for a component:
|
| |
|
| |
- A need to automatically detect new translation files? (typical usecase: website translation with one translation file per page)
|
| |
+ . 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}`
|
| |
====
|
| |
|
| |
- // 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
|
| |
+ 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`
|
| |
+ ====
|
| |
|
| |
- The specified username(s) will be set in the initial configuration of the project in Weblate as the project's administrator(s).
|
| |
+ 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"_.
|
| |
+ --
|
| |
|
| |
- Once the initial configuration is made the project contact(s) will be notified.
|
| |
+ Further reference from Weblate software documentation:
|
| |
|
| |
- 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'??
|
| |
+ * 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]
|
| |
This PR more or less touches all pages. The main changes are: