Last week Jean-Baptiste Holcroft and Adam Šamalík met in Strasbourg for Docs Translations mini-FAD in order to prototype translations support for the Fedora Docs website. And we did a lot of work! This post is a report from the event, a status report, and a brief plan for how to move forward.
Our goal was to make sure we’re both on the same page about how it’s all going to work, to do some coding and publish a functional prototype, and to write a set of requirements for a potential production deployment.
The event happened a co-working space Le Shadok and we were grateful for being able to use the spaces for free.
The architecture we went for is flexible enough to support many different workflows and tools for translators while having as little impact on the Docs build pipeline as possible. To achieve that, we use the commonly used POT and PO files as an interface between the Docs build pipeline and the translators — so both words can operate at their own pace.
Because Antora doesn’t yet support languages, we work around it by building a separate site for each language, and we include a piece of UI that allows users to choose what language they want to view. One benefit of this approach is that all the internal links keep functioning within a language out of the box. And we’ll be ready to switch to a proper support later.
Progress at the event
There were three main areas of focus: coordination, coding, and making a plan for the future.
The architecture is not terribly complicated, but the devil is in the details — so the ability to get together and make sure we both understand it the same way and that it works nicely for both the Fedora Docs build pipeline and the translators was very beneficial.
From the technology perspective, we have focused on automation and bug-fixes (read: a complete rewrite) of the existing code, writing new parts to make it all work together, and thinking about ways of production deployment in the future.
The most visible change has been the UI that allows users to choose a language on the site.
However, the most work went to the scripts that do the conversion between Antora sources and the POT and PO files. We had a very simple functionality before the event, but it required a lot of human intervention to make it work over time. So we’ve added some automation to it and fixed bugs and the result has been a complete rewrite of the scripts. The result is one script that does it all. You can see it in the fedora-docs/translations-scripts repository on Pagure.
The website preview has been deployed to Fedora Docs Staging. Languages can be switched using the menu on the top-right corner.
The Antora build, including the languages, is now being built automatically in Fedora OpenShift. However, the Antora sources with the translated content has to be generated manually.
Jean-Baptiste’s Weblate instance is available for people to try — it supports FAS (Fedora Account System) login.
Fun statistics: we have converted over 1,500 source pages into translatable POT files. That resulted in 65,000 sentences to be translated into each language.
At the moment, all of this is just to demonstrate how the whole pipeline works and to test it. Production deployment is yet to be discussed.
There are still a few things missing in the pipeline — such as support for images, and a few minor bugs. We feel it is good enough to be tested now, but we need to fix them before going to production.
To deploy this in production, there are two things missing: a service that will do the conversion between Antora sources and the POT and PO files (that is done manually now), and a translation platform.
To deploy the scripts into production, there is still some hardening to be done, but once that’s completed, it will only require an OpenShift service that will run periodically.
For the translation platform, there are still conversations to be had about which one to use and where to run it. We have used Weblate in this example because we believe it does a great job for what we need.
We invite people to try what we’ve build and send us feedback either here in the comments or on the Fedora Docs mailing list.