Spike reorganization of docs by Divio's system

To make moving fragments of text easier, I created a new section
in the Developer Documentation called Translations.

I started re-shuffling the content of the l10n page only and
this is still in a very draft state, but I think it gives a clear
enough idea of what using Divio's system to reorganize
the translation docs could look like.

docs/development/translations.rst

@@ -0,0 +1,300 @@
+Translations
+============
+
+Get Started
+-----------
+
+.. _get_started_using_weblate:
+
+Get started using Weblate
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+- :ref:`Register an account on Weblate using an email address <how_to_register_on_weblate_email>`
+- :ref:`Register an account on Weblate using a GitHub account <how_to_register_on_weblate_github>`
+
+You can contribute to any language, but Weblate has some conveniences to make it easier to work with your preferred languages.
+
+- :ref:`Choose your preferred languages on Weblate <how_to_manage_your_preferred_languages_weblate>`
+- :ref:`Can new languages be added to Securedrop? <adding_a_new_language>`
+
+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|
+
+- :ref:`Start translating a language on Weblate <how_to_translate_a_language_weblate>`
+- :ref:`How to translate a phrase on Weblate <how_to_translate_a_phrase_weblate>`
+- :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>`
+
+SecureDrop translations are a collaborative endeavour!
+
+- :ref:`Suggesting changes to source strings <suggesting_changes_to_source_strings>`
+- :ref:`Changing an existing translation <changing_an_existing_translation>`
+
+.. _how_to_get_help_translations:
+
+Getting help about translations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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`_
+
+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 **[email protected]** 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 unless you already are.
+#. 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 <how_to_translate_a_phrase_weblate>`.
+
+|Weblate translations screenshot|
+
+.. _how_to_translate_a_phrase_weblate:
+
+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.
+#. Click **Save**. The next untranslated string will apear automatically.
+
+|Weblate translate screenshot|
+
+
+
+
+
+Reference
+---------
+
+
+
+Background information
+----------------------
+
+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 <https://www.youtube.com/watch?v=oSW2wMWtAMM>`_.
+* Read the `Localization Lab "Ask Me Anything" on SecureDrop <https://www.localizationlab.org/blog/2018/4/20/4bp1j2olispup45z8o2mm5nb5snxm2>`_.
+
+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. :ref:`Get started using Weblate <get_started_using_weblate>`
+
+.. _translating_phrases_with_placeholders:
+
+Translating phrases 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}
+
+
+.. _translating_phrases_with_html:
+
+Translating phrases with HTML code
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some source strings represent HTML that will be presented in the
+SecureDrop web interface.
+
+HTML elements (embraced by in ``<``, ``>``, example: ``<strong>``)
+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 (``<img>``) 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::
+
+  <img src="{icon}" alt="shield icon">
+
+As explained above, the placeholder ``{icon}`` in the ``src``
+attribute of the ``<img>`` element should not be translated. The
+``alt`` attribute text (``"shield icon"``) should be. The correctly
+translated HTML in Portuguese would be::
+
+  <img src="{icon}" alt="ícone do escudo">
+
+Attribute ``title``
+"""""""""""""""""""
+
+Links (``<a>``) and abbreviations (``<abbr>``) sometimes rely on
+an additional ``title`` attribute. The content of that attribute is
+usually shown when placing a cursor over the link or abbreviation.
+::
+
+  <a id="recommend-tor" title="How to install Tor Browser" href="{url}">Learn how to install it</a>
+
+It is necessary to translate the contents of any ``title`` attribute.
+The correctly translated HTML in Spanish would be::
+
+  <a id="recommend-tor" title="Cómo instalar Tor Browser" href="{url}">Aprenda cómo instalarlo</a>
+
+As explained above, the text content ``recommend-tor`` of the ``id``
+attribute in the ``<a>`` 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.
+
+.. _adding_a_new_language:
+
+Can new languages be added 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`_.
+
+.. _suggesting_changes_to_source_strings:
+
+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:
+
+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

docs/index.rst

@@ -115,6 +115,7 @@ anonymous sources.
    development/contributor_guidelines
    development/tips_and_tricks
    development/database_migrations
+   development/translations
    development/i18n
    development/l10n
    development/documentation_guidelines