summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorsajolida <sajolida@pimienta.org>2019-09-20 19:49:09 +0000
committersajolida <sajolida@pimienta.org>2019-09-20 19:49:09 +0000
commitbcc550f0ccc38b7fbb232ddc3274c74f595bf181 (patch)
tree5b35b679a3eb872823b11546b60e54ebc83ca481
parent49ca0b1a8533bcea1b0781caf96e196b3b36bc3b (diff)
parentb0efe35963de6209135f90c77b49ff19bd6879ee (diff)
Merge remote-tracking branch 'origin/master'
-rw-r--r--wiki/src/blueprint/translation_platform.mdwn154
1 files changed, 69 insertions, 85 deletions
diff --git a/wiki/src/blueprint/translation_platform.mdwn b/wiki/src/blueprint/translation_platform.mdwn
index 6a8b2b1..c692823 100644
--- a/wiki/src/blueprint/translation_platform.mdwn
+++ b/wiki/src/blueprint/translation_platform.mdwn
@@ -11,8 +11,7 @@ This is the technical design documentation of our setup.
We also provide a dedicated [[documentation for translators on how to use
Weblate|contribute/how/translate/with_Weblate]] to contribute
-translations. (This link will work once [[!tails_ticket 11763]] is
-fixed.)
+translations.
Terms used in this document
===========================
@@ -21,11 +20,62 @@ Terms used in this document
website relies on, in scripts often called "main repository" or "main
Git"
- Production server: the server that hosts our website
-- translate.lizard: the VM that hosts our Weblate web interface, the
+- translate.lizard: the VM that hosts our Weblate webinterface, the
corresponding Git repositories, as well as the staging website.
[Corresponding tickets on Redmine](https://redmine.tails.boum.org/code/projects/tails/issues?query_id=321)
+Choosing a translation web platform
+===================================
+
+MUST
+----
+
+* provide a usable easy web interface
+* be usable from Tor Browser
+* automatic pull from main Git repo
+* provide a common glossary for each language, easy to use and improve
+* allow translators to view, in the correct order, all strings that
+ come from the entire page being translated, both in English and in
+ the target language
+* make it easy to view the translations in context i.e. when translating
+ an entire page, all strings to be translated should only come from
+ this page. translators should be able to view the page in context.
+* provide user roles (admin, reviewer, translator)
+
+SHOULD
+------
+
+* be "privacy sensitive", i.e. be operated by a non-profit
+* allow translators to push translations through Git (so that core
+ developers only have to fetch reviewed translations from there)
+* provide support for Git standard development branches (devel, stable,
+ and testing) but we could also agree upon translation only master
+ through this interface
+* provide checks for inconsistent translations
+* provide feature to write/read comments between translators
+
+MAY
+---
+
+* allow translating topic branches without confusing translators,
+ causing duplicate/premature work, fragmentation or merge conflicts
+ -- e.g. present only new or updated strings in topic branches;
+ see <https://mailman.boum.org/pipermail/tails-l10n/2015-March/002102.html>
+ for details
+* provide a feature to easily see what is new, what needs updating, what are translation priorities
+* provide possibility to set up new languages easily
+* send email notifications
+ - to reviewers whenever new strings have been translated or updated
+ - to translators whenever a resource is updated
+* respect authorship (different committers?)
+* provide statistics about the percentage of translated and fuzzy strings
+* Letting translators report about problems in original strings, e.g.
+ with a "Report a problem in the original English text" link, that
+ e.g. results in an email being sent to -l10n@ or -support-private@.
+ If we don't have that, then [[contribute/how/translate]] MUST
+ document how to report issues in the original English text.
+
Setup of our translation platform & integration with our infrastructure
=======================================================================
@@ -57,7 +107,7 @@ that:
In order to integrate Weblate and the work done by translators into our
process, we have set up this scheme:
-[[!img "lib/design/git_repository_details.svg" link="no"]]
+<img src="git_repository_details.svg" />
Website and Weblate
-------------------
@@ -78,7 +128,9 @@ thus approved translations of all languages enabled on the Weblate
platform, while only part of them are active on the website.
Each PO file corresponds to a single component in Weblate, in order to
-appear in the Weblate interface. For example, the component:
+appear in the Weblate interface.
+
+For example, the component:
wiki/src/support.*.po
@@ -160,7 +212,7 @@ they needed?)
Whenever a contributor modifies a markdown (`*.mdwn`) file, and pushes
to master, the corresponding POT and PO files are updated, that is: the
-translatable English strings within those files are updated. This
+translateable English strings within those files are updated. This
update happens on the production server itself, when [[building the
wiki|contribute/build/website]] for languages that are enabled on the
production website.
@@ -174,8 +226,7 @@ modified English strings in those files, in all languages.
### Step 1: Canonical → Integration
-**Update the integration repository with changes made on the canonical
-repository**
+### Update the integration repository with changes made on the canonical repository
The script fetches from the canonical (remote) repository and tries to
merge changes into the (local) integration repository. The merge
@@ -204,9 +255,9 @@ we've previously defined as a default language. If the actual POT file,
generated on the production server differs from the POT file we've just
created, then every additional language PO file needs to be updated.
-On top of this, if the PO file of the default language (that is, its
-markdown file) have been renamed, moved or deleted, than the PO files of
-additional languages need to follow this step.
+On top of this, if the "defaultlang"s PO file (and its markdown file)
+have been renamed, moved or deleted, than the PO files of additional
+languages need to follow this step.
Finally, the script will test if the new commit has triggered any change,
(XXX: I don't understand what "the new commit" is here, can you please
@@ -215,8 +266,7 @@ please clarify on what this is performed).
### Step 4: Weblate → Integration
-**Integrating the changes made in the canonical Git repository into
-Weblate repository and database**
+### Integrating the changes made in the canonical Git repository into Weblate repository and database
After having merged changes from the canonical Git repository into the
integration Git repository, and integrated changes from Weblate there,
@@ -227,7 +277,7 @@ can try?", who or what tries it when?)
If a fast-forward is not possible then the Canonical <-> Integration
loop has something to do (XXX: What does this mean "something to do"?
-And how do we know it's not possible?) and we try again later to pull.
+and how do we know it's not possible?) and we try again later to pull.
(XXX: What is this triggered by? What does "later" mean in this
context?)
@@ -240,15 +290,14 @@ handled by another script:
There may be other scripts (XXX: like what?), that may update the master
branch of Weblate repo besides our script, that's why the script is
using an own Git remote named "cron" (XXX: is this information
-up-to-date? I cannot find it in the script. If this is a configuration
+up-to-date? I cannot find it in the script. If this is a config
variable, let's make it clear. I also don't understand what this own Git
remote is, where does it come from, is it up-to-date?) to keep track of which commits need to
be scanned (XXX: scanned, really?) for Weblate component changes.
### Step 6: Weblate → Integration
-**Merging changes from Weblate's Git repository into the integration
-repository**
+### Merging changes from Weblate's Git repository into the integration repository
Weblate's Git repository is not bare. Hence we need to pull changes
committed to Weblate's Git repository and merge them into the
@@ -261,14 +310,13 @@ done to PO files manually, via the canonical Git repository.
Again, PO file merges are done on translation units (`msgids`).
-Furthermore, we make sure via the script that Weblate has only modified
+Furtheremore, we make sure via the script that Weblate has only modified
PO files; indeed we automatically reset everything else to the version
that exists in canonical.
### Step 9: Integration → Canonical
-**Pushing from the integration repository to our canonical repository,
-aka "production"**
+### Pushing from the integration repository to our canonical repository, aka "production"
As a last step, a push from the VM hosting Weblate (XXX: to where?) is done, using
the integration repository that has all changes:
@@ -322,7 +370,7 @@ database and applies them to a local clone of Weblate's Git repository,
after having updated the clone with newer data from Weblate's VCS.
[`save-suggestions.py`](https://git-tails.immerda.ch/puppet-tails/tree/files/weblate/scripts/save-suggestions.py)
-After that we run `ikiwiki --refresh` using an dedicated `ikiwiki.setup`
+After that we run ikiwiki --refresh using an dedicated `ikiwiki.setup`
file for the staging website.
None of the changes on this repository clone are fed back anywhere and they
@@ -432,17 +480,6 @@ Currently implemented proposal
suggestion to be accepted as a validated translation?
(At the moment, suggestion voting is disabled.)
-Weblate administration
-======================
-
-- [[Enabling a new language|contribute/l10n_tricks#weblate-administration]]
- Make sure to enable languages only if they are part of our tier-1
- list or discuss the matter on the l10n-mailing list.
-
-- Sysadmin: This documentation currently still lives in
- translate-server.git and should be moved somewhere else.
- [[!tails_ticket 15086]]
-
Weblate installation and maintenance
====================================
@@ -492,56 +529,3 @@ Long-term maintenance plan
This is work in progress. A plan for the future maintenance of our
Weblate instance will be worked on in November 2019 and laid out here
before the end of the year.
-
-Choosing a translation web platform
-===================================
-
-These are the requirements that we have defined for our translation web platform.
-
-MUST
-----
-
-* provide a usable easy web interface
-* be usable from Tor Browser
-* automatic pull from main Git repo
-* provide a common glossary for each language, easy to use and improve
-* allow translators to view, in the correct order, all strings that
- come from the entire page being translated, both in English and in
- the target language
-* make it easy to view the translations in context i.e. when translating
- an entire page, all strings to be translated should only come from
- this page. translators should be able to view the page in context.
-* provide user roles (admin, reviewer, translator)
-
-SHOULD
-------
-
-* be "privacy sensitive", i.e. be operated by a non-profit
-* allow translators to push translations through Git (so that core
- developers only have to fetch reviewed translations from there)
-* provide support for Git standard development branches (devel, stable,
- and testing) but we could also agree upon translation only master
- through this interface
-* provide checks for inconsistent translations
-* provide feature to write/read comments between translators
-
-MAY
----
-
-* allow translating topic branches without confusing translators,
- causing duplicate/premature work, fragmentation or merge conflicts
- -- e.g. present only new or updated strings in topic branches;
- see <https://mailman.boum.org/pipermail/tails-l10n/2015-March/002102.html>
- for details
-* provide a feature to easily see what is new, what needs updating, what are translation priorities
-* provide possibility to set up new languages easily
-* send email notifications
- - to reviewers whenever new strings have been translated or updated
- - to translators whenever a resource is updated
-* respect authorship (different committers?)
-* provide statistics about the percentage of translated and fuzzy strings
-* Letting translators report about problems in original strings, e.g.
- with a "Report a problem in the original English text" link, that
- e.g. results in an email being sent to -l10n@ or -support-private@.
- If we don't have that, then [[contribute/how/translate]] MUST
- document how to report issues in the original English text.