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).

[zenmonkeykstop]

Given that this is not likely to be a frequent occurrence and some level of developer attention would likely be required anyway, we could probably make do with the current hotfix release process and avoid the -stable split. I'm thinking a scenario like:

• LL raises the bat-signal for a language ZZ
• FPF compares string catalogues in the main(develop) and latest release branch, and adds any strings in release but missing in main back to main in a file that is picked up by Babel/whatever node equiv is. (this could be automated and done preemptively at the end of any release cycle)
• FPF adds ZZ in Weblate, LL notifies translators/reviewers
• Weblate's repo now has all strings in the release branch, via the stringdiff file above. Translation for ZZ proceeds.
• Once translation is complete, FPF backports string changes to the release branch, enables ZZ in the server app, and cuts/ships a hotfix release.

If we wanted we could still do the package split, but I'd be worried that the testing burden would actually be the same or higher as you'd need to verify that it worked with the current server release.

[cfm]

In proposal review yesterday, we concluded that we're more interested in internationalizing other resources such as our documentation, with freedomofpress/securedrop-info#19 as a test case. But @zenmonkeykstop and I will refine this proposal to see if we can commit to the "new language is a hotfix" approach without making any process or tooling changes (aka "diffoscope and ship").