Skip to content

Review Weblate's translation workflow and its integration with Git repos and websites

Originally created by @zen on #17655 (Redmine)

For the integration of the Translation Platform with the main website, we originally wanted that:

  • Anyone can suggest.
  • Logged in users can vote on suggestions.
  • Most voted suggestions would appear in the staging website.
  • Reviewers can accept translations.
  • Accepted translations appear in the main website automatically.

Current state: Weblate workflow vs Git repository vs website rendering

The following table attempts to address the following questions:

  • Which of the possible states of strings (Needs editing, Waiting for review, Approved) gets committed to the repo?
  • Which of these states gets committed but is marked as fuzzy?
  • Which of these states get rendered in the main website?
  • Which of these states get rendered in the staging website?

The Weblate workflow did not change since we first installed (3.5.1) it up to the latest version (4.12.2 nowadays).

Using the info from Weblate Doc and comparing strings in Weblate, Tails Git repo and the main website, this is the current state of affairs:

Weblate state Committed to Git? Marked as fuzzy? Rendered in the main website? Rendered in staging website?
Suggestions ❌ (doesn't apply) ❌ ✅
Untranslated ❌ (doesn't apply) ❌ ❌
Needs editing /Fuzzy ✅ ✅ ❌ ❌
Waiting for review / Translated ✅ ❌ ✅ ✅ (if not committed to git)
Approved ✅ ❌ ✅ ✅ (if not committed to git already)

Analysis of the current state

  • There's a difference between what Weblate and what Tails understand as "reviewed strings":
    • For Weblate, a string "Waiting for review" is a valid translation:
      • "It is stored in the file as a valid translation" and, because of that, it gets rendered in our main website (as well as in the staging website, unless there are suggestions for it).
      • The difference between "Waiting for review" and "Approved" only lives in the Weblate database.
    • For Tails, an unreviewed string needs "to be accepted by reviewers to go live onto the main Tails website".
  • Right now:
    • We're only using 3 "kinds" of roles in Weblate related to actually translating (not counting other functionalities as managing glossaries, etc): Guests, Users and (global and per-language) Reviewers.
    • Guests and Users can only suggest, and suggestions determine what gets rendered on the staging website.
    • Reviewers can accept suggestions to turn them into any of the other states described in the table above.
  • As emmapeel wrote:
    • This workflow probably wasn't in place when Weblate started to be evaluated.
    • We currently use a bad mapping from Weblate workflow features to Tails translation workflow.
    • The current setup causes several usability problems.

Assumptions made by our current integration code

Weblate → Canonical:

  1. Assumption: All changes made via Weblate web interface that are committed to the Weblate Git repo will eventually be merged into the Canonical repo (unless they conflict with changes made to Canonical in the meantime).

    Consequence: Canonical gets all translation content and state changes made in the Weblate interface (not counting conflicts and suggestions): "Needs edit" translations are committed as fuzzy (and thus invalidated, rendering the main language instead), and "Needs review" and "Approved" translations are committed as "valid" translations.

  2. Assumption: Weblate and our custom code only change .po files in the Weblate and Integration repos.

    Consequence: Pushing changes to Canonical fails if anything other than .po files is changed.

  3. Assumption: When there are conflicts, changes from Canonical have precedence over changes from Weblate.

    Consequence: Conflicting translations made through Weblate are lost.

Canonical → Weblate:

  1. Assumption: The update of the translations in the Weblate backend is not made automatically by Weblate (i.e. AUTO_UPDATE is off, so Weblate-initiated Git pulls and component discovery are never triggered automatically).

    Consequences:

    • We need a custom mechanism to update the Weblate backend with changes from Canonical.
    • Such mechanism is responsible for maintaining integrity between the Weblate backend and repository, that is, to ensure that when it finishes all translations content and state are the same in both places.

  2. Assumption: Source string changes are not automatically reflected in the Canonical repo for languages that are not activated in the main website. (The .po files for languages that are activated in the main website are automatically updated by the production Ikiwiki.)

    Consequence: Our custom code needs to propagate relevant changes to source strings to the languages that are not activated in the main website, but that are activated in Weblate and the staging website.

  3. Assumption: Changes in any source string or translation in a component cause the whole component to be updated in the Weblate backend.

    Consequence: If the state of a translation in the Weblate backend differs from its state in the .po file (for example if we implement only committing of "Approved" strings), then a change in another translation in the same component may cause data loss in the Weblate backend.

Analysis of the proposals

In terms of UX, @emmapeel proposes:

  • Guests and unprivileged Users can only suggest, and suggestions only live in Weblate.
  • Translators (which are "approved" Users, added to the Translators group) can determine what gets rendered in the staging website.
  • Reviewers can determine what is accepted and included in the main website.

Implementation-wise, because there's no easy way to change how Weblate behaves, we have to face the problem that "Waiting for review" strings are treated as "valid" translations, thus always get committed to the Weblate repository without the fuzzy tag (see the table above).

From the discussion below in this issue, i understand that @emmapeel's idea is to either:

  1. Change the logic of our integration scripts and integration repository(ies) in a way that only "Approved" strings are propagated from Weblate to the Tails canonical repository, or
  2. Change Weblate behavior upstream, which would mean convince Weblate devs that only strings in "Approved" state should be committed to the repository (effectively changing the first and second columns in the table above).

In any of the above cases:

  • The new Translator role would be able to add strings directly to the "Waiting for review" state.
  • Such strings would be rendered in the staging website only.
  • Only Reviewers would be able to turn such strings into "Approved" state.

Proposal 1: Replace merging from Weblate by importing "Approved" strings

  • Replace the "Merge Weblate Changes" step by an "Integrate Approved Strings" step.
  • Update the "Update Weblate Components" step to account for the fact that the Weblate repo will never converge with the Canonical repo.
  • Change Weblate roles/permissions so that Translators can add strings to "Needs review".
  • Change the generation of the Staging website to use strings in "Needs review" state instead of suggestions.

Pros: improved UX, satisfies security policy.

Cons: high cost of implementation, needs changes in many places of our integration code.

Proposal 2: Foster the implementation of a write-policy in Weblate

  • Wait or help Weblate to implement a write-policy.
  • Change Weblate config so only "Approved" strings get committed to the Weblate repository.
  • Profit.

Pros: improved UX, satisfies security policy, benefits more Weblate users.

Cons: needs knowledge of Weblate codebase, needs acceptance by Weblate, needs currently unknown amount of resources.

Proposal 3: Stick with the same workflow, improve communication with Reviewers

Train Reviewers to:

  • Do their own translations by means of suggestions.
  • Periodically check for new suggestions.
  • Do not use the "Needs review" state: every accepted suggestion must be reviewed by the time of acceptance and immediately marked and saved as "Approved".

Pros: cheap solution.

Cons: bad UX.

Next steps

Preparation and evaluation:

  • Create a table comparing weblate states, storage in file in Git repo, fuzziness, and rendering in the main and staging websites.
  • Compare the current state with emmapeel's proposal
  • List what would need to be changed to implement the proposal
  • Ask for review, confirmation and input from folks, maybe iterate to improve the proposal
  • Write a proposal that only changes workflow and permissions
  • Map assumptions that our code/design relies on
  • Maybe: Prototype something that commits only "Approved" strings to Git
  • Decide next steps
Edited by Zen Fu
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information