docs: sketch a Weblate workflow for rapid translation releases from a stable branch

[cfm]

Previously

• freedomofpress/securedrop-engineering#93
• Notes from original discussion with Localization Lab

The goal

As @legoktm put it:

MediaWiki used to have a method in which users of stable releases (every ~6 months) could get localization updates once they were merged into main (https://www.mediawiki.org/w/index.php?oldid=6317009) [...].

If we wanted do that, we could pretty easily split the message catalogs into a separate Debian package that can be released out of band from a normal SD release. We just have to worry about the disconnect between messages that change between stable and develop branches.

Status quo

Translation

A Weblate "component" for each GitHub repository tracks its main branch. Translations come back as pull requests into the main branch for review.

Weblate component tracks...	GitHub repository	Branch
securedrop/securedrop	securedrop	develop
securedrop/securedrop-app	securedrop-client	main

Packaging

A release branch release/X.Y.Z is tagged as X.Y.Z, from which the securedrop-app-code and securedrop-app packages are built.

Other assumptions

• Our Debian packages are reproducible.
• Translation assets are either (a) human-readable (i18next) or (b) verified round-trip (gettext).
• Localization Lab reviewers are trusted and responsible for the correctness and safety of translation text.
• SecureDrop maintainers are responsible for the safety of translation markup, which Weblate helps enforce.
• SecureDrop server and app deployments update within 24 hours to the latest packages we publish.

Proposed changes

The big idea

1. Break out translation files into their own package, separate from the application package.
2. Break out translation from the latest tag into its own Weblate component, separate from the main branch and component.
3. Support releasing translation packages with minimal, automated QA, decoupled from the regular SecureDrop release and QA processs.

Translation

Introduce a component+branch pair like stable from the latest tag X.Y.Z (changes in bold):

Weblate component tracks...	GitHub repository	Branch
securedrop/securedrop	securedrop	develop
securedrop/securedrop-stable	securedrop	stable
securedrop/securedrop-app	securedrop-client	main
securedrop/securedrop-app-stable	securedrop-client	stable

Weblate supports translating multiple branches from the same repository. This means that:

1. Translators working on a -stable component will see only source strings currently on its stable branch.
2. Translations made on a -stable component will be pushed back to its stable branch (via pull request). Both CI and manual review will enforce that only localization paths have changed.
3. However, translations made on a -stable component will nonetheless be propagated within Weblate to the main components, so that they can be reused on main branches for future releases. (We'll want to test this behavior on our sandbox Weblate instance to see how it works in practice.)

Packaging

1. Separate translation files into separate packages, e.g.:

Repository	Main package	Translation package
securedrop	securedrop-app-code	securedrop-app-translations
securedrop-client	securedrop-app	securedrop-app-translations

(The naming collision is unfortunate. To discuss.)

2. As noted above: Enforce in CI that the stable branch may diverge from the latest tag X.Y.Z only at localization paths.

3. A -translations package may be built and released from the stable branch at any time. It is versioned based on the latest tag, where T is the translation-specific monotonic release counter for X.Y.Z starting from T=0, either:

   1. X.Y.Z.T (extend Debian upstream-version field) or
   2. X.Y.Z-T (overload Debian debian-revision field).