fixup! Spike reorganization - add Weblate glossary

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 <translating_phrases_with_placeholders>`
 - :ref:`Learn more about translating phrases with HTML code <translating_phrases_with_html>`
 
-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 <weblate_glossary_reviewer>` before being accepted into SecureDrop.
 
 - :ref:`Why do strings need to be reviewed? <why_are_strings_reviewed>`
 - :ref:`How to approve a translated string <how_to_approve_a_translated_string>`
 - :ref:`How can I become a reviewer? <how_to_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 <weblate_glossary_reviewer>`. 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 <suggesting_changes_to_source_strings>`
@@ -114,9 +114,9 @@ How to translate a phrase on Weblate
 #. :ref:`Select a language <how_to_translate_a_language_weblate>`.
 #. 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 <weblate_glossary_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? <why_are_strings_reviewed>`
+- :ref:`How can I become a reviewer? <how_to_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 <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 <getting_help_translations>`!
+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 <weblate_glossary_source_string>`, consult one of the following glossaries, or :ref:`ask for help <getting_help_translations>`!
 
 - 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 <weblate_glossary_source_string>` represent HTML that will be presented in the
 SecureDrop web interface.
 
 HTML elements (embraced by in ``<``, ``>``, example: ``<strong>``)
@@ -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 <weblate_glossary_source_string>`, 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,15 +394,15 @@ 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 <weblate_glossary_source_string>` contains terms
 from this glossary, the glossary entries will be displayed in a box on
 the right side of the translation page.
 
 |Weblate glossary sidebar screenshot|
 
 - :ref:`How to translate a phrase on Weblate <how_to_translate_a_phrase_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 <weblate_glossary_reviewer>` before they become part of SecureDrop.
 
 .. _how_to_become_a_reviewer: