Docs Translation Prototype

This is a prototype of a multi-language Fedora Docs build pipeline. Work is tracked in https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/epic/1.

These scripts work with:

• Fedora Docs sources — sources of the docs in an adoc format.
• Translation repos — pagure.io/projects/fedora-l10n/* — repositories holding POT and PO files, acting as a bridge between the Fedora Docs site and translators. This way, translators can choose any workflow with a translation engine of their choice. The only requirement is that they need to work with POT and PO files.
• Translated sources - pagure.io/fedora-docs/translated-sources/ — all translated adoc files used to build the translated site.

How to run

Make sure Podman is installed on your system. You can install Podman using the following command:

$ sudo dnf install podman

Submitting sources for translation

The all-src-to-pot.sh holds a list of repositories to be translated. It clones all of the specified source repositories, all of the matching translation repos, and converts the English sources into POT files. The output of this script are local copies of the translation repos, updated with the newly generated POT files.

It takes one argument — an absolute path to an empty directory to store the output.

First, create an empty directory for the output and run the script:

$ mkdir translation-repos
$ ./all-src-to-pot.sh $(pwd)/translation-repos

Now you have local copies of the translation repos under ./translation-repos, with the updated POT files. The next step is to push the changes to each repo. Go to the directory, and list all the repos:

$ cd translation-repos
$ ls
docs  fedora  fedora-install-guide  fedora-release-notes

Then go to each repo, and push the changes. For example:

$ cd docs
$ git add .
$ git commit -m "refresh POT files"
$ git push
$ cd ..

Repeat this for each repo. And you're done.

Retrieving the translated sources

The $ ./all-po-to-src.sh holds a list of repositories to be translated and a list of target languages. The output is a local copy of the translated sources repo, updated with the newly generated adoc files.

See the structure of the translated sources.

First, create a directory for the output and run the script:

$ mkdir translated-sources
$ ./all-po-to-src.sh $(pwd)/translated-sources

Now you have a local copy of the translated sources repo, right in ./translated-sources. To push the changes:

$ cd translated-sources
$ git add .
$ git commit -m "update translated source"
$ git push
$ cd ..

Rebuilding the translated website

The official Fedora Docs docs-fp-o repo holds Antora playbooks for each language of the docs, and build scripts for each language.

Note: The playbooks are constructed manually and might not be up-to-date. Please make sure to update them based on the main site.yml and the outputs in the translated sources repo.

Clone the repository, run a build of the translated sites (each language is its own site), and run a local preview:

$ git clone https://pagure.io/fedora-docs/docs-fp-o.git
$ ./build-translated.sh
$ ./preview.sh

Now you should be able to see, for example, the French site, on http://localhost:8080/fr-FR/.