On Mon, Oct 1, 2018 at 4:20 PM Petr Bokoc <pbokoc@xxxxxxxxxx> wrote:
Thanks, Brian.
Adam, Jean-Baptiste, thank you for doing this; I can't wait to see how the system works in practice.
Adam, the proposal looks reasonable. Regarding where to store translated sources: based on the Antora issue for multilang support[0], if I'm reading that right, we should be able to store them in the same repo as the English sources, just in a different directory. We'll just need to move the English version into "en_US/" from the repo root (Antora apparently assumes en_US/ by default) and store other sources in their own directories, but it can all be one repo. I'm just not sure how much of what Dan is talking about in the issue is actually implemented in Antora. Does anyone know what happens if we store the sources in "en_US/modules/<name>/pages" right now - is anything going to break? If not we can just do that right away.
Of course, that requires that someone to periodically in the POs from our translation platform, run the script to apply them to the sources, and push the translated sources in the correct directory. The process was fairly manual before with DocBook/publican, too, so it shouldn't be a huge issue.
Mixing the original English source with anything else is exactly what we want to avoid. That's mostly for two reasons:
1) We don't always have permissions to modify the source repository. Even though we did, it might be invasive.
2) People are never supposed to edit the translated sources. All work happens in a translation platform that consumes POT files and produces PO files.
That's why we keep the source repos unmodified. We'll convert them to POT, load that to the translation platform which is where human interaction happens, and then we go the PO -> asciidoc -> website in basically one step.
How does that sound?
_______________________________________________
Petr
[0] https://gitlab.com/antora/antora/issues/208
On 10/1/18 2:08 PM, Brian (bex) Exelbierd wrote:
On Thu, Sep 27, 2018 at 4:52 PM Adam Samalik <asamalik@xxxxxxxxxx> wrote:
_______________________________________________Hey everyone,
I had some discussions about translations with a few people and this is the result:
We have a new epic [1] tracking the initial implementation.
The English pipeline is quite straightforward — it takes the English source and converts it into the English site. That already works today.
Simplified view: `English source -> English site`
The translation pipeline has a few more steps. First, we need to have a script that converts the English sources to POT files [#114] which are used for translations. These POT files need to be stored in a git repository [#110] [#111] and will be consumed by a translation engine which pushes the results back into the repo. To make it consumable for Antora, we need another script that converts the resulting PO files into translated sources [#115] and store them [#112] [#113] somewhere. Before the site can be built, we also need to have a translated UI for each language that also has a language switcher [#116] [#117]. The UI along with the translated sources will be consumed by a build script [#119] that builds the final website.
Simplified view: `English source -> POT files -> PO files -> translated source -> translated site`
Apart from these, we also need to have two new policies. One for adding new content to the docs [#120] which need to ensure that the new content is also being translated properly. The other one will be about introducing a new language [#121] and will make sure that all the repositories are set up and that the UI also supports this new language.
Last thing is the "edit this page" button on translated sites. For that, we probably need to have a page for each language explaining that the content is created and edited in English, and how translations work and how to contribute. And the "edit this page" link (with likely a different wording) will point to that page. There are no cards for this, yet.
So, we need places to store:* POT + PO files for every language [#110] [#111]* translated sources for every language [#112] [#113]
We needs scripts for:* Converting English sources to POT files [#114]* Converting PO files to translated sources for every language [#115]* Converting translated sources + translated UI to the translated site for every language [#119]
And we also need:* Translated UI for every language [#116] [#117]* Policy for adding new content to the docs that ensures adding it also to translations [#120]* Policy for introducing a new language [#121]
As you can see, the implementation will be "translation engine-agnostic" — using POT and PO files. This way we can have some flexibility.
I'll start working on it later this week. If you have any feedback or want to help, let me know!
Cheers!Adam
--
Software Engineer
Adam Šamalík
---------------------------
Red Hat
docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx
Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html
List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
List Archives: https://lists.fedoraproject.org/archives/list/docs@xxxxxxxxxxxxxxxxxxxxxxx
--
Brian (bex) Exelbierd | bexelbie@xxxxxxxxxx | bex@xxxxxxxxx
Fedora Community Action & Impact Coordinator
@bexelbie | http://www.winglemeyer.org
_______________________________________________ docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@xxxxxxxxxxxxxxxxxxxxxxx-- Petr Bokoč (pbokoc) Senior Technical Writer Community Platform Engineering Red Hat Czech, s. r. o. Purkyňova 99 612 45 Brno, Czech Republic
docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx
Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html
List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
List Archives: https://lists.fedoraproject.org/archives/list/docs@xxxxxxxxxxxxxxxxxxxxxxx
--
Adam Šamalík
---------------------------
Red Hat
_______________________________________________ docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@xxxxxxxxxxxxxxxxxxxxxxx
