From 36bc188afda0dc3b9c32c011e9e63eab6672e013 Mon Sep 17 00:00:00 2001 From: Gonzalo Bulnes Guilpain Date: Sun, 31 Jan 2021 01:45:35 +1100 Subject: [PATCH] fixup! Spike reorganization - add Weblate glossary --- docs/development/translations.rst | 46 +++++++++++++++++++++++-------- 1 file changed, 35 insertions(+), 11 deletions(-) diff --git a/docs/development/translations.rst b/docs/development/translations.rst index 63cb5e65e..608bee60b 100644 --- a/docs/development/translations.rst +++ b/docs/development/translations.rst @@ -32,13 +32,13 @@ Our Weblate instance only contains one project, SecureDrop, which has two transl - :ref:`Learn more about translating phrases with placeholders ` - :ref:`Learn more about translating phrases with HTML code ` -Once a string is translated, it must be approved by a _reviewer_ before being accepted into SecureDrop. +Once a string is translated, it must be approved by a :ref:`reviewer ` before being accepted into SecureDrop. - :ref:`Why do strings need to be reviewed? ` - :ref:`How to approve a translated string ` - :ref:`How can I become a reviewer? ` -Approved strings can only be modified by _reviewers_. However, translators can still suggest modifications and make comments if they notice something wrong. +Approved strings can only be modified by :ref:`reviewers `. However, translators can still suggest modifications and make comments if they notice something wrong. SecureDrop translations are a collaborative endeavour! - :ref:`Suggesting changes to source strings ` @@ -114,9 +114,9 @@ How to translate a phrase on Weblate #. :ref:`Select a language `. #. Read the translatable string in the text area labelled **Source**. #. Review the suggested translations if there are any in the **Glossary** sidebar. -#. Review the contextual information about the source string in the **Source information** sidebar, like its location in our source code. -#. If a screenshot of the SecureDrop user interface is vailable, read the source string in context. -#. Input your translation in the **Translation** test area near the source string. +#. Review the contextual information about the :ref:`source string ` in the **Source information** sidebar, like its location in our source code. +#. If a screenshot of the SecureDrop user interface is vailable, read the *source string* in context. +#. Input your translation in the **Translation** test area near the *source string*. #. Click **Save**. The next untranslated string will apear automatically. |Weblate translate screenshot| @@ -165,6 +165,30 @@ How to approve a translated string Reference --------- +Weblate glossary +^^^^^^^^^^^^^^^^ + +.. _weblate_glossary_reviewer: + +Reviewer +"""""""" + +Reviewers are people who are trusted to review and accept new translations into SecureDrop. + +- :ref:`Why do strings need to be reviewed? ` +- :ref:`How can I become a reviewer? ` + +.. _weblate_glossary_source_string: + +Source string +""""""""""""" + +On Weblate, the phrases being translated are called *source string*. (No relation with the terms *source* and *journalist* in SecureDrop.) + +Source strings are English phrases and are automatically extracted from SecureDrop's code. Because of that, they can only be modified by developers outside Weblate. + +- :ref:`Suggesting changes to source strings ` + Language glossaries on Weblate ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -184,7 +208,7 @@ If a term is missing from the glossary for the language you're translating into, Technical glossaries ^^^^^^^^^^^^^^^^^^^^ -Translating SecureDrop requires understanding some complicated security terminology, involving cryptography, networking, and threat models. If you are unfamiliar with terms you encounter in source strings, consult one of the following glossaries, or :ref:`ask for help `! +Translating SecureDrop requires understanding some complicated security terminology, involving cryptography, networking, and threat models. If you are unfamiliar with terms you encounter in :ref:`source strings `, consult one of the following glossaries, or :ref:`ask for help `! - The :doc:`SecureDrop glossary <../glossary>` explains terms specific to SecureDrop. @@ -264,7 +288,7 @@ And it would be **incorrect** to translate the placeholder like so:: Translating phrases with HTML code ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Some source strings represent HTML that will be presented in the +Some :ref:`source strings ` represent HTML that will be presented in the SecureDrop web interface. HTML elements (embraced by in ``<``, ``>``, example: ````) @@ -336,7 +360,7 @@ forum`_. Suggesting changes to source strings ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you notice errors in our source strings, or catch us using English +If you notice errors in our :ref:`source strings `, or catch us using English idioms that are hard to translate, please add comments letting us know. At the beginning of every translation cycle in our release schedule, we have a few days for incorporating your feedback, and very @@ -370,7 +394,7 @@ Using language glossaries on Weblate ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Weblate contains an internal glossary for each language, to which -we can add suggested translations. If a source string contains terms +we can add suggested translations. If a :ref:`source string ` contains terms from this glossary, the glossary entries will be displayed in a box on the right side of the translation page. @@ -378,7 +402,7 @@ the right side of the translation page. - :ref:`How to translate a phrase on Weblate ` -If you find that a source string contains terms from the +If you find that a *source string* contains terms from the :doc:`SecureDrop glossary <../glossary>` or the `EFF Surveillance Self-Defense glossary`_, but the glossary sidebar says ``No related strings found in the glossary.``, we'd really appreciate it if you @@ -393,7 +417,7 @@ with. Why do strings need to be reviewed? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Sources, journalists and admins use localized versions of SecureDrop. A malicious actor could attempt to modify their behavior by creating misleading translations. In order to mitigate that risk, all translations must be reviewed and accepted by designated *reviewers* before they become part of SecureDrop. +Sources, journalists and admins use localized versions of SecureDrop. A malicious actor could attempt to modify their behavior by creating misleading translations. In order to mitigate that risk, all translations must be reviewed and accepted by designated :ref:`reviewers ` before they become part of SecureDrop. .. _how_to_become_a_reviewer: