#12 'Translation hints and tips' added to weblate.adoc, more changes to hosting.adoc
Merged 4 months ago by darknao. Opened 8 months ago by peartown.
fedora-l10n/ peartown/docs weblate-admin  into  stg

empty or binary file added
empty or binary file added
empty or binary file added
empty or binary file added
empty or binary file added
empty or binary file added
empty or binary file added
empty or binary file added
empty or binary file added
file modified
+1
@@ -1,4 +1,5 @@ 

  * xref:join.adoc[Join Localization community]

  * xref:weblate.adoc[How to use Weblate]

+ * xref:transtats.adoc[How to use Transtats]

  * xref:doc_l10n.adoc[Documentation Translation Workflow]

  * xref:hosting.adoc[Translation projects in Weblate]

@@ -2,6 +2,8 @@ 

  :experimental:

  

  = Documentation Translation Workflow

+ Fedora Localization Team

+ 2023-06-26

  

  This document outlines how the localization workflow works for the Fedora Documentation Website.

  

file modified
+106 -39
@@ -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]

@@ -1,6 +1,8 @@ 

  include::{partialsdir}/attributes.adoc[]

  

  = Fedora Localization Team

+ Fedora Localization Team

+ 2023-08-27

  	

  image::translation.png[]

  
@@ -11,7 +13,7 @@ 

  thus, projects can concentrate on development, while translators purely on translation.

  

  [[find-l10n]]

- == Where to find Fedora l10n team

+ == Where to find Fedora L10N team

  

  Mailing list:: {TRANSML}[{TRANSML}]

  Matrix room:: {CHAT}[#l10n:fedoraproject.org] in https://chat.fedoraproject.org[Fedora Chat]
@@ -23,6 +25,6 @@ 

  

  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].

+ Some insights into our localization tooling used in the Fedora Project for translating, for example the https://docs.fedoraproject.org[Fedora documentation], can be found in xref:doc_l10n.adoc[Documentation Translation Workflow].

  

- Projects considering the use of our translation platform for their translations might find relevant information xref:hosting.adoc[here].

+ Projects considering the use of our translation platform for their translations might find relevant information in xref:hosting.adoc[].

file modified
+5 -2
@@ -1,8 +1,11 @@ 

  include::{partialsdir}/attributes.adoc[]

  

- = Join Fedora Translation community

+ = Join Fedora Localization Community

+ Fedora Localization Team

+ 2023-03-16

+ :reftext: Join Fedora L10N team

  

- Become a member of Fedora Translation community by following these steps.

+ Become a member of Fedora l10n/translation community by following these steps.

  

  [[fedora-account]]

  == Create a Fedora Account

@@ -0,0 +1,65 @@ 

+ include::{partialsdir}/attributes.adoc[]

+ 

+ = What Is Transtats?

+ Fedora Localization Team

+ 2023-08-13

+ :reftext: What is Transtats?

+ :experimental:

+ 

+ Transtats is a web application which tries to tie up upstream repositories, translation platforms, build system, and product release schedule together to solve problems of mismatch, out-of-sync conditions and to assist the timely packaging of quality translations. Actually, it collects translation data, analyzes them, and creates meaningful representations.

+ 

+ Fedora Transtats is hosted at https://transtats.fedoraproject.org

+ 

+ image:transtats-landing.png[]

+ 

+ == Track Translations

+ 

+ === How to see the translation status of a package?

+ 

+ Just select Packages tab from left hand side navigation bar. This takes us to the packages list view. Then, search for the package and click on its name. For example anaconda.

+ 

+ image:anaconda-pkg.png[]

+ 

+ We can reach here from https://src.fedoraproject.org/rpms/anaconda as well.

+ 

+ On package details page, locate following:

+ 

+ image:anaconda-details.png[]

+ 

+ Languages in red color indicate that there are translated strings remaining in the Translation Platform to be pulled and packaged, whereas, yellow denote translated messages could not make 100% in the built package.

+ 

+ image:anaconda-stats.png[]

+ 

+ Here, we have translation statistics from translation platform: Weblate and Koji build system. Syncs with the platform and build system are scheduled, which update differences periodically.

+ 

+ ==== Login to add a new package

+ 

+ image:transtats-login.png[]

+ 

+ image:transtats-new-package.png[]

+ 

+ NOTE: Package name should match the project name on https://translate.fedoraproject.org.

+ 

+ === How to see the translation status of a language?

+ 

+ Use Languages tab to list all the supported languages. Click on any of the languages, say, German. This takes us to the translation status page.

+ 

+ image:german-stats.png[]

+ 

+ We can navigate further into details to estimate the translation work for a release.

+ 

+ === How to see the translation status of a territory?

+ 

+ Click on any of the territories from the map, say India. This shows high level statistics.

+ 

+ image:territory-stats.png[]

+ 

+ == Create Reports

+ 

+ Coverage rules can be created for a set of packages for specific details around string differences.

+ 

+ image:coverage-report.png[]

+ 

+ Transtats exposes an array of REST end points. See https://transtats.fedoraproject.org/api-docs/

+ 

+ For further information, please visit https://docs.transtats.org[Transtats Documentation].

file modified
+130 -1
@@ -1,6 +1,9 @@ 

  include::{partialsdir}/attributes.adoc[]

  

- = How to use Weblate

+ = How To Use Weblate

+ Fedora Localization Team

+ 2023-08-27

+ :reftext: How to use Weblate

  :experimental:

  

  This page describes in basic (ie. non-exhaustive) manner how to use and translate on the contemporary translation platform used by the Fedora Localization team.
@@ -60,3 +63,129 @@ 

  

  For further information about using Weblate software, please visit the official https://docs.weblate.org[Weblate Documentation].

  

+ // This could have it's own page in the future

+ == Translation hints and tips

+ 

+ Our primary aim for this subchapter is to provide some useful and quick information you may seek, particularly when you have just begun translating for Fedora.

+ It is inspired by questions received from within our community members and preserved in the "`question-and-answer`" style.

+ 

+ Should you wish to see other question answered here, please xref:index.adoc#find-l10n[let us know].

+ 

+ // Question 1

+ How to start translating a project in Weblate to my language? Why I can't find my language on the list?::

+ When you visit a project to translate in Weblate (fig. 1) and enter one of it's components, you are presented with a list of languages (fig. 2) that doesn't have to contain all languages set and available for translation in Weblate.

+ The list contains languages only for which a translation of a given project/component was created.

+ +

+ --

+ .A project with its translation components

+ image::Weblate_project_components_list.png[]

+ 

+ .A component with languages listed

+ image::Weblate_project_component_languages.png[]

+ 

+ Provided you have set a `_translated language_` in your profile setings, your language translation can be added, strictly speaking, created by clicking on the btn:[+] sign next to your language on the list (fig. 3).

+ If such option is not available to you, you can click btn:[Start new translation] button in the end of the list and subsequently choose your language from the list of all langauges available in Weblate (fig. 4)(fig. 5).

+ 

+ .Create translation button for the Czech language

+ image::Weblate_create_translation.png[]

+ 

+ .Start new translation page

+ image::Weblate_project_start_newtrans.png[]

+ 

+ .Dropdown list with all available languages

+ image::Weblate_project_start_newtrans_langlist.png[]

+ 

+ If you still cannot find your language and you expect 3 letter code, please note Weblate prefers https://docs.weblate.org/en/latest/admin/languages.html#language-code[two letter codes].

+ If you are not able to find your language even after that, https://pagure.io/fedora-l10n/tickets[file a ticket].

+ --

+ 

+ // Question 2

+ I want to translate Fedora Documentation, what docs should I start with?::

+ Try to start with the translation of the Fedora Docs https://docs.fedoraproject.org[homepage].

+ https://translate.fedoraprroject.org/projects/fedora-docs-l10n-docs/masterpagesindex is the relevant translation project in Weblate.

+ +

+ --

+ Go through https://docs.fedoraproject.org/en-US/quick-docs/[Quick Docs], our the most used documentation, and see if you can pick an article that suits your particular interest.

+ Quick Docs translation project in Weblate: https://translate.fedoraproject.org/projects/fedora-docs-l10n-quick-docs/.

+ 

+ Last but not least, why not translate the documentation of your Fedora edition?

+ --

+ 

+ // Question 3

+ Should I translate the text I find enclosed in curly brackets in the fedora-websites-3.0 project?::

+ No, it is not translatable and the text should be left unchanged.

+ +

+ --

+ The curly brackets in the https://translate.fedoraproject.org/projects/fedora-websites-3-0/[fedora-website-3.0] translation project are used to distinguish names of (HTML) templates.

+ A template's content(s) is inserted (interpolated) during the website build process.

+ Related text interpolation facilitates localization since it enables a combination of the content (text) of different HTML elements together, names of the templates in translation strings in turn preserves better the text context for translators.

+ Be assured that you will be able to translate the content of a template (text which substitutes the template) too, but in another translation string.

+ 

+ Let a text of the first numbered indent from the verification modal dialog (see fig. 6 below) which can be opened from a download page of the website serve us as an example:

+ 

+ `Download the checksum file and signature into the same directory as the image you downloaded.`

+ 

+ .Example of curly brackets translation - original

+ image::Website_translation_curlybrackets_example_en.png[]

+ 

+ This sentence is a combination of an ordinary text and two web links - _checksum file_ and _signature_. For the purpose of its correct translation, you are supposed to translate three translation strings.

+ 

+ .string 1

+ ....

+ Download the {checksum_file} and {signature} into the same directory as the image you downloaded.

+ ....

+ 

+ In this string you translate everything except `{checksum_file}` and `{signature}`, which should be retained unchanged (as these 'words' are actually the names of templates).

+ They can be placed anywhere in your translation sentence, even their order of appereance, if appropriate, can be exchanged (`{signature}` might come first, `{checksum_file}` second).

+ 

+ .string 2 and 3

+ ....

+ cheksum file

+   signature

+ ....

+ 

+ How you translate these two strings, they will appear exactly in the sentence after the website is built.

+ The following table shows an example of translation of the three strings to the Czech language:

+ 

+ .Example comparison of string translations

+ [cols="1,3,3,3"]

+ |===

+ | |English (original) |Czech (translated) |String key

+ 

+ |string 1

+ |Download the {checksum_file} and {signature} into the same directory as the image you downloaded.

+ |Stáhněte si {checksum_file} a {signature} do stejného adresáře, kam jste stáhli obraz.

+ |download_the_checksum_and_signature

+ 

+ |string 2

+ |checksum file

+ |soubor kontrolního součtu

+ |checksum file

+ 

+ |string 3

+ |signature

+ |podpis

+ |signature

+ |===

+ 

+ NOTE: Keys of both string 2 and 3 - `checksum file` and `signature` - correspond with the templates' names.

+ 

+ Strings 2 and 3 substitute the templates `{checksum_file}` and `{signature}` in the string 1. So these three strings  will be combined together into the resulting sentence. Moreover, the translated version works the same, as can be seen on the below image.

+ 

+ .Example of curly brackets translation - translated

+ image::Website_translation_curlybrackets_example_cs.png[]

+ 

+ If templates and the text interpolation were not used, it would be needed to translate five translation strings to build the sentence:

+ 

+ ....

+ 1. Download the

+   2. checksum file

+   3. and

+   4. signature

+   5. into the same directory as the image you downloaded.

+ ....

+ 

+ Imagine the strings in Weblate were not placed any near each other, then the text context for successful translation would be very limited, if not lost completely.

+ 

+ CAUTION: If you attempted to translate the template names (curly brackets) in string 1 directly, the template substitution and consequently text/translation interpolation on the website would be broken.

+ --

This PR more or less touches all pages. The main changes are:

  • some continuation from fedora-l10n/docs#9 regarding hosting.adoc page, a new chapter "Project configuration good practice" added
  • new chapter "Translation hints and tips" added to weblate.adoc, image files included
  • author and revision date attributes/metadata added to the pages

I've asked to pull to stg as I'm not sure it is publishable in the current state.

Still, I'd like to get some help (input, review) from our Fedora Weblate admins for the hosting.adoc. I would appreciate a feedback if such information could be helpful.

For the Translation hints and tips I tried to use [qanda] type of list, but the list formatting didn't work properly IMHO in the local preview. Moreover, the questions were part of the ToC (and thus quite long), so I use discrete type heading instead.

I also added reftext attribute to page titles, however I think I don't have much use for it yet.

1 new commit added

  • Modify weblate.adoc - Question added - documentation
8 months ago

1 new commit added

  • Modify weblate.adoc - Translation hints and tips reworked from descrete headings into description lists of Q&A style
5 months ago

AFAIK "in" is not capitalized in Title Case

Not only Fedora subprojects are hosted though. For instance, plymouth is freedesktop's and there is GUIX. Should the text make room for possibly allowing other free (as in freedom) projects?

Consider making it "Translation Projects in Weblate" (Title Case) in the hyperlink text to match the case change in the xref-ed doc.

Not only Fedora subprojects are hosted though. For instance, plymouth is freedesktop's and there is GUIX. Should the text make room for possibly allowing other free (as in freedom) projects?

'Any free and open source software project is welcome to use this platform.' is 1st sentence of the following 'Considerations to upstream projects' section. To empfhasize this more, I would need to think about another rewording/restylization. Just now, I am thinking about using eg. sidebar...

Consider making it "Translation Projects in Weblate" (Title Case) in the hyperlink text to match the case change in the xref-ed doc.

One more reason to get rid off (or at least rethink) the reftext page attribute I unnecessarily introduced earlier.

2 new commits added

  • Small styling changes to index.adoc and hosting.adoc
  • Modify hosting.adoc - More emphasis to 'non-Fedora' projects
4 months ago

1 new commit added

  • Modify hosting.adoc - added info about placeholders to good practice
4 months ago

Pull-Request has been merged by darknao

4 months ago
Metadata