From Fedora Project Wiki
m (add links)
m
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Taiga follow-up: https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/epic/1
+
{{autolang|base=yes}}
 +
 
 +
{{admon/important|Work in progress|Goal: to be able to translate the Fedora [[Docs Project]] documentation in our [[L10N/Translation Platform]]}}
 +
 
 +
* FAD on this subject will be on April' 12th and 13th: https://pagure.io/Fedora-Council/tickets/issue/250
 +
* English report: https://communityblog.fedoraproject.org/fedora-docs-translations-fad-report/
 +
* French report: https://jibecfed.fedorapeople.org/blog-hugo/fr/2019/04/notre-documentation-pourra-bient%C3%B4t-%C3%AAtre-traduite-/
 +
 
 +
Contributors:
 +
* [[user:asamalik]] (antora usage and scripting),
 +
* [[user:jibecfed]] (scripting, testing, internationalization, translation platform),
 +
* [[user:bex]] (po4a patches)
 +
 
 +
==  Overview ==
 +
 
 +
English source -> POT files -> PO files -> translated source -> translated site
 +
[[File:Fedora-docs-build-pipeline.png|thumb|center|Build pipeline of fedora-docs including internationalization and localization ]]
 +
 
 +
=== Git organization ===
 +
 
 +
# English source => Doc repository ==> (D)
 +
## Mostly on https://pagure.io/projects/fedora-docs/%2A
 +
# POT files -> PO files => localization repository ==> (L)
 +
## https://pagure.io/projects/fedora-l10n/%2A
 +
# PO files -> localized content
 +
## https://pagure.io/fedora-docs/translated-sources/
 +
# translated source => "web" repository ==> (W)
 +
## https://pagure.io/fedora-docs/fedora-docs-web/ (see branches)
 +
 
 +
=== Process ===
 +
 
 +
# When there is a change in (D), it will call a job, and update pot files in (L)
 +
# When there is a change in (L), translation platform will know and get updated
 +
# When there is a change in translation platform, it will update content in (L)
 +
# Every day or night, content from (D for EN) and (L for every other languages) are used to generate content for (W), and publish it
  
 
== Current phase ==
 
== Current phase ==
Line 7: Line 41:
 
* We create a few other languages to validate the tool.
 
* We create a few other languages to validate the tool.
 
* We use a Weblate as a test tool http://translate.holcroft.fr/
 
* We use a Weblate as a test tool http://translate.holcroft.fr/
 +
 +
== How to build ==
 +
 +
To build translated website, just run the "build-translated.sh" file from: https://pagure.io/fedora-docs/docs-fp-o
 +
Note: I wrote an updated script (using local cache to save a LOT OF TIME): https://pagure.io/fork/jibecfed/fedora-docs/docs-fp-o/tree/tracking
 +
 +
To produce new pot from source and new localized content from po files: https://pagure.io/fedora-docs/translations-scripts/
 +
Note: you need commit right on multiple repositories to do so.
  
 
== Requirements to enter Beta Phase ==
 
== Requirements to enter Beta Phase ==
Line 16: Line 58:
  
 
* Done:
 
* Done:
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/ #110] POT+PO repositories — design the structure
+
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/110 #110] POT+PO repositories — design the structure
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/ #111] POT+PO repositories — create them
+
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/111 #111] POT+PO repositories — create them
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/ #112] Translated source repositories — design the structure
+
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/112 #112] Translated source repositories — design the structure
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/ #113] Translated source repositories — create them
+
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/113 #113] Translated source repositories — create them
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/ #114] English source -> POT script — write it
+
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/114 #114] English source -> POT script — write it
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/ #115] PO -> translated source script — write it
+
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/115 #115] PO -> translated source script — write it
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/ #119] Build script for translated site — write it
+
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/119 #119] Build script for translated site — write it
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/ #123] Redesign the structure of the PO and POT repositories
+
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/123 #123] Redesign the structure of the PO and POT repositories
* TODO:
 
 
** Fix the language code (we should stick to IETF BCP 47 language tag and not assume anything)
 
** Fix the language code (we should stick to IETF BCP 47 language tag and not assume anything)
 
*** Context: a language can have multiple regional declination (and variants, etc.).
 
*** Context: a language can have multiple regional declination (and variants, etc.).
 
*** In this URL: https://docs.fedoraproject.org/fr-FR/docs/ the language code should be fr, because it's how the folder is named. https://pagure.io/fedora-l10n/docs/blob/master/f/po (it's the translation platform who will create the correct folder name)
 
*** In this URL: https://docs.fedoraproject.org/fr-FR/docs/ the language code should be fr, because it's how the folder is named. https://pagure.io/fedora-l10n/docs/blob/master/f/po (it's the translation platform who will create the correct folder name)
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/ #116] Translated UI — determine how it's gonna work
+
** Generate the [https://pagure.io/fedora-docs/translations-scripts/blob/master/f/all-src-to-pot.sh list of docs to convert for translation in all-src-to-pot] from [https://pagure.io/fedora-docs/docs-fp-o/blob/master/f/site.yml site.yml]
*** Includes: browser's language detection for redirection and language button? '''needs better description'''
+
** Create all required fedora-l10n repositories
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/ #117] Translated UI — create it
+
** Generate the list of translated language from localization repositories
*** what does it includes? '''needs better description'''
+
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/116 #116] Translated UI — determine how it's gonna work
 +
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/117 #117] Translated UI — create it
 +
* TODO:
 +
** Generate localized version of yml files
 +
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/122 #122] (spike) How do we deal with images?
 +
** use the same [script for language redirection as the one for fedora-wesites https://infrastructure.fedoraproject.org/cgit/ansible.git/tree/roles/fedora-web/getfedora/files/languages.conf]
  
 
== Requirements to enter Public Availability ==
 
== Requirements to enter Public Availability ==
Line 39: Line 85:
 
# translation platform is Zanata or any other tool the Fedora community decide to use
 
# translation platform is Zanata or any other tool the Fedora community decide to use
  
* [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/ #120] Process for adding new content — draft it
+
DONE:
* [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/ #121] Process for adding a new language — draft it
+
* [https://pagure.io/fedora-docs/translations-scripts/blob/master/f/all-po-to-src.sh don't assume language list in all-po-to-src]
* [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/ #130] Fix: Clicking on the logo should go to a homepage of the current language
+
TODO:
* [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/ #122] (spike) How do we deal with images?
+
** Infra ticket is open: https://pagure.io/fedora-infrastructure/issue/7696
* Doc generation should use fedora infrastructure (and not Asamalik's computer)
+
* [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/120 #120] Process for adding new content — draft it
 +
* [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/121 #121] Process for adding a new language — draft it
 +
* [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/130 #130] Fix: Clicking on the logo should go to a homepage of the current language
 +
* Doc generation should use fedora infrastructure (and not Asamalik's fedorapeople)
  
 
== Other needed improvements  ==
 
== Other needed improvements  ==
  
 
* TODO:
 
* TODO:
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/ #133] include localized URL in sitemaps
+
** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/133 #133] include localized URL in sitemaps
 
** Generally speaking, respect i18n-checker advices https://validator.w3.org/i18n-checker/
 
** Generally speaking, respect i18n-checker advices https://validator.w3.org/i18n-checker/
*** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/ #35] We need to be able to generate “href lang attributes”
+
*** [https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/35 #35] We need to be able to generate “href lang attributes”
 
** RTL texts (arabic, ...)
 
** RTL texts (arabic, ...)
 
** Dedicated documentation
 
** Dedicated documentation
 +
 +
== Other follow up tools ==
 +
 +
Taiga follow-up: https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/epic/1
 +
[[Category:Localization]]

Latest revision as of 13:35, 26 September 2019

Important.png
Work in progress
Goal: to be able to translate the Fedora Docs Project documentation in our L10N/Translation Platform

Contributors:

Overview

English source -> POT files -> PO files -> translated source -> translated site
Build pipeline of fedora-docs including internationalization and localization

Git organization

  1. English source => Doc repository ==> (D)
    1. Mostly on https://pagure.io/projects/fedora-docs/%2A
  2. POT files -> PO files => localization repository ==> (L)
    1. https://pagure.io/projects/fedora-l10n/%2A
  3. PO files -> localized content
    1. https://pagure.io/fedora-docs/translated-sources/
  4. translated source => "web" repository ==> (W)
    1. https://pagure.io/fedora-docs/fedora-docs-web/ (see branches)

Process

  1. When there is a change in (D), it will call a job, and update pot files in (L)
  2. When there is a change in (L), translation platform will know and get updated
  3. When there is a change in translation platform, it will update content in (L)
  4. Every day or night, content from (D for EN) and (L for every other languages) are used to generate content for (W), and publish it

Current phase

  • We are in Alpha
  • We translate in French to validate the tooling.
  • We create a few other languages to validate the tool.
  • We use a Weblate as a test tool http://translate.holcroft.fr/

How to build

To build translated website, just run the "build-translated.sh" file from: https://pagure.io/fedora-docs/docs-fp-o Note: I wrote an updated script (using local cache to save a LOT OF TIME): https://pagure.io/fork/jibecfed/fedora-docs/docs-fp-o/tree/tracking

To produce new pot from source and new localized content from po files: https://pagure.io/fedora-docs/translations-scripts/ Note: you need commit right on multiple repositories to do so.

Requirements to enter Beta Phase

Beta phase means:

  1. translation is open for a few more languages, testing is still active.
  2. translation platform is still Weblate as a test tool

Requirements to enter Public Availability

Public Availability means:

  1. translation is open for every needed languages.
  2. translation platform is Zanata or any other tool the Fedora community decide to use

DONE:

TODO:

  • #120 Process for adding new content — draft it
  • #121 Process for adding a new language — draft it
  • #130 Fix: Clicking on the logo should go to a homepage of the current language
  • Doc generation should use fedora infrastructure (and not Asamalik's fedorapeople)

Other needed improvements

  • TODO:
    • #133 include localized URL in sitemaps
    • Generally speaking, respect i18n-checker advices https://validator.w3.org/i18n-checker/
      • #35 We need to be able to generate “href lang attributes”
    • RTL texts (arabic, ...)
    • Dedicated documentation

Other follow up tools

Taiga follow-up: https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/epic/1