From 767e255d5a1e4ce91eee38a301c54ba480115c5a Mon Sep 17 00:00:00 2001 From: Gonzalo Bulnes Guilpain Date: Thu, 28 Jan 2021 00:23:25 +1100 Subject: [PATCH 1/4] Reorganize docs by Divio's system - create self-sufficient sections where possible - keep the Background Information concise - move as much content as possible to the How-to Guides - order the sections to allow for sequential reading See https://documentation.divio.com --- docs/development/contributing.rst | 4 +- docs/development/l10n.rst | 352 -------------------- docs/development/translations.rst | 364 +++++++++++++++++++++ docs/images/weblate/approved.png | 3 - docs/images/weblate/dashboard.png | 3 - docs/images/weblate/waiting-for-review.png | 3 - docs/index.rst | 2 +- 7 files changed, 367 insertions(+), 364 deletions(-) delete mode 100644 docs/development/l10n.rst create mode 100644 docs/development/translations.rst delete mode 100644 docs/images/weblate/approved.png delete mode 100644 docs/images/weblate/dashboard.png delete mode 100644 docs/images/weblate/waiting-for-review.png diff --git a/docs/development/contributing.rst b/docs/development/contributing.rst index 7e2fee4e9..be3433f2c 100644 --- a/docs/development/contributing.rst +++ b/docs/development/contributing.rst @@ -29,7 +29,7 @@ participate in longer discussions. * To start contributing to the `codebase `__, see our :doc:`contributing guidelines `. * To start making documentation changes, see our :doc:`documentation guidelines `. -* To start translating, see our :doc:`translator guide `. +* To start translating, see our :doc:`translator guide `. * Not sure where to start? You can always ask for advice in the `chat room `__. Programmers @@ -168,7 +168,7 @@ another language, we would welcome your help. SecureDrop is translated using `Weblate `__. We provide a :doc:`detailed -guide ` for translators, and feel free to contact us in the +guide ` for translators, and feel free to contact us in the `translation section of the SecureDrop forum `__ for help. Non-English forum discussions are also welcome. diff --git a/docs/development/l10n.rst b/docs/development/l10n.rst deleted file mode 100644 index 6092b4e4b..000000000 --- a/docs/development/l10n.rst +++ /dev/null @@ -1,352 +0,0 @@ -Translating SecureDrop -====================== - -Putting SecureDrop in context for translation ---------------------------------------------- - -What is SecureDrop? -^^^^^^^^^^^^^^^^^^^ - -SecureDrop is a system that lets people share sensitive information -with investigative journalists anonymously and securely. It's designed -to protect its users with strong cryptography and network -communications that hide locations and activity. For more information: - -* Learn about :doc:`what makes SecureDrop unique <../what_makes_securedrop_unique>`.. -* Watch `The Globe and Mail guide to using SecureDrop `_. -* Read the `Localization Lab "Ask Me Anything" on SecureDrop `_. - - -Who Uses SecureDrop? -^^^^^^^^^^^^^^^^^^^^ - -There are two kinds of SecureDrop users: :doc:`Sources <../source>` -and :doc:`Journalists <../journalist>`. A source is an individual who -wants to communicate securely and anonymously with a -journalist. Sources are not expected to have any technical -background. Journalists using SecureDrop have usually received proper -training and understand the basic workflow of SecureDrop. - -How is SecureDrop translated? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -SecureDrop is translated using the `Weblate`_ platform. Read on to -find out how to use Weblate. - -Using Weblate -------------- - -Registration -^^^^^^^^^^^^ - -The first step is registering an account on our Weblate server by -visiting the `Weblate registration page`_. - -|Weblate registration page screenshot| - -You can choose to register with your email address, or by linking a -GitHub account. If you already have a GitHub account to which you're -usually logged in, that can be easier, but it's not required. - -Register with email -""""""""""""""""""" - -If you want to just register with your email address, you'll use the -**Register using email** form on the left side of the registration -page. - -Fill the form and click **Register**, then check your email for a -message from **weblate@securedrop.org** with the subject **[Weblate] -Your registration on Weblate**. That message will contain a -confirmation link. Clicking that link will complete your registration -and redirect you to the `Weblate dashboard`_. - -Register with GitHub -"""""""""""""""""""" - -To register with your GitHub account, click on the GitHub icon on the -right, under **Third party registration**. This should take you to a -page on https://github.com asking you to authorize the SecureDrop -Weblate server to ask GitHub to authenticate you. (If you're not -already logged in to GitHub, you'll be asked to do that first.) The -authorization request looks like this: - -|GitHub authorization page screenshot| - -Click the green **Authorize freedomofpress** button, and you will be -redirected to the `Weblate dashboard`_. - -Choosing your preferred languages -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can contribute to any language, but Weblate has some conveniences -to make it easier to work with your preferred languages. You can -manage those from the `Weblate dashboard`_: - -|Weblate dashboard screenshot| - -Click the **Manage your languages** button. - -|Weblate manage languages screenshot| - -In each selection box, simply click on the languages you would like to -translate. When you're done, click the **Save** button at the bottom -of the page. - -The SecureDrop translation project -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Weblate supports multiple projects. Our instance only contains one, -SecureDrop, which has two translation components: the main SecureDrop -web application (labeled "SecureDrop"), and the translations for the -desktop icons of the admin and journalist workstations used by news -organizations (labeled "desktop"). - -On the dashboard you will find links to both sets of translations. You -can also drill down to them via the **Projects** menu in the top -navigation bar. - -|Weblate project page screenshot| - -If you click on a component, you'll arrive at the list of languages into which it's translated: - -|Weblate translations screenshot| - -To start translating a language, click the **Translate** button at the far right of its row. - -Translating a phrase -^^^^^^^^^^^^^^^^^^^^ - -Each translatable string is shown in the text area labeled -**Source**. You can translate it right below in the **Translation** -text area. When you are done, click **Save** and the next untranslated -string will appear. - -|Weblate translate screenshot| - -On the right of the page you can find helpful information about the -source string. If the language glossary contains terms from the source -string, their suggested translations will appear in the **Glossary** -sidebar. In the **Source information** sidebar, you'll find contextual -information about the source string, like its location in our source -code. If a screenshot showing the string in context in the SecureDrop -user interface is available, that might be linked here as well. - - -Placeholders ------------- - -Source strings may contain placeholder text in curly braces, for -example ``{count}``. These represent variable content (like a -username, as in the example below), and must be left unmodified, but -they can be moved around in a string. For instance:: - - Edit user {user} - -might be displayed to the user as:: - - Edit user Jean-Claude - -The French translated string should look like:: - - Modifier l'utilisateur {user} - -And it would be **incorrect** to translate the placeholder like so:: - - Modifier l'utilisateur {utilisateur} - -HTML content -^^^^^^^^^^^^ - -Some source strings represent HTML that will be presented in the -SecureDrop web interface. - -HTML elements (embraced by in ``<``, ``>``, example: ````) -can contain multiple so-called *attributes*. - -The text of the two attributes called ``alt`` and ``title`` -should be translated. The text of the other attributes should not -be translated. - -Attribute ``alt`` -""""""""""""""""" - -Image elements (````) in HTML place a picture on the -page. Because people with visual impairments rely on a special note -on the image element -- the ``alt`` attribute -- to describe the image, -it is necessary to translate those. Here's an example that contains an -image with both an ``alt`` attribute *and* a placeholder:: - - shield icon - -As explained above, the placeholder ``{icon}`` in the ``src`` -attribute of the ```` element should not be translated. The -``alt`` attribute text (``"shield icon"``) should be. The correctly -translated HTML in Portuguese would be:: - - ícone do escudo - -Attribute ``title`` -""""""""""""""""""" - -Links (````) and abbreviations (````) sometimes rely on -an additional ``title`` attribute. The content of that attribute is -usually shown when placing a cursor over the link or abbreviation. -:: - - Learn how to install it - -It is necessary to translate the contents of any ``title`` attribute. -The correctly translated HTML in Spanish would be:: - - Aprenda cómo instalarlo - -As explained above, the text content ``recommend-tor`` of the ``id`` -attribute in the ```` element should not be translated. Neither -should the ``{url}`` placeholder of ``href`` attribute. Only the text -content of the ``title`` attribute (``"How to install Tor Browser"``) -should be translated. - -Other attributes -"""""""""""""""" - -No attribute other than ``alt`` and ``title`` should be translated. - -In particular, please make sure the attributes ``class``, ``id``, -``height``, ``href``, ``rel``, ``src`` and ``width`` -are never translated. - -Reviews -------- - -Translated strings must be approved by a reviewer before being -accepted into SecureDrop. This is to make sure the source or -journalist will not be confused by an incorrect translation. - -Anyone can contribute translations, just like anyone can edit -Wikipedia. However the right to review translations is only extended -to trusted translators. You can ask to become a reviewer for a -language by posting a message in the `translation category of the -SecureDrop forum`_. - -A reviewer sees a **Review state** section below the source string, -including the ``Waiting for review`` and ``Approved`` radio buttons. -All source strings are initially set to ``Waiting for review``. - -|Waiting for review screenshot| - -When the translation is deemed correct, the reviewer should change it to -``Approved``. - -|Approved screenshot| - -Once a translation has been approved, only reviewers can modify -it. Translators can still suggest modifications or make comments if -they notice something wrong. - -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 ask in the -`translation category of the SecureDrop forum`_. - -- The SecureDrop :doc:`glossary <../glossary>` explains terms specific - to SecureDrop. -- The `EFF Surveillance Self-Defense glossary`_ explains many general - security concepts. - -Weblate Glossary -^^^^^^^^^^^^^^^^ - -Weblate also contains an internal glossary for each language, to which -we can add suggested translations. If a 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| - -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 -could add those terms to the glossary of the language you're working -with. Simply fill out the **Source** and **Translation** fields in the -sidebar under **Add new word to glossary**, then click the **Add** -button. - -You can see the full glossary for a language by clicking the edit icon -at the top right of the glossary sidebar. The glossary page contains -all the terms that have been translated for the language: - -|Weblate glossary list screenshot| - -Getting Help ------------- - -Should you need help, you can do one of the following: - -* Post a message in the `translation category of the SecureDrop forum`_ -* Chat in the `SecureDrop instant messaging channel`_ -* Read the `Weblate documentation`_ - -Collaboration Guidelines ------------------------- - -Adding new languages -^^^^^^^^^^^^^^^^^^^^ - -We love seeing SecureDrop translated into new languages. Just ask us -to add yours by posting in the `translation category of the SecureDrop -forum`_. - -Suggesting changes to source strings -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you notice errors in our 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 -much appreciate it. - -Changing an existing translation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you think a translation can be improved, please don't run roughshod -over another translator's work. Make a suggestion or comment first, to -allow discussion before saving your changes. - -Exceptions to this policy would be: - -- Obvious errors in spelling, grammar, or punctuation. - -- A string in our interface that is supposed to match another - project. For example, we include instructions for adjusting Tor - Browser settings, so if our wording is out of date, it has to be - corrected to reduce confusion for people using SecureDrop. - -In those cases, please feel free to correct the existing translation. - -.. _`Weblate`: https://weblate.org/ -.. _`SecureDrop Weblate instance`: https://weblate.securedrop.org/ -.. _`Weblate registration page`: https://weblate.securedrop.org/accounts/register/ -.. _`Weblate dashboard`: https://weblate.securedrop.org/ -.. _`translation category of the SecureDrop forum`: https://forum.securedrop.org/c/translations -.. _`SecureDrop instant messaging channel`: https://gitter.im/freedomofpress/securedrop -.. _`Weblate documentation`: https://docs.weblate.org/ -.. _`EFF Surveillance Self-Defense glossary`: https://ssd.eff.org/en/glossary/ - - -.. |Weblate registration page screenshot| image:: ../images/weblate/registration.png -.. |GitHub authorization page screenshot| image:: ../images/weblate/github-authorization.png -.. |Weblate dashboard screenshot| image:: ../images/weblate/dashboard.png -.. |Weblate manage languages screenshot| image:: ../images/weblate/manage-languages.png -.. |Weblate project page screenshot| image:: ../images/weblate/project.png -.. |Weblate translations screenshot| image:: ../images/weblate/translations.png -.. |Weblate translate screenshot| image:: ../images/weblate/translate.png -.. |Weblate glossary sidebar screenshot| image:: ../images/weblate/glossary-sidebar.png -.. |Weblate glossary list screenshot| image:: ../images/weblate/glossary-list.png -.. |Waiting for review screenshot| image:: ../images/weblate/waiting-for-review.png -.. |Approved screenshot| image:: ../images/weblate/approved.png diff --git a/docs/development/translations.rst b/docs/development/translations.rst new file mode 100644 index 000000000..0f72b8bca --- /dev/null +++ b/docs/development/translations.rst @@ -0,0 +1,364 @@ +Translations +============ + +Quick Start Guide +----------------- + +SecureDrop is a system that lets people share sensitive information +with investigative journalists anonymously and securely. +Learn :ref:`more about SecureDrop `. + +SecureDrop is written in English and translated into multiple +other languages. Translations are managed using **Weblate**, +a web platform that enables collaborative translation projects. + +.. _get_started_using_weblate: + +Get started using Weblate +^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can choose to :ref:`register on Weblate ` +with your email address, or by linking a GitHub account. + +You can contribute to any language, and Weblate has some conveniences +to make it easier to work with your preferred languages. +Learn :ref:`how to choose your preferred languages on Weblate `. + +Our Weblate instance only contains one project, SecureDrop, which has +two translation components: the main SecureDrop web application (labeled +"SecureDrop"), and the translations for the desktop icons of the admin +and journalist workstations used by news organizations (labeled "desktop"). + +|Weblate project page screenshot| + +Once a string is translated, it must be approved by a :ref:`reviewer ` +before being accepted into SecureDrop. + +Approved strings can only be modified by reviewers. +However, translators can still suggest modifications and make comments +if they notice something wrong. +SecureDrop translations are a collaborative endeavour! + +Learn :ref:`how to translate SecureDrop using Weblate `. + +.. _getting_help_translations: + +Getting help +^^^^^^^^^^^^ + +Should you need help, you can do one of the following: + +* Post a message in the `translation category of the SecureDrop forum`_ +* Chat in the `SecureDrop instant messaging channel`_ +* Read the `Weblate documentation`_ + +Background Information +---------------------- + +.. _what_is_securedrop: + +What is SecureDrop? +^^^^^^^^^^^^^^^^^^^ + +SecureDrop is a system that lets people share sensitive information +with investigative journalists anonymously and securely. It's designed +to protect its users with strong cryptography and network +communications that hide locations and activity. For more information: + +* Learn about :doc:`what makes SecureDrop unique <../what_makes_securedrop_unique>` +* Watch `The Globe and Mail guide to using SecureDrop `_ +* Read the `Localization Lab "Ask Me Anything" on SecureDrop `_ + +.. _who_uses_securedrop: + +Who uses SecureDrop? +^^^^^^^^^^^^^^^^^^^^ + +There are two kinds of SecureDrop users: :doc:`Sources <../source>` +and :doc:`Journalists <../journalist>`. A source is an individual who +wants to communicate securely and anonymously with a +journalist. Sources are not expected to have any technical +background. Journalists using SecureDrop have usually received proper +training and understand the basic workflow of SecureDrop. + +.. _how_is_securedrop_translated: + +How is SecureDrop translated? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SecureDrop is translated using the **Weblate** platform. :ref:`Get started using Weblate ` + +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 Guides +------------- + +.. _how_to_register_on_weblate_email: + +How to register an account on Weblate using an email address +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Visit the `Weblate registration page`_. +#. Fill the form **Register using email** and click **Register**. +#. Check your email for a message from **weblate@securedrop.org** with the subject **[Weblate] Your registration on Weblate**. +#. That message contains a confirmation link. Click that link to complete your registration. + +.. _how_to_register_on_weblate_github: + +How to register an account on Weblate using a GitHub account +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Visit the `Weblate registration page`_. +#. Click on the GitHub icon, under **Third party registration**. +#. Log into GitHub if necessary. +#. Click the green **Authorize freedomofpress** button. + +The authorization request looks like this: + +|GitHub authorization page screenshot| + +.. _how_to_manage_your_preferred_languages_weblate: + +How to manage your preferred languages on Weblate +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Visit the `Weblate dashboard`_. +#. Click the **Manage your languages** button. +#. Select the languages your want to translate. +#. Click the **Save** button. + +|Weblate manage languages screenshot| + +.. _how_to_translate_a_language_weblate: + +How to translate a language on Weblate +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Visit the `Weblate dashboard`_. +#. Click on the **component** in order to display the list of languages in which it is translated. +#. Click the **Translate** button. +#. :ref:`Start translating `. + +|Weblate translations screenshot| + +.. _how_to_suggest_changes_to_a_source_string: + +How to suggest changes to a source string +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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. We appreciate your feedback very much +and our release schedule includes a few days at the beginning +of every translation cycle for incorporating it. + +.. _how_to_translate_a_phrase_weblate: + +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 :ref:`source string ` in the **Source information** sidebar, like its location in our source code. +#. If a screenshot of the SecureDrop user interface is available, 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 appear automatically. + +|Weblate translate screenshot| + +- :ref:`Learn more about translating phrases with placeholders ` +- :ref:`Learn more about translating phrases with HTML code ` +- :ref:`Learn more about using language glossaries on Weblate ` + +.. _how_to_change_an_existing_translation: + +How to change an existing translation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you think a translation can be improved, please don't run roughshod +over another translator's work. Make a suggestion or comment first, to +allow for discussion before saving your changes. + +Exceptions to this policy would be: + +- Obvious errors in spelling, grammar, or punctuation + +- A string in our interface that is supposed to match another + project. For example, we include instructions for adjusting Tor + Browser settings, so if our wording is out of date, it has to be + corrected to reduce confusion for people using SecureDrop. + +In those cases, please feel free to correct the existing translation. + +.. _how_to_translate_a_phrase_with_placeholders: + +How to translate a phrase with placeholders +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Source strings may contain placeholder text in curly braces, for +example ``{count}``. These represent variable content (like a +username, as in the example below), and must be left unmodified, but +they can be moved around in a string. For instance:: + + Edit user {user} + +might be displayed to the user as:: + + Edit user Jean-Claude + +The French translated string should look like:: + + Modifier l'utilisateur {user} + +And it would be **incorrect** to translate the placeholder like so:: + + Modifier l'utilisateur {utilisateur} + +.. _how_to_translate_a_phrase_with_html_code: + +How to translate a phrase with HTML code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some :ref:`source strings ` represent HTML that will be presented in the +SecureDrop web interface. + +HTML elements (embraced by in ``<``, ``>``, example: ````) +can contain multiple so-called *attributes*. + +The text of the two attributes called ``alt`` and ``title`` +should be translated. The text of the other attributes should not +be translated. + +Attribute ``alt`` +""""""""""""""""" + +Image elements (````) in HTML place a picture on the +page. Because people with visual impairments rely on a special note +on the image element -- the ``alt`` attribute -- to describe the image, +it is necessary to translate those. Here's an example that contains an +image with both an ``alt`` attribute *and* a placeholder:: + + shield icon + +As explained above, the placeholder ``{icon}`` in the ``src`` +attribute of the ```` element should not be translated. The +``alt`` attribute text (``"shield icon"``) should be. The correctly +translated HTML in Portuguese would be:: + + ícone do escudo + +Attribute ``title`` +""""""""""""""""""" + +Links (````) and abbreviations (````) sometimes rely on +an additional ``title`` attribute. The content of that attribute is +usually shown when placing a cursor over the link or abbreviation. +:: + + Learn how to install it + +It is necessary to translate the contents of any ``title`` attribute. +The correctly translated HTML in Spanish would be:: + + Aprenda cómo instalarlo + +As explained above, the text content ``recommend-tor`` of the ``id`` +attribute in the ```` element should not be translated. Neither +should the ``{url}`` placeholder of ``href`` attribute. Only the text +content of the ``title`` attribute (``"How to install Tor Browser"``) +should be translated. + +Other attributes +"""""""""""""""" + +No attribute other than ``alt`` and ``title`` should be translated. + +In particular, please make sure the attributes ``class``, ``id``, +``height``, ``href``, ``rel``, ``src`` and ``width`` +are never translated. + +.. _how_to_use_language_glossaries_on_weblate: + +How to use the language glossaries on Weblate +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Weblate contains an internal glossary for each language, to which +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. + +|Weblate glossary sidebar screenshot| + +- :ref:`How to translate a phrase on Weblate ` + +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 could add those terms to +the glossary of the language you're working with. + +.. _how_to_add_a_new_language: + +How to add a new language to SecureDrop +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We love seeing SecureDrop translated into new languages. Just ask us +to add yours by posting in the `translation category of the SecureDrop +forum`_. + +.. _weblate_glossary: + +Glossary +-------- + +Weblate contains an internal glossary for each language, to which +we can add suggested translations. Learn more about +:ref:`using language glossaries on Weblate `. + +If a term is missing from the glossary for the language +you're translating into, you can refer to the following +technical glossaries for additional context. Then you can contribute +to improving your own language glossary on Weblate by suggesting +a translation yourself! + +- The :doc:`SecureDrop glossary <../glossary>` explains terms specific + to SecureDrop +- The `EFF Surveillance Self-Defense glossary`_ explains many general + security concepts + +Additionally, here is a list of terms that are specific to the usage of Weblate for SecureDrop. + +.. _weblate_glossary_reviewer: + +Reviewer +^^^^^^^^ + +Reviewers are people who are trusted to review and accept new translations into SecureDrop. + +.. _weblate_glossary_source_string: + +Source string +^^^^^^^^^^^^^ + +On Weblate, the phrases being translated are called *source strings*. (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. Learn :ref:`how to suggest changes to a source string `. + +.. _`Weblate`: https://weblate.org/ +.. _`SecureDrop Weblate instance`: https://weblate.securedrop.org/ +.. _`Weblate registration page`: https://weblate.securedrop.org/accounts/register/ +.. _`Weblate dashboard`: https://weblate.securedrop.org/ +.. _`translation category of the SecureDrop forum`: https://forum.securedrop.org/c/translations +.. _`SecureDrop instant messaging channel`: https://gitter.im/freedomofpress/securedrop +.. _`Weblate documentation`: https://docs.weblate.org/ +.. _`EFF Surveillance Self-Defense glossary`: https://ssd.eff.org/en/glossary/ + +.. |Weblate registration page screenshot| image:: ../images/weblate/registration.png +.. |GitHub authorization page screenshot| image:: ../images/weblate/github-authorization.png +.. |Weblate manage languages screenshot| image:: ../images/weblate/manage-languages.png +.. |Weblate project page screenshot| image:: ../images/weblate/project.png +.. |Weblate translations screenshot| image:: ../images/weblate/translations.png +.. |Weblate translate screenshot| image:: ../images/weblate/translate.png +.. |Weblate glossary sidebar screenshot| image:: ../images/weblate/glossary-sidebar.png +.. |Weblate glossary list screenshot| image:: ../images/weblate/glossary-list.png diff --git a/docs/images/weblate/approved.png b/docs/images/weblate/approved.png deleted file mode 100644 index 8c532b47a..000000000 --- a/docs/images/weblate/approved.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:c86564f275fa442859f7f136124a6bb1f6944d61224ee09a2106fd29242078ec -size 46579 diff --git a/docs/images/weblate/dashboard.png b/docs/images/weblate/dashboard.png deleted file mode 100644 index 43457a371..000000000 --- a/docs/images/weblate/dashboard.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:507c0d88bff020077c23c3306ba27a3b5e1a46a89de0bf53517912865cd2324a -size 104983 diff --git a/docs/images/weblate/waiting-for-review.png b/docs/images/weblate/waiting-for-review.png deleted file mode 100644 index 6739fcf26..000000000 --- a/docs/images/weblate/waiting-for-review.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:90987a05537fc251579311fadde10e3bffc9ee00959b66ae67e28c37164e8609 -size 46613 diff --git a/docs/index.rst b/docs/index.rst index ed27ded70..5ca50b5a2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -116,8 +116,8 @@ anonymous sources. development/contributor_guidelines development/tips_and_tricks development/database_migrations + development/translations development/i18n - development/l10n development/documentation_guidelines development/testing_securedrop development/testing_application_tests From 617cb654a26fb111bfbcaa835811e91669885962 Mon Sep 17 00:00:00 2001 From: Gonzalo Bulnes Guilpain Date: Sun, 28 Mar 2021 20:30:14 +1100 Subject: [PATCH 2/4] Use figures for screenshots, adjust size for readability Using figures instead of images ito enable a full-size link and allow adding captions. Trade-off: unlike the :image: directive, :figure: cannot be used in substituion definitions. Note that setting an explicit width to the image directive is enough to enable to link to the full-size image, but adding a caption makes the feature less likely ot be missed. See https://docutils.sourceforge.io/docs/ref/rst/directives.html#image and https://docutils.sourceforge.io/docs/ref/rst/directives.html#directives-for-substitution-definitions --- docs/development/translations.rst | 65 +++++++++++++++++++++++-------- 1 file changed, 49 insertions(+), 16 deletions(-) diff --git a/docs/development/translations.rst b/docs/development/translations.rst index 0f72b8bca..7f729e560 100644 --- a/docs/development/translations.rst +++ b/docs/development/translations.rst @@ -29,7 +29,12 @@ two translation components: the main SecureDrop web application (labeled "SecureDrop"), and the translations for the desktop icons of the admin and journalist workstations used by news organizations (labeled "desktop"). -|Weblate project page screenshot| +.. figure:: ../images/weblate/project.png + :align: center + :figwidth: 80% + :width: 100% + + Components of the SecureDrop project in Weblate. Click on the image to see it full-size. Once a string is translated, it must be approved by a :ref:`reviewer ` before being accepted into SecureDrop. @@ -103,6 +108,13 @@ How to register an account on Weblate using an email address #. Check your email for a message from **weblate@securedrop.org** with the subject **[Weblate] Your registration on Weblate**. #. That message contains a confirmation link. Click that link to complete your registration. +.. figure:: ../images/weblate/registration.png + :align: center + :figwidth: 80% + :width: 100% + + Weblate registration page. Click on the image to see it full-size. + .. _how_to_register_on_weblate_github: How to register an account on Weblate using a GitHub account @@ -115,7 +127,12 @@ How to register an account on Weblate using a GitHub account The authorization request looks like this: -|GitHub authorization page screenshot| +.. figure:: ../images/weblate/github-authorization.png + :align: center + :figwidth: 50% + :width: 100% + + GitHub authorization request. Click on the image to see it full-size. .. _how_to_manage_your_preferred_languages_weblate: @@ -127,7 +144,12 @@ How to manage your preferred languages on Weblate #. Select the languages your want to translate. #. Click the **Save** button. -|Weblate manage languages screenshot| +.. figure:: ../images/weblate/manage-languages.png + :align: center + :figwidth: 80% + :width: 100% + + Language preferences in Weblate. Click on the image to see it full-size. .. _how_to_translate_a_language_weblate: @@ -139,7 +161,12 @@ How to translate a language on Weblate #. Click the **Translate** button. #. :ref:`Start translating `. -|Weblate translations screenshot| +.. figure:: ../images/weblate/translations.png + :align: center + :figwidth: 80% + :width: 100% + + List of available languages in Weblate. Click on the image to see it full-size. .. _how_to_suggest_changes_to_a_source_string: @@ -165,7 +192,12 @@ How to translate a phrase on Weblate #. Input your translation in the **Translation** test area near the *source string*. #. Click **Save**. The next untranslated string will appear automatically. -|Weblate translate screenshot| +.. figure:: ../images/weblate/translate.png + :align: center + :figwidth: 80% + :width: 100% + + Translating a phrase in Weblate. Click on the image to see it full-size. - :ref:`Learn more about translating phrases with placeholders ` - :ref:`Learn more about translating phrases with HTML code ` @@ -288,9 +320,12 @@ we can add suggested translations. If a :ref:`source string ` + Glossary sidebar in Weblate. Click on the image to see it full-size. If you find that a *source string* contains terms from the :doc:`SecureDrop glossary <../glossary>` or the `EFF Surveillance @@ -316,6 +351,13 @@ Weblate contains an internal glossary for each language, to which we can add suggested translations. Learn more about :ref:`using language glossaries on Weblate `. +.. figure:: ../images/weblate/glossary-list.png + :align: center + :figwidth: 80% + :width: 100% + + A language glossary in Weblate. Click on the image to see it full-size. + If a term is missing from the glossary for the language you're translating into, you can refer to the following technical glossaries for additional context. Then you can contribute @@ -353,12 +395,3 @@ Source strings are English phrases and are automatically extracted from SecureDr .. _`SecureDrop instant messaging channel`: https://gitter.im/freedomofpress/securedrop .. _`Weblate documentation`: https://docs.weblate.org/ .. _`EFF Surveillance Self-Defense glossary`: https://ssd.eff.org/en/glossary/ - -.. |Weblate registration page screenshot| image:: ../images/weblate/registration.png -.. |GitHub authorization page screenshot| image:: ../images/weblate/github-authorization.png -.. |Weblate manage languages screenshot| image:: ../images/weblate/manage-languages.png -.. |Weblate project page screenshot| image:: ../images/weblate/project.png -.. |Weblate translations screenshot| image:: ../images/weblate/translations.png -.. |Weblate translate screenshot| image:: ../images/weblate/translate.png -.. |Weblate glossary sidebar screenshot| image:: ../images/weblate/glossary-sidebar.png -.. |Weblate glossary list screenshot| image:: ../images/weblate/glossary-list.png From e4b86acdeb0874143257c8887f9376a55417830e Mon Sep 17 00:00:00 2001 From: Gonzalo Bulnes Guilpain Date: Wed, 7 Apr 2021 22:04:53 +1000 Subject: [PATCH 3/4] Move 'Getting help' right after introduction --- docs/development/translations.rst | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/development/translations.rst b/docs/development/translations.rst index 7f729e560..73c4821d6 100644 --- a/docs/development/translations.rst +++ b/docs/development/translations.rst @@ -12,6 +12,18 @@ SecureDrop is written in English and translated into multiple other languages. Translations are managed using **Weblate**, a web platform that enables collaborative translation projects. +.. _getting_help_translations: + +Getting help +^^^^^^^^^^^^ + +If you're interested in helping with translation and have questions +about anything in this document, here's how to ask for help: + +* Post a message in the `translation category of the SecureDrop forum`_ +* Chat in the `SecureDrop instant messaging channel`_ +* Read the `Weblate documentation`_ + .. _get_started_using_weblate: Get started using Weblate @@ -46,17 +58,6 @@ SecureDrop translations are a collaborative endeavour! Learn :ref:`how to translate SecureDrop using Weblate `. -.. _getting_help_translations: - -Getting help -^^^^^^^^^^^^ - -Should you need help, you can do one of the following: - -* Post a message in the `translation category of the SecureDrop forum`_ -* Chat in the `SecureDrop instant messaging channel`_ -* Read the `Weblate documentation`_ - Background Information ---------------------- From 62fa97c7079f02198a8a77e2274c2c9da854d754 Mon Sep 17 00:00:00 2001 From: Gonzalo Bulnes Guilpain Date: Wed, 7 Apr 2021 22:06:03 +1000 Subject: [PATCH 4/4] Add 'How to become a reviewer' Fix name of forum category 'Translations' --- docs/development/translations.rst | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/development/translations.rst b/docs/development/translations.rst index 73c4821d6..7abcb04f0 100644 --- a/docs/development/translations.rst +++ b/docs/development/translations.rst @@ -20,7 +20,7 @@ Getting help If you're interested in helping with translation and have questions about anything in this document, here's how to ask for help: -* Post a message in the `translation category of the SecureDrop forum`_ +* Post a message in the `translations category of the SecureDrop forum`_ * Chat in the `SecureDrop instant messaging channel`_ * Read the `Weblate documentation`_ @@ -334,14 +334,21 @@ Self-Defense glossary`_, but the glossary sidebar says ``No related strings foun we'd really appreciate it if you could add those terms to the glossary of the language you're working with. +.. _how_to_become_a_reviewer: + +How to become a reviewer +^^^^^^^^^^^^^^^^^^^^^^^^ + +You can ask to become a reviewer for a language by posting a message +in the `translations category of the SecureDrop forum`_. + .. _how_to_add_a_new_language: How to add a new language to SecureDrop ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ We love seeing SecureDrop translated into new languages. Just ask us -to add yours by posting in the `translation category of the SecureDrop -forum`_. +to add yours by posting in the `translations category of the SecureDrop forum`_. .. _weblate_glossary: @@ -378,6 +385,7 @@ Reviewer ^^^^^^^^ Reviewers are people who are trusted to review and accept new translations into SecureDrop. +Learn :ref:`how to become a reviewer `. .. _weblate_glossary_source_string: @@ -392,7 +400,7 @@ Source strings are English phrases and are automatically extracted from SecureDr .. _`SecureDrop Weblate instance`: https://weblate.securedrop.org/ .. _`Weblate registration page`: https://weblate.securedrop.org/accounts/register/ .. _`Weblate dashboard`: https://weblate.securedrop.org/ -.. _`translation category of the SecureDrop forum`: https://forum.securedrop.org/c/translations +.. _`translations category of the SecureDrop forum`: https://forum.securedrop.org/c/translations .. _`SecureDrop instant messaging channel`: https://gitter.im/freedomofpress/securedrop .. _`Weblate documentation`: https://docs.weblate.org/ .. _`EFF Surveillance Self-Defense glossary`: https://ssd.eff.org/en/glossary/