Documentation Translation Workflow

Fedora Localization Team Last review: 2023-06-26

This document outlines how the localization workflow works for the Fedora Documentation Website.

Localization pipeline

Description

The localization process of the documentation works in three steps:

  • Extract strings from the English sources and produce POT files.

  • Translators translate these POT files and produce PO files.

  • We consume these PO files to construct translated sources, and finally to build the translated website.

Step 1 and 3 is handled by the localization pipeline scripts. Step 2 take place in Weblate.

Core scripts

Localization pipeline scripts are hosted on Pagure in the translation-scripts repository. This set of scripts run everyday at 21h UTC on our Openshift cluster.

The main script build.py extracts all strings from adoc files in all components, create POT files, then use translated PO files to generate translated adoc files that will be used to build the final documentation website.

Translated adoc files are stored in the translated sources repository.

A schema of how localization of Fedora Documentation is organized
Figure 1. Fedora Documentation localization build pipeline

Translation repositories

Design rationale

Documentation content is divided into components (spaces with their own navigation menu).
Each component can have multiple versions, and also multiple modules.

The primary function of modules is the ability to store different parts of components in different git repositories. But they can be also stored in a single repository.
One repository can even hold multiple components. And moving components or modules between repositories have no influence on the output.

This is also valid for translations, moving components around should not change the content for translators.
That’s why we need to organize the PO and POT wiles not according to repositories, but according to the components, modules, and versions.

Standard Antora repository structure
📒 repository (1)
  📄 antora.yml (2)
  📂 modules (3)
    📂 ROOT (4)
      📁 attachments (5)
      📁 examples (6)
      📁 images (7)
      📁 pages (8)
      📁 partials (9)
      📄 nav.adoc (10)
    📂 named-module (11)
      📁 pages
      📄 nav.adoc
  📁 packages (12)
1 The repository name has no influence on the documentation & translation output. By default, Antora assumes the documentation content source is at the root of a repository unless the start_path or start_paths is defined in the Fedora Doc’s playbook.
2 A component version descriptor file, named antora.yml, is required at each content source root.
3 Required directory named modules. A modules directory must contain, at a minimum, either a ROOT module directory or a named module directory.
4 Optional ROOT module directory. A module directory must contain at least one family directory.
5 Optional attachments family directory.
6 Optional examples family directory.
7 Optional images family directory.
8 Optional pages family directory.
9 Optional partials family directory.
10 Optional navigation file named nav.adoc.
11 Optional named module directory.
12 Antora won’t process the files in this directory because it’s located outside the modules directory.

Structure description

Translations are stored in dedicated repositories in the fedora-docs-l10n Pagure namespace.
Each repository uses the following structure:

Standard translation repository structure
📒 component-module (1)
  📂 pot (2)
    📁 version (3)
      📄 page.pot
  📁 po (4)
    📂 language-code (5)
      📁 version
        📄 page.po
1 The repository name is <component_name>-<module_name>, or just <component_name> for the ROOT module.
2 pot directory contain the source translation files used to start new translations.
3 The version directory is named from the version key in the component antora.yml. If not defined, it will be named master.
4 po directory contain translations that come directly from Weblate.
5 The language-code directory is named using codes as defined by ISO 639-1, ISO 639-2 or ISO 639-3 when required. (ie.: de, pt_BR or zh_Hans).
Renaming components or modules results in the loss of translations for that component and/or module.
While the content of those repositories is automatically generated by the localization pipeline and Weblate, each repository must first be created manually.

Repository creation

  1. Log in https://pagure.io and, in the top menu, click on: Create  New project.

    • Project name: <component_name>-<module_name> or <component_name> if ROOT module.

    • Description: translation of <documentation_repository_url>.

    • Project Namespace: fedora-docs-l10n.

    • Select "Create README".

  2. In the new repository, go in Settings  Project Options:
    In the Web-hooks field, add: https://translate.fedoraproject.org/hooks/pagure/, then click Update

  3. In Settings  Users & Groups:
    Click add group, select the fedora-docs-l10n group, choose commit in the second list, then click Add.

  4. In Settings  Hooks  Fedmsg:
    Check "Active", then click Update.

Weblate project

Documentation related projects are prefixed with fedora-docs-l10n.

Project creation

TBD

Want to help? Learn how to contribute to Fedora Docs ›