<commit_before>Getting Started with Weblate Translations
=========================================

SecureDrop is a whistleblower submission system that media
organizations can use to securely accept documents from and
communicate with anonymous sources. For more information, you may be
interested to learn about :doc:`what makes SecureDrop unique
<../what_makes_securedrop_unique>`.

SecureDrop uses the Weblate platform. This page lists detailed
instructions for getting started with the Weblate platform as a
translator. Before starting this guide, you should know which language
you would like to translate.

Who uses SecureDrop?
--------------------

There are two kind 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 be have any technical
background. Journalists using SecureDrop have all received proper
training and know what a PGP public key is, they understand the basic
workflow of SecureDrop.

.. _`Weblate registration page`: https://weblate.securedrop.club/accounts/register/

Register for Weblate
--------------------

Login via GitHub for the first time
...................................

If you already have a GitHub account, go to the `Weblate registration page`_:

|Weblate registration page screenshot|

Click on the octocat icon and agree to login via GitHub.

|GitHub authorization page screenshot|

You will then be redirected to the Weblate dashboard.

|Weblate dashboard screenshot|

Register a Weblate account
..........................

Go to the `Weblate registration page`_

|Weblate registration page screenshot|

Fill the form and click **Register** and check your mail for a
confirmation mail from **<EMAIL>** with the subject
**[Weblate] Your registration on Weblate**. Click the first link to
confirm: you will be redirected to the `Weblate dashboard`_:

|Weblate dashboard screenshot|

.. _`Weblate dashboard`: https://weblate.securedrop.club/

Choose a language
-----------------

From your `Weblate dashboard`_:

|Weblate dashboard screenshot|

Click the **Watched translations** menu and select **Suggested
translations**:

|Weblate suggested translations screenshot|

And click the **translate** button to the right on the line that shows
your native language:

|Weblate translate button screenshot|

Translate a phrase
------------------

Each string to be translated is shown in a **Source** box and you can
translate it right below in the **Translation** text area. When you
are done, click **Save** and another string will be proposed.

|Weblate translate screenshot|

For most strings a screenshot is available on the right side to show
how it looks in context. The screenshot can be displayed in full size
by clicking on it:

|Weblate translate context screenshot|

Placeholders
------------

The strings may contain placeholders between braces: they will be
substituted with actual content at runtime and must be left
unmodified. For instance::

  Edit user {user}

will be displayed to the user as::

  Edit user Jean-Claude

The French translated string should look like::

  Modifier l'utiliser {user}

And it would be **incorrect** to translate the placeholder like so::

  Modifier l'utiliser {utilisateur}

Glossary
--------

A :doc:`glossary <../terminology>` is available to explain the
SecureDrop specific terms. In addition, it is important that some key
terms are understood and precisely translated.

Adversary
.........

Your adversary is the person or organization attempting to undermine
your security goals. Adversaries can be different, depending on the
situation. For instance, you may worry about criminals spying on the
network at a cafe, or your classmates at a school. Often the adversary
is hypothetical.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/adversary>`__

Air gap
.......

A computer or network that is physically isolated from all other
networks, including the Internet, is said to be air-gapped.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/air-gap>`__

Attack
......

In computer security, an attack is a method that can be used to
compromise security, or its actual use. An attacker is the person or
organization using an attack. An attack method is sometimes called an
"exploit."

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/attack>`__

Command line tool (command)
...........................

The "command line" is an ancient way of giving a computer a series of
small, self-contained orders (think of those science fiction movies
where teenage geniuses type long strings of green text onto black
screens). To use a command line tool, the user types a command into a
window called a terminal emulator, hits the return or enter key, and
then receives a textual response in the same window. Windows, Linux
and Apple desktop computers still let you run software using this
interface, and even some mobile phones can do the same with the right
app. The command line can be used to run software pre-packaged with
your operating system. Some downloadable programs, especially
technical utilities, use the command line instead of a more familiar
"icons and buttons" user interface. The command line needn't be scary,
but it does require you to type in exactly the right set of letters
and numbers to get the correct result, and it's often unclear what to
do if the responses don't match your expectations.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/command-line-tool>`__


Cryptography
............

The art of designing secret codes or ciphers that let you send and
receive messages to a recipient without others being able to
understand the message.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/cryptography>`__

Decrypt
.......

Make a secret message or data intelligible. The idea behind encryption
is to make messages that can only be decrypted by the person or people
who are meant to receive them.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/decrypt>`__

Encryption
..........

A process that takes a message and makes it unreadable except to a
person who knows how to decrypt it back into a readable form.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/encryption>`__

Encryption key
..............

An encryption key is a piece of information that is used to convert a
message into an unreadable form. In some cases, you need the same
encryption key to decode the message. In others, the encryption key
and decryption key are different.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/encryption-key>`__

Fingerprint
...........

The keys of public key cryptography are very large numbers, sometimes
a thousand or more digits long. A fingerprint is a much smaller number
or set of numbers and letters that can be used as a unique name for
that key, without having to list all of the key's digits.  So, for
instance, if you and a friend wished to make sure you both had the
same key, you could either spend a long time reading off all the
hundreds of digits in the key, or you could each calculate your key's
fingerprint and compare those instead. The fingerprints presented by
cryptographic software usually consist of around 40 letters and
numbers. If you carefully check that a fingerprint has the right
value, you should be safe against impersonation using a fake key. Some
software tools may offer more convenient alternative ways to verify a
friend's key, but some form of verification needs to happen to prevent
communications providers from easily being able to listen in.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/fingerprint>`__

HTTPS
.....

If you've ever seen a web address spelled out as
“http://www.example.com/”, you'll recognize the “http” bit of this
term. HTTP (hypertext transfer protocol) is the way a web browser on
your machine talks to a remote web server. Unfortunately, standard
http sends text insecurely across the Internet. HTTPS (the S stands
for “secure”) uses encryption to better protect the data you send to
websites, and the information they return to you, from prying eyes.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/https>`__

Key
...

In cryptography, a piece of data which gives you the capability to
encrypt or decrypt a message.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/key>`__

Keyring
.......

If you use public key cryptography, you'll need to keep track of many
keys: your secret, private key, your public key, and the public keys
of everyone you communicate with. The collection of these keys is
often referred to as your keyring.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/keyring>`__

Man-in-the-middle attack (MITM)
..................................

Suppose you believe you were speaking to your friend, Bahram, via
encrypted instant messager. To check it's really him, you ask him to
tell you the city where you first met. "Istanbul" comes the
reply. That's correct! Unfortunately, without you or Bahram knowing,
someone else online has been intercepting all your
communications. When you first connected to Bahram, you actually
connected to this person, and she, in turn, connected to Bahram. When
you think you are asking Bahram a question, she receives your message,
relays the question to Bahram, receives his answer back , and then
sends it to you. Even though you think you are communicating securely
with Bahram, you are, in fact, only communicating securely with the
spy, who is also communicating securely to Bahram! This is the
man-in-the-middle attack. Men-in-the-middle can spy on communications
or even insert false or misleading messages into your
communications. Security-focused internet communications software
needs to defend against the man-in-the-middle attack to be safe
against attackers who have control of any part of the Internet between
two communicators.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/man-middle-attack>`__

Public key encryption
.....................

Traditional encryption systems use the same secret, or key, to encrypt
and decrypt a message. So if I encrypted a file with the password
"<PASSWORD>", you would need both the file and the secret
"bluetonicmonster" to decode it. Public key encryption uses two keys:
one to encrypt, and another to decrypt. This has all kinds of useful
consequences. For one, it means that you can hand out the key to
encrypt messages to you, and as long as you keep the other key secret,
anyone with that key can talk to you securely. The key you hand out
widely is known as the "public key": hence the name of the
technique. Public key encryption is used to encrypt email and files by
Pretty Good Privacy (PGP), OTR for instant messaging, and SSL/TLS for
web browsing.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/public-key-encryption>`__

Two-factor authentication
.........................

"Something you know, and something you have." Login systems that
require only a username and password risk being broken when someone
else can obtain (or guess) those pieces of information. Services that
offer two-factor authentication also require you to provide a separate
confirmation that you are who you say you are. The second factor could
be a one-off secret code, a number generated by a program running on a
mobile device, or a device that you carry and that you can use to
confirm who you are. Companies like banks, and major internet services
like Google, Paypal and Twitter now offer two-factor authentication.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/two-factor-authentication>`__

Weblate glossary
----------------

For each string to be translated, Weblate shows a glossary of terms
and their translation to help unify their translations. For instance
when translating `Please wait for a new two-factor token before
logging in again`, Weblate notices the word `two-factor` is found in
the glossary and displays the translation in the `glossary` to the
right.

|Weblate glossary show page screenshot|

Before translating strings, it is recommended to add all terms in the
`SecureDrop localization glossary <#glossary>`_ by clicking on the pen
in the right corner of the glossary displayed with each translated
string and then `Add new word`:

|Weblate glossary add page screenshot|

When all the terms are in the glossary, it is recommended to take
another look at the full list of terms and verify there is no
duplicate or other mistakes.

|Weblate glossary list page screenshot|

.. tip:: The terms copied from the EFF glossary already have a
         translation in a number of languages.

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 messenging channel`_
* read the `Weblate documentation`_

.. _`translation category of the SecureDrop forum`: https://forum.securedrop.club/c/translations
.. _`SecureDrop instant messenging channel`: https://gitter.im/freedomofpress/securedrop
.. _`Weblate documentation`: http://docs.weblate.org/en/latest/user/index.html


Frequently Asked Questions
--------------------------                                                  

* What if the language I want to translate is not on the list?

  You can send a request for a new language in the `translation
  category of the SecureDrop forum`_. But please make sure the
  language you want is definitely not present!

.. |Weblate registration page screenshot| image:: ../images/weblate/weblate1.png
.. |GitHub authorization page screenshot| image:: ../images/weblate/weblate2.png
.. |Weblate dashboard screenshot| image:: ../images/weblate/weblate3.png
.. |Weblate suggested translations screenshot| image:: ../images/weblate/weblate4.png
.. |Weblate translate button screenshot| image:: ../images/weblate/weblate5.png
.. |Weblate translate screenshot| image:: ../images/weblate/weblate6.png
.. |Weblate translate context screenshot| image:: ../images/weblate/weblate7.png
.. |Weblate glossary show page screenshot| image:: ../images/weblate/glossary1.png
.. |Weblate glossary add page screenshot| image:: ../images/weblate/glossary2.png
.. |Weblate glossary list page screenshot| image:: ../images/weblate/glossary3.png

<commit_msg>docs: l10n instructions about a user navigation<commit_after>Getting Started with Weblate Translations
=========================================

SecureDrop is a whistleblower submission system that media
organizations can use to securely accept documents from and
communicate with anonymous sources. For more information, you may be
interested to learn about :doc:`what makes SecureDrop unique
<../what_makes_securedrop_unique>`.

SecureDrop uses the Weblate platform. This page lists detailed
instructions for getting started with the Weblate platform as a
translator. Before starting this guide, you should know which language
you would like to translate.

Who uses SecureDrop?
--------------------

There are two kind 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 be have any technical
background. Journalists using SecureDrop have all received proper
training and know what a PGP public key is, they understand the basic
workflow of SecureDrop.

.. _`Weblate registration page`: https://weblate.securedrop.club/accounts/register/

Register for Weblate
--------------------

Login via GitHub for the first time
...................................

If you already have a GitHub account, go to the `Weblate registration page`_:

|Weblate registration page screenshot|

Click on the octocat icon and agree to login via GitHub.

|GitHub authorization page screenshot|

You will then be redirected to the Weblate dashboard.

|Weblate dashboard screenshot|

Register a Weblate account
..........................

Go to the `Weblate registration page`_

|Weblate registration page screenshot|

Fill the form and click **Register** and check your mail for a
confirmation mail from **<EMAIL>** with the subject
**[Weblate] Your registration on Weblate**. Click the first link to
confirm: you will be redirected to the `Weblate dashboard`_:

|Weblate dashboard screenshot|

.. _`Weblate dashboard`: https://weblate.securedrop.club/

Choose a language
-----------------

From your `Weblate dashboard`_:

|Weblate dashboard screenshot|

Click the **Watched translations** menu and select **Suggested
translations**:

|Weblate suggested translations screenshot|

And click the **translate** button to the right on the line that shows
your native language:

|Weblate translate button screenshot|

Translate a phrase
------------------

Each string to be translated is shown in a **Source** box and you can
translate it right below in the **Translation** text area. When you
are done, click **Save** and another string will be proposed.

|Weblate translate screenshot|

For most strings a screenshot is available on the right side to show
how it looks in context. The screenshot can be displayed in full size
by clicking on it:

|Weblate translate context screenshot|

Instructions about a user navigation
------------------------------------

The strings may contain instructions relative to the user interface of
a software. The software should be run and the steps verified to find
the translation. For instance::

  ...tap "Set up account"...

must be translated by navigating to the localized interface of Google
Authenticator and using the translation displayed in place of **Set up
account**.

Placeholders
------------

The strings may contain placeholders between braces: they will be
substituted with actual content at runtime and must be left
unmodified. For instance::

  Edit user {user}

will be displayed to the user as::

  Edit user Jean-Claude

The French translated string should look like::

  Modifier l'utiliser {user}

And it would be **incorrect** to translate the placeholder like so::

  Modifier l'utiliser {utilisateur}

Glossary
--------

A :doc:`glossary <../terminology>` is available to explain the
SecureDrop specific terms. In addition, it is important that some key
terms are understood and precisely translated.

Adversary
.........

Your adversary is the person or organization attempting to undermine
your security goals. Adversaries can be different, depending on the
situation. For instance, you may worry about criminals spying on the
network at a cafe, or your classmates at a school. Often the adversary
is hypothetical.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/adversary>`__

Air gap
.......

A computer or network that is physically isolated from all other
networks, including the Internet, is said to be air-gapped.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/air-gap>`__

Attack
......

In computer security, an attack is a method that can be used to
compromise security, or its actual use. An attacker is the person or
organization using an attack. An attack method is sometimes called an
"exploit."

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/attack>`__

Command line tool (command)
...........................

The "command line" is an ancient way of giving a computer a series of
small, self-contained orders (think of those science fiction movies
where teenage geniuses type long strings of green text onto black
screens). To use a command line tool, the user types a command into a
window called a terminal emulator, hits the return or enter key, and
then receives a textual response in the same window. Windows, Linux
and Apple desktop computers still let you run software using this
interface, and even some mobile phones can do the same with the right
app. The command line can be used to run software pre-packaged with
your operating system. Some downloadable programs, especially
technical utilities, use the command line instead of a more familiar
"icons and buttons" user interface. The command line needn't be scary,
but it does require you to type in exactly the right set of letters
and numbers to get the correct result, and it's often unclear what to
do if the responses don't match your expectations.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/command-line-tool>`__


Cryptography
............

The art of designing secret codes or ciphers that let you send and
receive messages to a recipient without others being able to
understand the message.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/cryptography>`__

Decrypt
.......

Make a secret message or data intelligible. The idea behind encryption
is to make messages that can only be decrypted by the person or people
who are meant to receive them.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/decrypt>`__

Encryption
..........

A process that takes a message and makes it unreadable except to a
person who knows how to decrypt it back into a readable form.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/encryption>`__

Encryption key
..............

An encryption key is a piece of information that is used to convert a
message into an unreadable form. In some cases, you need the same
encryption key to decode the message. In others, the encryption key
and decryption key are different.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/encryption-key>`__

Fingerprint
...........

The keys of public key cryptography are very large numbers, sometimes
a thousand or more digits long. A fingerprint is a much smaller number
or set of numbers and letters that can be used as a unique name for
that key, without having to list all of the key's digits.  So, for
instance, if you and a friend wished to make sure you both had the
same key, you could either spend a long time reading off all the
hundreds of digits in the key, or you could each calculate your key's
fingerprint and compare those instead. The fingerprints presented by
cryptographic software usually consist of around 40 letters and
numbers. If you carefully check that a fingerprint has the right
value, you should be safe against impersonation using a fake key. Some
software tools may offer more convenient alternative ways to verify a
friend's key, but some form of verification needs to happen to prevent
communications providers from easily being able to listen in.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/fingerprint>`__

HTTPS
.....

If you've ever seen a web address spelled out as
“http://www.example.com/”, you'll recognize the “http” bit of this
term. HTTP (hypertext transfer protocol) is the way a web browser on
your machine talks to a remote web server. Unfortunately, standard
http sends text insecurely across the Internet. HTTPS (the S stands
for “secure”) uses encryption to better protect the data you send to
websites, and the information they return to you, from prying eyes.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/https>`__

Key
...

In cryptography, a piece of data which gives you the capability to
encrypt or decrypt a message.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/key>`__

Keyring
.......

If you use public key cryptography, you'll need to keep track of many
keys: your secret, private key, your public key, and the public keys
of everyone you communicate with. The collection of these keys is
often referred to as your keyring.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/keyring>`__

Man-in-the-middle attack (MITM)
..................................

Suppose you believe you were speaking to your friend, Bahram, via
encrypted instant messager. To check it's really him, you ask him to
tell you the city where you first met. "Istanbul" comes the
reply. That's correct! Unfortunately, without you or Bahram knowing,
someone else online has been intercepting all your
communications. When you first connected to Bahram, you actually
connected to this person, and she, in turn, connected to Bahram. When
you think you are asking Bahram a question, she receives your message,
relays the question to Bahram, receives his answer back , and then
sends it to you. Even though you think you are communicating securely
with Bahram, you are, in fact, only communicating securely with the
spy, who is also communicating securely to Bahram! This is the
man-in-the-middle attack. Men-in-the-middle can spy on communications
or even insert false or misleading messages into your
communications. Security-focused internet communications software
needs to defend against the man-in-the-middle attack to be safe
against attackers who have control of any part of the Internet between
two communicators.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/man-middle-attack>`__

Public key encryption
.....................

Traditional encryption systems use the same secret, or key, to encrypt
and decrypt a message. So if I encrypted a file with the password
"<PASSWORD>", you would need both the file and the secret
"bluetonicmonster" to decode it. Public key encryption uses two keys:
one to encrypt, and another to decrypt. This has all kinds of useful
consequences. For one, it means that you can hand out the key to
encrypt messages to you, and as long as you keep the other key secret,
anyone with that key can talk to you securely. The key you hand out
widely is known as the "public key": hence the name of the
technique. Public key encryption is used to encrypt email and files by
Pretty Good Privacy (PGP), OTR for instant messaging, and SSL/TLS for
web browsing.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/public-key-encryption>`__

Two-factor authentication
.........................

"Something you know, and something you have." Login systems that
require only a username and password risk being broken when someone
else can obtain (or guess) those pieces of information. Services that
offer two-factor authentication also require you to provide a separate
confirmation that you are who you say you are. The second factor could
be a one-off secret code, a number generated by a program running on a
mobile device, or a device that you carry and that you can use to
confirm who you are. Companies like banks, and major internet services
like Google, Paypal and Twitter now offer two-factor authentication.

This definition was copied from `the EFF glossary <https://ssd.eff.org/en/glossary/two-factor-authentication>`__

Weblate glossary
----------------

For each string to be translated, Weblate shows a glossary of terms
and their translation to help unify their translations. For instance
when translating `Please wait for a new two-factor token before
logging in again`, Weblate notices the word `two-factor` is found in
the glossary and displays the translation in the `glossary` to the
right.

|Weblate glossary show page screenshot|

Before translating strings, it is recommended to add all terms in the
`SecureDrop localization glossary <#glossary>`_ by clicking on the pen
in the right corner of the glossary displayed with each translated
string and then `Add new word`:

|Weblate glossary add page screenshot|

When all the terms are in the glossary, it is recommended to take
another look at the full list of terms and verify there is no
duplicate or other mistakes.

|Weblate glossary list page screenshot|

.. tip:: The terms copied from the EFF glossary already have a
         translation in a number of languages.

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 messenging channel`_
* read the `Weblate documentation`_

.. _`translation category of the SecureDrop forum`: https://forum.securedrop.club/c/translations
.. _`SecureDrop instant messenging channel`: https://gitter.im/freedomofpress/securedrop
.. _`Weblate documentation`: http://docs.weblate.org/en/latest/user/index.html


Frequently Asked Questions
--------------------------                                                  

* What if the language I want to translate is not on the list?

  You can send a request for a new language in the `translation
  category of the SecureDrop forum`_. But please make sure the
  language you want is definitely not present!

.. |Weblate registration page screenshot| image:: ../images/weblate/weblate1.png
.. |GitHub authorization page screenshot| image:: ../images/weblate/weblate2.png
.. |Weblate dashboard screenshot| image:: ../images/weblate/weblate3.png
.. |Weblate suggested translations screenshot| image:: ../images/weblate/weblate4.png
.. |Weblate translate button screenshot| image:: ../images/weblate/weblate5.png
.. |Weblate translate screenshot| image:: ../images/weblate/weblate6.png
.. |Weblate translate context screenshot| image:: ../images/weblate/weblate7.png
.. |Weblate glossary show page screenshot| image:: ../images/weblate/glossary1.png
.. |Weblate glossary add page screenshot| image:: ../images/weblate/glossary2.png
.. |Weblate glossary list page screenshot| image:: ../images/weblate/glossary3.png


{'fraction_non_alphanumeric': 0.08434538902976112, 'fraction_numerical': 0.0008674763112238089, 'mean_word_length': 3.844512687893971, 'pattern_counts': {'":': 2, '<': 47, '<?xml version=': 0, '>': 47, 'https://': 38, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3711081', 'n_tokens_mistral': 7947, 'n_tokens_neox': 7505, 'n_words': 4146}