translation_platform.mdwn 12.2 KB
Newer Older
1
2
The [[design documentation|contribute/design/translation_platform]]
documents how the production setup works.
3

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

6
[[!toc levels=2]]
Ulrike Uhlig's avatar
Ulrike Uhlig committed
7

sajolida's avatar
sajolida committed
8
9
<a id="maintainers-responsibilities"></a>

10
11
# Responsibilities of the _Translation platform maintainers_

127.0.0.1's avatar
127.0.0.1 committed
12
13
14
15
16
17
18
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.
   
19
Team responsabilities:
127.0.0.1's avatar
127.0.0.1 committed
20
21
22
23
24
   
- 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.
25
- Refine and update the translation workflow.
127.0.0.1's avatar
127.0.0.1 committed
26
27
28

Backend responsibilities:

29
- Maintain and upgrade Weblate.
30
- Maintain and improve the integration with main website.
31
32
33
34
35
36
- 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.

127.0.0.1's avatar
127.0.0.1 committed
37
38
Frontend responsibilities:

39
- Facilitate the process of adding new languages for translation:
127.0.0.1's avatar
127.0.0.1 committed
40
41
42
43
44
  - 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.
45
- Grant reviewer permissions (following our documented process).
127.0.0.1's avatar
127.0.0.1 committed
46
47
48
49
50
- Update documentation for translators.


Ideas:

51
Here we dump ideas that could be useful when defining [[this
intrigeri's avatar
intrigeri committed
52
job|contribute/working_together/roles/translation_platform]]
127.0.0.1's avatar
127.0.0.1 committed
53
as part of [[!tails_ticket 17726]].
sajolida's avatar
sajolida committed
54
55

## In scope
56
57

- Upgrade Weblate to new upstream releases.
sajolida's avatar
sajolida committed
58
59
- Weblate crashes.
- Removing stuff from the Weblate database because the webapp got mad.
intrigeri's avatar
intrigeri committed
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
- 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

## Borderline

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
sajolida's avatar
sajolida committed
80
81
82
83
84
85

## 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
86

87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
<a id="ux"></a>

UX for new translators
======================

[[!tails_ticket 16974]] tracks progress on this front.

Weblate
-------

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](https://translate.tails.boum.org/projects/tails/anonymous_internet/fr/),
    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:
  https://tails.boum.org/contribute/how/translate/" message on the
  Weblate homepage, clicked on that link and then got totally lost.

  Proposal: instead directly point to [[a more focused doc
  page|contribute/how/translate/with_translation_platform]], 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](https://translate.tails.boum.org/accounts/register/).
  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|contribute/how/translate]], 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.
intrigeri's avatar
intrigeri committed
238
  Implemented in [[!tails_gitweb_commit 3317eea94a]].
239
240
241

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

intrigeri's avatar
intrigeri committed
242
  Implemented in [[!tails_gitweb_commit b2a0d9c495]].
243
244
245
246

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

intrigeri's avatar
intrigeri committed
247
  Hopefully fixed in [[!tails_gitweb_commit eb17bf9da4]]
248
249
250
251
252
253
254

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

intrigeri's avatar
intrigeri committed
255
    Hopefully fixed in [[!tails_gitweb_commit 20090cdd20]] and [[!tails_gitweb_commit 77bbbb2c42]].
256
257
258
259

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

intrigeri's avatar
intrigeri committed
260
    Hopefully fixed in [[!tails_gitweb_commit 69702d9faa]].
261

Ulrike Uhlig's avatar
Ulrike Uhlig committed
262
A hybrid approach
263
=================
264

Ulrike Uhlig's avatar
Ulrike Uhlig committed
265
266
267
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
intrigeri's avatar
intrigeri committed
268
system conflicts with installing and maintaining Weblate, a
Ulrike Uhlig's avatar
Ulrike Uhlig committed
269
270
271
272
273
274
275
276
277
278
279
280
281
282
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:
283
284

* Move the database to a separate Docker service.
Ulrike Uhlig's avatar
Ulrike Uhlig committed
285
286
287
288
289
* 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.
290
291
* Set up persistence for the Weblate git repository and configuration.
* Set up persistence and backups for the database service.
Ulrike Uhlig's avatar
Ulrike Uhlig committed
292
293
294
295
296
297
298
299
* 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
300
Weblate directly on the server.