From 0203103e51ddc62e14e73c69921500b699356bff Mon Sep 17 00:00:00 2001 From: Gonzalo Bulnes Guilpain Date: Thu, 28 Jan 2021 00:23:25 +1100 Subject: [PATCH] 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 | 300 ++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 301 insertions(+) create mode 100644 docs/development/translations.rst diff --git a/docs/development/translations.rst b/docs/development/translations.rst new file mode 100644 index 000000000..dedc5b046 --- /dev/null +++ b/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 ` +- :ref:`Register an account on Weblate using a GitHub account ` + +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 ` +- :ref:`Can new languages be added to Securedrop? ` + +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 ` +- :ref:`How to translate a phrase on Weblate ` +- :ref:`Learn more about translating phrases with placeholders ` +- :ref:`Learn more about translating phrases with HTML code ` + +SecureDrop translations are a collaborative endeavour! + +- :ref:`Suggesting changes to source strings ` +- :ref:`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 **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 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 `. + +|Weblate translations screenshot| + +.. _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 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 `_. +* 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. :ref:`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: ````) +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. + +.. _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 diff --git a/docs/index.rst b/docs/index.rst index 11c4a9478..57712fa08 100644 --- a/docs/index.rst +++ b/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