The design documentation documents how the production setup works.

This page is about ideas that are not implemented (yet?).

Responsibilities of the Translation platform maintainers

First draft:

The maintainers of the translation platform have to make sure that the Tails translators can translate our website easily, while not compromising the safety of the rest of the Tails ecosystem.

Team responsabilities:

  • Manage the budget for this team/job.
  • Keep track of upcoming big changes (e.g. Weblate dropping support for the database we're using, or gaining extra non-trivial dependencies) and plan the work we'll have to do to adjust.
  • Refine and update the translation workflow.

Backend responsibilities:

  • Maintain and upgrade Weblate.
  • Maintain and improve the integration with main website.
  • Maintain and improve the generation of the staging website.
  • Maintain technical documentation up-to-date.
  • Monitor error messages (Weblate, server, integrations).
  • Implement backend changes needed for the translation workflow.
  • Fix crashes in the whole setup.

Frontend responsibilities:

  • Facilitate the process of adding new languages for translation:
    • Induction of new language teams if no Tails translator takes the lead.
    • Final, more technical review when new languages are deemed ready for the main website.
  • Hear feedback from translators, facilitate these discussions until they reach a conclusion, and report to upstream when needed.
  • Grant reviewer permissions (following our documented process).
  • Update documentation for translators.


Here we dump ideas that could be useful when defining this job as part of #17726.

In scope

  • Upgrade Weblate to new upstream releases.
  • Weblate crashes.
  • Removing stuff from the Weblate database because the webapp got mad.
  • Analyze error email send by cron and figure out what to do about them: ignore? fix the immediate problem (possibly repeatedly)? address the deeper root cause?
  • Manage the budget for this team/job; for details, see Handbook/Timesheets_and_budget_management.mdwn in summit.git
  • Keep track of upcoming big changes (e.g. Weblate dropping support for the database we're using, or gaining extra non-trivial dependencies) and plan the work we'll have to do to adjust


The initial draft job description explicitly excluded social/community work. Hmm… do we want to change this?

Who's responsible for the following tasks?

  • Grant reviewer permissions (following our documented process)
  • Hear feedback from translators, facilitate these discussions until they reach a conclusion

Out of scope

  • Work that requires sysadmin privileges or belongs to "sysadmins provide an OS with the required packages and system services", e.g. MariaDB is crashing

UX for new translators

#16974 tracks progress on this front.


This list of problems was built thanks to usability testing at MozFest 2019. The "users" referred to below are all people who tried to use Weblate for the first time. All these users were rather technical. They were using a broad variety of devices (about half smartphones and half laptops) and browsers (a couple Tor Browser, some Firefox, some the default browser of their mobile OS).

The initial set of hypotheses and proposals below are intrigeri's.

  • The Suggested translations (10) link in the top bar is confusing: Several users thought it was about suggestions of translations for specific strings, that should be reviewed. It took them a while to realize that this was not the case. But then it was still not clear what this link is about, nor how to actually list the translation suggestions that need to be reviewed.

  • Nobody understood what the numbers next to the links in the top bar meant. After asking them what they thought it could be, some ventured hypothesis: total number of strings, number of untranslated strings, number of languages.

    And regarding the Suggested translations (10) link, several users assumed that 10 was the number of translation suggestions that should be reviewed, which is incorrect.

  • Several users found it hard to find what needs work and what they should focus on first. Some specific issues in this area:

    • Nobody clicked on the "core pages" link.

      Hypothesis: the fact that link is in the middle of 8 other links may not help.

      Proposal: remove the "anonymous internet", "first steps", "Install & upgrade", and "persistence" links from the top bar. It's not clear to me whether these component lists are maintained (e.g. lots of the install and upgrade stuff has moved in the last year; are the new components listed there?).

    • One user wondered what to translate first once core pages are done.

    • On the page that gives an overview of a component for a given language, such as this one, there's a Translate button, even when the component is fully translated already. One user found it confusing to click Translate and land on a string that is already translated.

  • One user would have liked to be able to give feedback on suggested translations, e.g. via a comment, even though they were not a reviewer and thus could not approve the suggestion.

  • All users but one found the Register button without needing help. The other user, after reading the prominent "Please get in touch to start translating Tails website:" message on the Weblate homepage, clicked on that link and then got totally lost.

    Proposal: instead directly point to a more focused doc page, remove "Please get in touch", and rephrase this message.

  • Several users did not manage to register an account because Weblate told them "too many registration attempts" on their first attempt. Some were using Tor, some their mobile data, some the shared Wi-Fi provided by the event.

    Hypothesis: the root cause of this problem looks like a sysadmin or Weblate bug rather than a UX design problem. Maybe Weblate has a rate limiting mechanism to protect against too many account registration attempts in a given time span, regardless of what device/IP is used?

  • During the account registration process, one user commented that the arithmetic CAPTCHA they were facing (7×8) felt too hard. They managed to solve it eventually.

    Hypothesis: even if the user can fallback to using a calculator, having to do so can be damaging for their self-confidence and desire to continue. The message we're sending here is even worse than that, given the skills required to solve this CAPTCHA are entirely foreign to the skills one needs to translate Tails.

    Proposal: whatever blocks spammers is good enough. Can we configure the difficulty of this CAPTCHA? For example, maybe basic addition and subtraction between numbers up to 5 might be an OK trade-off.

  • One user found it hard to discover the hamburger menu on a smartphone.

  • A UX designer who attended the session gave feedback and recommendations about the account registration page. What follows was freely transcribed and interpreted by intrigeri from very rough notes and memory.

    It's all about the first sentence ("By registering you agree to use your name and email in version control system commits and provide your contribution under license defined by each translated project"), which has several problems:

    • It uses technical jargon ("version control system commits") and vague terms and conditions ("under license defined by each translated project", that is?) ⇒ it may not be clear to the user what they are agreeing with exactly. That's not a good way to ask if they consent.

    • It's outside of the main form so it's easy to skip. If we really need users to explicitly agree with these conditions, then this should be a checkbox right on top of the Register button.

    • It does not encourage new translators to continue.

      Recommendation: add an introduction text that briefly explains why registering is useful, thanks the visitor, and encourages them to continue.

Documentation for translators

This is feedback and recommendations from a UX designer about our documentation for translators, freely transcribed and interpreted by intrigeri from rough notes. Proposals are intrigeri's, recommendations are this UX designer's.

  • The list of teams makes the whole page longer than it could be. It's not clear if the list of teams is up-to-date: it does not match the languages that are enabled in Weblate.

    Proposal: ask on -l10n@ what these pages are still useful for in the Weblate era.

  • It's not clear what translators should do with the information found in the "Tier-1 languages" section.

  • A new translator first needs to skip the "For native English speakers" section, that presumably is of little interest to the vast majority of folks who landed on this page.

    Recommendation: move this section further down the page. Implemented in 3317eea94a.

  • To be more encouraging, we should start by thanking new translators.

    Implemented in b2a0d9c495.

  • The page lacks structure which makes it harder to find the information a new translator needs.

    Hopefully fixed in eb17bf9da4

  • The "Translate this website" section has a number of problems:

    • It's long and it's hard to find the link most readers will need, i.e. "on the translation platform", because there are 3 links in the paragraph where it lives.

      Hopefully fixed in 20090cdd20 and 77bbbb2c42.

    • It contains obsolete information: "you need to get into contact with a language team if you want to participate".

      Hopefully fixed in 69702d9faa.

A hybrid approach

The Tails infrastructure uses Puppet to make it easier to enforce and replicate system configuration, and usually relies on Debian packages to ensure stability of the system. But the effort to maintain a stable system conflicts with installing and maintaining Weblate, a Python web application, which requires using up-to-date versions of Weblate itself and of its dependencies.

Having that in mind, and taking into account that we already started using Docker to replicate the translation server environment to experiment with upgrading and running an up-to-date version of Weblate, it can be a good trade-off to use Puppet to provide an environment to run Docker, and to use a Docker container to actually run an up-to-date Weblate installation.

From the present state of the Docker image, which currently uses (slightly modified/updated) Puppet code to configure the environment and then sets up Weblate, the following steps could be taken to achieve a new service configuration as described above:

  • Move the database to a separate Docker service.
  • Remove all Puppet code from the Docker image: inherit from the simplest possible Docker image and setup a Weblate Docker image with all needed dependencies.
  • Modify the Puppet code to account for setting up an environment that has Docker installed and that runs the Weblate Docker image.
  • Set up persistence for the Weblate git repository and configuration.
  • Set up persistence and backups for the database service.
  • Update the Puppet code to run tmserver (if/when it's needed -- latest Weblate accounts for basic suggestions using its own database).

After that, we should have a clear separation between stable infrastructure maintenance using Debian+Puppet in one side and up-to-date Weblate application deployment using Docker in the other side. The Docker image would have to be constantly maintained to account for Weblate upgrades, but that should be easier cleaner than deploying Weblate directly on the server.