README.md

Fedora Docs internatialization

This is a prototype of a multi-language Fedora Docs build pipeline. Work is tracked in https://fedoraproject.org/wiki/User:Jibecfed/fedoradoc-antora-localization.

The internatialization work with:

How to run

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

$ sudo dnf install podman

You can build the container image with Podman:

$ cd translations-scripts
$ podman build . -t builder:latest

To run the build.py script inside a container:

$ podman run builder:latest ./build.py [args]

Alternatively, you can mount your own local repository inside the container, for development purpose:

$ podman run -v ./:/workspace:Z builder:latest ./build.py [args]

Or you can open an interactive shell to tinker with:

$ podman run -it builder:latest /bin/bash

Submitting sources for translation

The buid.py script will find list of repositories to be translated in the file site.yml from the the docs-fp-o repo. 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 the following arguments :

  --clone_sources {true,false}
                   Should we clone/update sources or use local content?
  --commit_l10n {true,false}
                   Should we commit changes on l10n repos?
  --commit_tsources {true,false}
                   Should we commit translated sources?
  --component COMPONENT
                   Antora component to convert, all if unset

The buid.py script will create three folders:

  • $(pwd)/sources — Fedora Docs sources
  • $(pwd)/l10n — Translation repos
  • $(pwd)/translated-sources — Translated sources

Publish translated sources

$ cd translated-sources
$ git add.
$ git commit -m "automatic update of translated content"
$ git push

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://gitlab.com/fedora/docs/docs-website/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/.

Maintenance

When you run the build.py process, an "errors.txt" file will be generated. It contains missing fedora-docs-l10n repositories.

Adding a new repository

Example data:

Process:

  • Log in https://pagure.io, in the top menu, follow: Create > New project
    • Set for Project: doc-example
    • Set for Description: translation of example-doc-project
    • Set for Project namespace: fedora-docs-l10n
    • Select "Create README"
  • Go in Settings > Project Options:
  • Go in Settings > Users & Groups:
    • add group: fedora-docs-l10n with commit rights
  • Go in Settings > Hooks:

    • enable the Fedmsg hook
    • click the update button
  • Log in https://translate.fedoraproject.org, follow: Add > Add new translation project

  • Click the add new translation component
    • Set the component name as "nav" (use antora if no nav)
    • Version control system: git
    • URL is: ssh://git@pagure.io/fedora-docs-l10n/ask-fedora-sops.git
    • validate and select the nav pattern
    • Set Repository push URL: ssh://git@pagure.io/fedora-docs-l10n/ask-fedora-sops.git
    • Disable "Edit base file"
    • set License as CC-SA-3.0
    • Save
  • Open the component and access Addons
    • Automatic translation
    • Contributors in comment
    • Update PO files to match POT (msgmerge)
    • Squash Git commits: Commit squashing Per author
    • Component discovery: This addon automatically adds or removes components to the project based on file changes in the version control system.
      • Regular expression to match translation files against po/(?P<language>[^/]*)/(?P<component>.*)\.po
      • File format: gettext PO file
      • Customize the component name: {{ component }}
      • File for new translations pot/{{ component }}.pot
      • Language filter ^[^.]+$
      • Clone addons from the main component to the newly created ones True
      • Remove components for inexistant files True