The Fedora project documentation website provides a lot of end-users content. All of this content is now translateable, providing a powerful tool for our multilingual communication. Writers will continue to work as usual. The publishing tools automatically convert content and push it to the translation platform. Then, translated content is automatically published.

Restoring a multilingual Fedora communication

In the past, Fedora community used the wiki for both internal and external communication. Translating the wiki is doable using templates, but there is no tool to ease translation maintenance. Source content and translation can easily become out of sync.

At that time, we also had a documentation using DocBook. DocBook is based on XML with multilingual support, but the publication processes were complex enough that much translator work went unpublished.

The Fedora project decided to move into documentation as code, and it is a great success. It aggregates the content of 41 repositories from the many Fedora community teams and groups. The current content is about 1,500 pages and 2,000,000 words. This content can be either for contributors or end users.

The build mechanism to translate everything

Since 2016, we have a new publication tool named Antora, but it was lacking the ability to localize the content. Luckily, translating text is easy to do, thanks to the po4a converter. This tool converts from asciidoc to po, the most common translation template. Easy to interface with many existing tools.

A first proof of concept demonstrated in Flock 2016 already.

Last year, we met in Strasbourg to design the following build mechanism:

  1. Retrieve the English content, convert it to po-templates and save the content in Pagure
  2. Plug the Weblate translation platform to Pagure, contributors will translate and their work will end-up into po files.
  3. Convert all the po files into translated content.
Multilingual build pipeline of Fedora docs

Once we had the tool and the conversion mechanism, we had to decide what to translate. We finally decided to keep it simple, and allow the community to translate everything by default. This provides autonomy for everyone and simplifies the automation.

Transparent workflow

All content added to the documentation system will reach the translation platform. Any translation in an existing language or a new language publishes automatically. Thus, there is no specific request to send for any of this.

To summarize: the multilingual documentation system is fully automated. Thanks to our new translation platform, the great Pagure, the magical po4a and the work of Jean-Baptiste Holcroft and Adam Šamalík, with help of many other contributors.