Translations are coming!

[Adam Samalik]

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



[1]
https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/epic/1
[#110]
https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/110
[#111]
https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/111
[#112]
https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/112
[#113]
https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/113
[#114]
https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/114
[#115]
https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/115
[#116]
https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/116
[#117]
https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/117
[#118]
https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/118
[#119]
https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/119
[#120]
https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/120
[#121]
https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/121

-- 

Adam Šamalík
---------------------------
Software Engineer
Red Hat