Weblate Integration

Hedy uses Weblate for translation purposes. This page describes how Hedy integrates with Weblate.

Weblate data model

According to Weblate's page on continuous localization, this is what the Weblate data model looks like:

Things that can go wrong

The translatable files are the .pot and .po files, and .yaml files in content. Because these files get updated by many people and scripts from multiple sides, we have a lot of reformatting and validation scripts around these files to avoid merge conflicts as much as possible.

• .po files
  • In Weblate, should be set to "hard wrapping" (only wrap at \n boundaries)
  • Our validation scripts check for the wrapping, as well as no duplicated nor empty keys.
• .yaml files
  • In Weblate, should be set to "no wrapping" and "indent: 4" (even though Weblate still sometimes wraps them for unclear reasons)
  • Our validation scripts check that the YAML files match schema files that exist, we have a reflowing script that fixes the indentation and sets key order in a way that makes sense for humans editing the YAML directly, and we test all code samples inside YAML files.

Weblate configuration

For every individual component:

• Go to Manage > Settings > Version Control.
  • Push on commit: unchecked
  • Age of changes to commit: 2160
  • Merge style: rebase
• Go to Manage > Add-ons.
  • Yaml
    • Indentation: 4
    • No line wrapping

Weblate workflow

In order to minimize merge conflicts, we don't let Weblate automatically create commits all the time. Instead, we have a GitHub Actions Job that runs every morning, early hours UTC, to do the following:

• Pull the latest changes from upstream. Pulling brings in reflowed YAML files or new translations; Weblate scans the updated files to add them to its database. Weblate pulls continuously throughout the day as the Hedy repo is updated, but we also do a final Pull here just to be Extra Safe.
• Only then create commits with new translations. This is unlikely to lead to conflicts, as Weblate just pulled the latest code from the Hedy repo.
• Push and create a PR. This creates a PR on the Hedy repository with the freshly committed changes.
• Automatically approve that PR. A GitHub Action runs to automatically approve Weblate PRs. The normal PR validation checks run, and the PR is merged as soon as they pass.

This controlled pull workflow automatic approval workflow keeps the window in which conflicts could arise very small: we would get conflicts only if some PR gets merged that touches the translation files in the ~1 hour between the pull and the merge every morning around 06:00-07:00 UTC.

The workflow can also be run on-demand if necessary.